001// *************************************************************************************************************************** 002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * 003// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * 004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * 005// * with the License. You may obtain a copy of the License at * 006// * * 007// * http://www.apache.org/licenses/LICENSE-2.0 * 008// * * 009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * 010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * 011// * specific language governing permissions and limitations under the License. * 012// *************************************************************************************************************************** 013package org.apache.juneau.serializer.annotation; 014 015import static java.lang.annotation.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.lang.annotation.*; 019 020import org.apache.juneau.*; 021import org.apache.juneau.annotation.*; 022import org.apache.juneau.serializer.*; 023 024/** 025 * Annotation for specifying config properties defined in {@link Serializer}, {@link OutputStreamSerializer}, and {@link WriterSerializer}. 026 * 027 * <p> 028 * Used primarily for specifying bean configuration properties on REST classes and methods. 029 */ 030@Documented 031@Target({TYPE,METHOD}) 032@Retention(RUNTIME) 033@Inherited 034@PropertyStoreApply(SerializerConfigApply.class) 035public @interface SerializerConfig { 036 037 /** 038 * Optional rank for this config. 039 * 040 * <p> 041 * Can be used to override default ordering and application of config annotations. 042 */ 043 int rank() default 0; 044 045 //------------------------------------------------------------------------------------------------------------------- 046 // OutputStreamSerializer 047 //------------------------------------------------------------------------------------------------------------------- 048 049 /** 050 * Configuration property: Binary output format. 051 * 052 * <p> 053 * When using the {@link OutputStreamSerializer#serializeToString(Object)} method on stream-based serializers, this defines the format to use 054 * when converting the resulting byte array to a string. 055 * 056 * <ul class='notes'> 057 * <li> 058 * Possible values: 059 * <ul> 060 * <li><js>"SPACED_HEX"</js> 061 * <li><js>"HEX"</js> (default) 062 * <li><js>"BASE64"</js> 063 * </ul> 064 * <li> 065 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 066 * <li> 067 * A default global value can be set via the system property <js>"OutputStreamSerializer.binaryFormat.s"</js>. 068 * </ul> 069 * 070 * <ul class='seealso'> 071 * <li class='jf'>{@link OutputStreamSerializer#OSSERIALIZER_binaryFormat} 072 * </ul> 073 */ 074 String binaryFormat() default ""; 075 076 //------------------------------------------------------------------------------------------------------------------- 077 // Serializer 078 //------------------------------------------------------------------------------------------------------------------- 079 080 /** 081 * Configuration property: Add <js>"_type"</js> properties when needed. 082 * 083 * <p> 084 * If <js>"true"</js>, then <js>"_type"</js> properties will be added to beans if their type cannot be inferred 085 * through reflection. 086 * 087 * <p> 088 * This is used to recreate the correct objects during parsing if the object types cannot be inferred. 089 * <br>For example, when serializing a <c>Map<String,Object></c> field where the bean class cannot be determined from 090 * the type of the values. 091 * 092 * <p> 093 * Note the differences between the following settings: 094 * <ul> 095 * <li class='jf'>{@link Serializer#SERIALIZER_addRootType} - Affects whether <js>'_type'</js> is added to root node. 096 * <li class='jf'>{@link Serializer#SERIALIZER_addBeanTypes} - Affects whether <js>'_type'</js> is added to any nodes. 097 * </ul> 098 * 099 * <ul class='notes'> 100 * <li> 101 * Possible values: 102 * <ul> 103 * <li><js>"true"</js> 104 * <li><js>"false"</js> (default) 105 * </ul> 106 * <li> 107 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 108 * <li> 109 * A default global value can be set via the system property <js>"Serializer.addBeanTypes.b"</js>. 110 * </ul> 111 * 112 * <ul class='seealso'> 113 * <li class='jf'>{@link Serializer#SERIALIZER_addBeanTypes} 114 * </ul> 115 */ 116 String addBeanTypes() default ""; 117 118 /** 119 * Configuration property: Add type attribute to root nodes. 120 * 121 * <p> 122 * When disabled, it is assumed that the parser knows the exact Java POJO type being parsed, and therefore top-level 123 * type information that might normally be included to determine the data type will not be serialized. 124 * 125 * <p> 126 * For example, when serializing a top-level POJO with a {@link Bean#typeName() @Bean(typeName)} value, a 127 * <js>'_type'</js> attribute will only be added when this setting is enabled. 128 * 129 * <p> 130 * Note the differences between the following settings: 131 * <ul> 132 * <li class='jf'>{@link Serializer#SERIALIZER_addRootType} - Affects whether <js>'_type'</js> is added to root node. 133 * <li class='jf'>{@link Serializer#SERIALIZER_addBeanTypes} - Affects whether <js>'_type'</js> is added to any nodes. 134 * </ul> 135 * 136 * <ul class='notes'> 137 * <li> 138 * Possible values: 139 * <ul> 140 * <li><js>"true"</js> 141 * <li><js>"false"</js> (default) 142 * </ul> 143 * <li> 144 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 145 * <li> 146 * A default global value can be set via the system property <js>"Serializer.addRootType.b"</js>. 147 * </ul> 148 * 149 * <ul class='seealso'> 150 * <li class='jf'>{@link Serializer#SERIALIZER_addRootType} 151 * </ul> 152 */ 153 String addRootType() default ""; 154 155 /** 156 * Configuration property: Serializer listener. 157 * 158 * <p> 159 * Class used to listen for errors and warnings that occur during serialization. 160 * 161 * <ul class='seealso'> 162 * <li class='jf'>{@link Serializer#SERIALIZER_listener} 163 * </ul> 164 */ 165 Class<? extends SerializerListener> listener() default SerializerListener.Null.class; 166 167 /** 168 * Configuration property: Sort arrays and collections alphabetically. 169 * 170 * <p> 171 * Copies and sorts the contents of arrays and collections before serializing them. 172 * 173 * <p> 174 * Note that this introduces a performance penalty. 175 * 176 * <ul class='notes'> 177 * <li> 178 * Possible values: 179 * <ul> 180 * <li><js>"true"</js> 181 * <li><js>"false"</js> (default) 182 * </ul> 183 * <li> 184 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 185 * <li> 186 * A default global value can be set via the system property <js>"Serializer.sortCollections.b"</js>. 187 * </ul> 188 * 189 * <ul class='seealso'> 190 * <li class='jf'>{@link Serializer#SERIALIZER_sortCollections} 191 * </ul> 192 */ 193 String sortCollections() default ""; 194 195 /** 196 * Configuration property: Sort maps alphabetically. 197 * 198 * <p> 199 * Copies and sorts the contents of maps by their keys before serializing them. 200 * 201 * <p> 202 * Note that this introduces a performance penalty. 203 * 204 * <ul class='notes'> 205 * <li> 206 * Possible values: 207 * <ul> 208 * <li><js>"true"</js> 209 * <li><js>"false"</js> (default) 210 * </ul> 211 * <li> 212 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 213 * <li> 214 * A default global value can be set via the system property <js>"Serializer.sortMaps.b"</js>. 215 * </ul> 216 * 217 * <ul class='seealso'> 218 * <li class='jf'>{@link Serializer#SERIALIZER_sortMaps} 219 * </ul> 220 */ 221 String sortMaps() default ""; 222 223 /** 224 * Configuration property: Trim empty lists and arrays. 225 * 226 * <p> 227 * If <js>"true"</js>, empty lists and arrays will not be serialized. 228 * 229 * <p> 230 * Note that enabling this setting has the following effects on parsing: 231 * <ul class='spaced-list'> 232 * <li> 233 * Map entries with empty list values will be lost. 234 * <li> 235 * Bean properties with empty list values will not be set. 236 * </ul> 237 * 238 * <ul class='notes'> 239 * <li> 240 * Possible values: 241 * <ul> 242 * <li><js>"true"</js> 243 * <li><js>"false"</js> (default) 244 * </ul> 245 * <li> 246 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 247 * <li> 248 * A default global value can be set via the system property <js>"Serializer.trimEmptyCollections.b"</js>. 249 * </ul> 250 * 251 * <ul class='seealso'> 252 * <li class='jf'>{@link Serializer#SERIALIZER_trimEmptyCollections} 253 * </ul> 254 */ 255 String trimEmptyCollections() default ""; 256 257 /** 258 * Configuration property: Trim empty maps. 259 * 260 * <p> 261 * If <js>"true"</js>, empty map values will not be serialized to the output. 262 * 263 * <p> 264 * Note that enabling this setting has the following effects on parsing: 265 * <ul class='spaced-list'> 266 * <li> 267 * Bean properties with empty map values will not be set. 268 * </ul> 269 * 270 * <ul class='notes'> 271 * <li> 272 * Possible values: 273 * <ul> 274 * <li><js>"true"</js> 275 * <li><js>"false"</js> (default) 276 * </ul> 277 * <li> 278 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 279 * <li> 280 * A default global value can be set via the system property <js>"Serializer.trimEmptyMaps.b"</js>. 281 * </ul> 282 * 283 * <ul class='seealso'> 284 * <li class='jf'>{@link Serializer#SERIALIZER_trimEmptyMaps} 285 * </ul> 286 */ 287 String trimEmptyMaps() default ""; 288 289 /** 290 * Configuration property: Trim null bean property values. 291 * 292 * <p> 293 * If <js>"true"</js>, null bean values will not be serialized to the output. 294 * 295 * <p> 296 * Note that enabling this setting has the following effects on parsing: 297 * <ul class='spaced-list'> 298 * <li> 299 * Map entries with <jk>null</jk> values will be lost. 300 * </ul> 301 * 302 * <ul class='notes'> 303 * <li> 304 * Possible values: 305 * <ul> 306 * <li><js>"true"</js> (default) 307 * <li><js>"false"</js> 308 * </ul> 309 * <li> 310 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 311 * <li> 312 * A default global value can be set via the system property <js>"Serializer.trimNullProperties.b"</js>. 313 * </ul> 314 * 315 * <ul class='seealso'> 316 * <li class='jf'>{@link Serializer#SERIALIZER_trimNullProperties} 317 * </ul> 318 */ 319 String trimNullProperties() default ""; 320 321 /** 322 * Configuration property: Trim strings. 323 * 324 * <p> 325 * If <js>"true"</js>, string values will be trimmed of whitespace using {@link String#trim()} before being serialized. 326 * 327 * <ul class='notes'> 328 * <li> 329 * Possible values: 330 * <ul> 331 * <li><js>"true"</js> 332 * <li><js>"false"</js> (default) 333 * </ul> 334 * <li> 335 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 336 * <li> 337 * A default global value can be set via the system property <js>"Serializer.trimStrings.b"</js>. 338 * </ul> 339 * 340 * <ul class='seealso'> 341 * <li class='jf'>{@link Serializer#SERIALIZER_trimStrings} 342 * </ul> 343 */ 344 String trimStrings() default ""; 345 346 /** 347 * Configuration property: URI context bean. 348 * 349 * <h5 class='section'>Description:</h5> 350 * <p> 351 * Bean used for resolution of URIs to absolute or root-relative form. 352 * 353 * <ul class='notes'> 354 * <li> 355 * Format: JSON object representing a {@link UriContext} 356 * <li> 357 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 358 * <li> 359 * A default global value can be set via the system property <js>"Serializer.uriContext.s"</js>. 360 * </ul> 361 * 362 * <ul class='seealso'> 363 * <li class='jf'>{@link Serializer#SERIALIZER_uriContext} 364 * </ul> 365 */ 366 String uriContext() default ""; 367 368 /** 369 * Configuration property: URI relativity. 370 * 371 * <p> 372 * Defines what relative URIs are relative to when serializing any of the following: 373 * <ul> 374 * <li>{@link java.net.URI} 375 * <li>{@link java.net.URL} 376 * <li>Properties and classes annotated with {@link org.apache.juneau.annotation.URI @URI} 377 * </ul> 378 * 379 * <ul class='notes'> 380 * <li> 381 * Possible values: 382 * <ul> 383 * <li><js>"RESOURCE"</js> (default) - Relative URIs should be considered relative to the servlet URI. 384 * <li><js>"PATH_INFO"</js> - Relative URIs should be considered relative to the request URI. 385 * </ul> 386 * <li> 387 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 388 * <li> 389 * A default global value can be set via the system property <js>"Serializer.uriRelativity.s"</js>. 390 * </ul> 391 * 392 * <ul class='seealso'> 393 * <li class='jf'>{@link Serializer#SERIALIZER_uriRelativity} 394 * <li class='link'>{@doc juneau-marshall.URIs} 395 * </ul> 396 */ 397 String uriRelativity() default ""; 398 399 /** 400 * Configuration property: URI resolution. 401 * 402 * <p> 403 * Defines the resolution level for URIs when serializing any of the following: 404 * <ul> 405 * <li>{@link java.net.URI} 406 * <li>{@link java.net.URL} 407 * <li>Properties and classes annotated with {@link org.apache.juneau.annotation.URI @URI} 408 * </ul> 409 * 410 * <ul class='notes'> 411 * <li> 412 * Possible values: 413 * <ul> 414 * <li><js>"ABSOLUTE"</js> - Resolve to an absolute URL (e.g. <js>"http://host:port/context-root/servlet-path/path-info"</js>). 415 * <li><js>"ROOT_RELATIVE"</js> - Resolve to a root-relative URL (e.g. <js>"/context-root/servlet-path/path-info"</js>). 416 * <li><js>"NONE"</js> (default) - Don't do any URL resolution. 417 * </ul> 418 * <li> 419 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 420 * <li> 421 * A default global value can be set via the system property <js>"Serializer.uriResolution.s"</js>. 422 * </ul> 423 * 424 * <ul class='seealso'> 425 * <li class='jf'>{@link Serializer#SERIALIZER_uriResolution} 426 * <li class='link'>{@doc juneau-marshall.URIs} 427 * </ul> 428 */ 429 String uriResolution() default ""; 430 431 //------------------------------------------------------------------------------------------------------------------- 432 // WriterSerializer 433 //------------------------------------------------------------------------------------------------------------------- 434 435 /** 436 * Configuration property: File charset. 437 * 438 * <p> 439 * The character set to use for writing Files to the file system. 440 * 441 * <p> 442 * Used when passing in files to {@link Serializer#serialize(Object, Object)}. 443 * 444 * <ul class='notes'> 445 * <li> 446 * Format: string 447 * <li> 448 * "DEFAULT" can be used to indicate the JVM default file system charset. 449 * <li> 450 * Default: JVM system default. 451 * <li> 452 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 453 * <li> 454 * A default global value can be set via the system property <js>"WriterSerializer.fileCharset.s"</js>. 455 * <li> 456 * This setting does not apply to the RDF serializers. 457 * </ul> 458 * 459 * <ul class='seealso'> 460 * <li class='jf'>{@link WriterSerializer#WSERIALIZER_fileCharset} 461 * </ul> 462 */ 463 String fileCharset() default ""; 464 465 /** 466 * Configuration property: Maximum indentation. 467 * 468 * <p> 469 * Specifies the maximum indentation level in the serialized document. 470 * 471 * <ul class='notes'> 472 * <li> 473 * Format: integer 474 * <li> 475 * Default: 100 476 * <li> 477 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 478 * <li> 479 * A default global value can be set via the system property <js>"WriterSerializer.maxIndent.i"</js>. 480 * <li> 481 * This setting does not apply to the RDF serializers. 482 * </ul> 483 * 484 * <ul class='seealso'> 485 * <li class='jf'>{@link WriterSerializer#WSERIALIZER_maxIndent} 486 * </ul> 487 */ 488 String maxIndent() default ""; 489 490 /** 491 * Configuration property: Quote character. 492 * 493 * <p> 494 * This is the character used for quoting attributes and values. 495 * 496 * <ul class='notes'> 497 * <li> 498 * Default: " 499 * <li> 500 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 501 * <li> 502 * A default global value can be set via the system property <js>"WriterSerializer.quoteChar.s"</js>. 503 * <li> 504 * This setting does not apply to the RDF serializers. 505 * </ul> 506 * 507 * <ul class='seealso'> 508 * <li class='jf'>{@link WriterSerializer#WSERIALIZER_quoteChar} 509 * </ul> 510 */ 511 String quoteChar() default ""; 512 513 /** 514 * Configuration property: Output stream charset. 515 * 516 * <p> 517 * The character set to use when writing to OutputStreams. 518 * 519 * <p> 520 * Used when passing in output streams and byte arrays to {@link WriterSerializer#serialize(Object, Object)}. 521 * 522 * <ul class='notes'> 523 * <li> 524 * Format: string 525 * <li> 526 * Default: <js>"utf-8"</js>. 527 * <li> 528 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 529 * <li> 530 * A default global value can be set via the system property <js>"WriterSerializer.streamCharset.s"</js>. 531 * <li> 532 * This setting does not apply to the RDF serializers. 533 * </ul> 534 * 535 * <ul class='seealso'> 536 * <li class='jf'>{@link WriterSerializer#WSERIALIZER_streamCharset} 537 * </ul> 538 */ 539 String streamCharset() default ""; 540 541 /** 542 * Configuration property: Use whitespace. 543 * 544 * <p> 545 * If <js>"true"</js>, whitespace is added to the output to improve readability. 546 * 547 * <ul class='notes'> 548 * <li> 549 * Possible values: 550 * <ul> 551 * <li><js>"true"</js> 552 * <li><js>"false"</js> (default) 553 * </ul> 554 * <li> 555 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 556 * <li> 557 * A default global value can be set via the system property <js>"Serializer.useWhitespace.b"</js>. 558 * </ul> 559 * 560 * <ul class='seealso'> 561 * <li class='jf'>{@link WriterSerializer#WSERIALIZER_useWhitespace} 562 * </ul> 563 */ 564 String useWhitespace() default ""; 565}