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 * </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 DefaultSvlVariables} (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 DefaultSvlVariables} (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: Serializer listener. 151 * 152 * <p> 153 * Class used to listen for errors and warnings that occur during serialization. 154 * 155 * <ul class='seealso'> 156 * <li class='jf'>{@link Serializer#SERIALIZER_listener} 157 * </ul> 158 */ 159 Class<? extends SerializerListener> listener() default SerializerListener.Null.class; 160 161 /** 162 * Configuration property: Sort arrays and collections alphabetically. 163 * 164 * <p> 165 * Copies and sorts the contents of arrays and collections before serializing them. 166 * 167 * <p> 168 * Note that this introduces a performance penalty. 169 * 170 * <ul class='notes'> 171 * <li> 172 * Possible values: 173 * <ul> 174 * <li><js>"true"</js> 175 * <li><js>"false"</js> (default) 176 * </ul> 177 * <li> 178 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</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 * </ul> 206 * 207 * <ul class='seealso'> 208 * <li class='jf'>{@link Serializer#SERIALIZER_sortMaps} 209 * </ul> 210 */ 211 String sortMaps() default ""; 212 213 /** 214 * Configuration property: Trim empty lists and arrays. 215 * 216 * <p> 217 * If <js>"true"</js>, empty lists and arrays will not be serialized. 218 * 219 * <p> 220 * Note that enabling this setting has the following effects on parsing: 221 * <ul class='spaced-list'> 222 * <li> 223 * Map entries with empty list values will be lost. 224 * <li> 225 * Bean properties with empty list values will not be set. 226 * </ul> 227 * 228 * <ul class='notes'> 229 * <li> 230 * Possible values: 231 * <ul> 232 * <li><js>"true"</js> 233 * <li><js>"false"</js> (default) 234 * </ul> 235 * <li> 236 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 237 * </ul> 238 * 239 * <ul class='seealso'> 240 * <li class='jf'>{@link Serializer#SERIALIZER_trimEmptyCollections} 241 * </ul> 242 */ 243 String trimEmptyCollections() default ""; 244 245 /** 246 * Configuration property: Trim empty maps. 247 * 248 * <p> 249 * If <js>"true"</js>, empty map values will not be serialized to the output. 250 * 251 * <p> 252 * Note that enabling this setting has the following effects on parsing: 253 * <ul class='spaced-list'> 254 * <li> 255 * Bean properties with empty map 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 DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 267 * </ul> 268 * 269 * <ul class='seealso'> 270 * <li class='jf'>{@link Serializer#SERIALIZER_trimEmptyMaps} 271 * </ul> 272 */ 273 String trimEmptyMaps() default ""; 274 275 /** 276 * Configuration property: Trim null bean property values. 277 * 278 * <p> 279 * If <js>"true"</js>, null bean 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 * Map entries with <jk>null</jk> values will be lost. 286 * </ul> 287 * 288 * <ul class='notes'> 289 * <li> 290 * Possible values: 291 * <ul> 292 * <li><js>"true"</js> (default) 293 * <li><js>"false"</js> 294 * </ul> 295 * <li> 296 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 297 * </ul> 298 * 299 * <ul class='seealso'> 300 * <li class='jf'>{@link Serializer#SERIALIZER_trimNullProperties} 301 * </ul> 302 */ 303 String trimNullProperties() default ""; 304 305 /** 306 * Configuration property: Trim strings. 307 * 308 * <p> 309 * If <js>"true"</js>, string values will be trimmed of whitespace using {@link String#trim()} before being serialized. 310 * 311 * <ul class='notes'> 312 * <li> 313 * Possible values: 314 * <ul> 315 * <li><js>"true"</js> 316 * <li><js>"false"</js> (default) 317 * </ul> 318 * <li> 319 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 320 * </ul> 321 * 322 * <ul class='seealso'> 323 * <li class='jf'>{@link Serializer#SERIALIZER_trimStrings} 324 * </ul> 325 */ 326 String trimStrings() default ""; 327 328 /** 329 * Configuration property: URI context bean. 330 * 331 * <h5 class='section'>Description:</h5> 332 * <p> 333 * Bean used for resolution of URIs to absolute or root-relative form. 334 * 335 * <ul class='notes'> 336 * <li> 337 * Format: JSON object representing a {@link UriContext} 338 * <li> 339 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 340 * </ul> 341 * 342 * <ul class='seealso'> 343 * <li class='jf'>{@link Serializer#SERIALIZER_uriContext} 344 * </ul> 345 */ 346 String uriContext() default ""; 347 348 /** 349 * Configuration property: URI relativity. 350 * 351 * <p> 352 * Defines what relative URIs are relative to when serializing any of the following: 353 * <ul> 354 * <li>{@link java.net.URI} 355 * <li>{@link java.net.URL} 356 * <li>Properties and classes annotated with {@link org.apache.juneau.annotation.URI @URI} 357 * </ul> 358 * 359 * <ul class='notes'> 360 * <li> 361 * Possible values: 362 * <ul> 363 * <li><js>"RESOURCE"</js> (default) - Relative URIs should be considered relative to the servlet URI. 364 * <li><js>"PATH_INFO"</js> - Relative URIs should be considered relative to the request URI. 365 * </ul> 366 * <li> 367 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 368 * </ul> 369 * 370 * <ul class='seealso'> 371 * <li class='jf'>{@link Serializer#SERIALIZER_uriRelativity} 372 * <li class='link'>{@doc juneau-marshall.URIs} 373 * </ul> 374 */ 375 String uriRelativity() default ""; 376 377 /** 378 * Configuration property: URI resolution. 379 * 380 * <p> 381 * Defines the resolution level for URIs when serializing any of the following: 382 * <ul> 383 * <li>{@link java.net.URI} 384 * <li>{@link java.net.URL} 385 * <li>Properties and classes annotated with {@link org.apache.juneau.annotation.URI @URI} 386 * </ul> 387 * 388 * <ul class='notes'> 389 * <li> 390 * Possible values: 391 * <ul> 392 * <li><js>"ABSOLUTE"</js> - Resolve to an absolute URL (e.g. <js>"http://host:port/context-root/servlet-path/path-info"</js>). 393 * <li><js>"ROOT_RELATIVE"</js> - Resolve to a root-relative URL (e.g. <js>"/context-root/servlet-path/path-info"</js>). 394 * <li><js>"NONE"</js> (default) - Don't do any URL resolution. 395 * </ul> 396 * <li> 397 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 398 * </ul> 399 * 400 * <ul class='seealso'> 401 * <li class='jf'>{@link Serializer#SERIALIZER_uriResolution} 402 * <li class='link'>{@doc juneau-marshall.URIs} 403 * </ul> 404 */ 405 String uriResolution() default ""; 406 407 //------------------------------------------------------------------------------------------------------------------- 408 // WriterSerializer 409 //------------------------------------------------------------------------------------------------------------------- 410 411 /** 412 * Configuration property: File charset. 413 * 414 * <p> 415 * The character set to use for writing Files to the file system. 416 * 417 * <p> 418 * Used when passing in files to {@link Serializer#serialize(Object, Object)}. 419 * 420 * <ul class='notes'> 421 * <li> 422 * Format: string 423 * <li> 424 * "DEFAULT" can be used to indicate the JVM default file system charset. 425 * <li> 426 * Default: JVM system default. 427 * <li> 428 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 429 * <li> 430 * This setting does not apply to the RDF serializers. 431 * </ul> 432 * 433 * <ul class='seealso'> 434 * <li class='jf'>{@link WriterSerializer#WSERIALIZER_fileCharset} 435 * </ul> 436 */ 437 String fileCharset() default ""; 438 439 /** 440 * Configuration property: Maximum indentation. 441 * 442 * <p> 443 * Specifies the maximum indentation level in the serialized document. 444 * 445 * <ul class='notes'> 446 * <li> 447 * Format: integer 448 * <li> 449 * Default: 100 450 * <li> 451 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 452 * <li> 453 * This setting does not apply to the RDF serializers. 454 * </ul> 455 * 456 * <ul class='seealso'> 457 * <li class='jf'>{@link WriterSerializer#WSERIALIZER_maxIndent} 458 * </ul> 459 */ 460 String maxIndent() default ""; 461 462 /** 463 * Configuration property: Quote character. 464 * 465 * <p> 466 * This is the character used for quoting attributes and values. 467 * 468 * <ul class='notes'> 469 * <li> 470 * Default: <c>"</c> 471 * <li> 472 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 473 * <li> 474 * This setting does not apply to the RDF serializers. 475 * </ul> 476 * 477 * <ul class='seealso'> 478 * <li class='jf'>{@link WriterSerializer#WSERIALIZER_quoteChar} 479 * </ul> 480 */ 481 String quoteChar() default ""; 482 483 /** 484 * Configuration property: Output stream charset. 485 * 486 * <p> 487 * The character set to use when writing to OutputStreams. 488 * 489 * <p> 490 * Used when passing in output streams and byte arrays to {@link WriterSerializer#serialize(Object, Object)}. 491 * 492 * <ul class='notes'> 493 * <li> 494 * Format: string 495 * <li> 496 * Default: <js>"utf-8"</js>. 497 * <li> 498 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 499 * <li> 500 * This setting does not apply to the RDF serializers. 501 * </ul> 502 * 503 * <ul class='seealso'> 504 * <li class='jf'>{@link WriterSerializer#WSERIALIZER_streamCharset} 505 * </ul> 506 */ 507 String streamCharset() default ""; 508 509 /** 510 * Configuration property: Use whitespace. 511 * 512 * <p> 513 * If <js>"true"</js>, whitespace is added to the output to improve readability. 514 * 515 * <ul class='notes'> 516 * <li> 517 * Possible values: 518 * <ul> 519 * <li><js>"true"</js> 520 * <li><js>"false"</js> (default) 521 * </ul> 522 * <li> 523 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 524 * </ul> 525 * 526 * <ul class='seealso'> 527 * <li class='jf'>{@link WriterSerializer#WSERIALIZER_useWhitespace} 528 * </ul> 529 */ 530 String useWhitespace() default ""; 531}