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