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