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.annotation; 014 015import static java.lang.annotation.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.io.*; 019import java.lang.annotation.*; 020import java.lang.reflect.*; 021import java.util.*; 022 023import org.apache.juneau.*; 024import org.apache.juneau.parser.*; 025import org.apache.juneau.serializer.*; 026import org.apache.juneau.transform.*; 027 028/** 029 * Annotation for specifying config properties defined in {@link BeanContext} and {@link BeanTraverseContext}. 030 * 031 * <p> 032 * Used primarily for specifying bean configuration properties on REST classes and methods. 033 */ 034@Documented 035@Target({TYPE,METHOD}) 036@Retention(RUNTIME) 037@Inherited 038@PropertyStoreApply(BeanConfigApply.class) 039public @interface BeanConfig { 040 041 /** 042 * Optional rank for this config. 043 * 044 * <p> 045 * Can be used to override default ordering and application of config annotations. 046 */ 047 int rank() default 0; 048 049 //----------------------------------------------------------------------------------------------------------------- 050 // BeanContext 051 //----------------------------------------------------------------------------------------------------------------- 052 053 /** 054 * Dynamically applies {@link Bean @Bean} annotations to specified classes. 055 * 056 * <p> 057 * Provides an alternate approach for applying annotations using {@link Bean#on() @Bean.on} to specify the names 058 * to apply the annotation to. 059 * 060 * <ul class='seealso'> 061 * <li class='link'>{@doc DynamicallyAppliedAnnotations} 062 * </ul> 063 */ 064 Bean[] applyBean() default {}; 065 066 /** 067 * Dynamically applies {@link Beanc @Beanc} annotations to specified constructors. 068 * 069 * <p> 070 * Provides an alternate approach for applying annotations using {@link Beanc#on() @Beanc.on} to specify the names 071 * to apply the annotation to. 072 * 073 * <ul class='seealso'> 074 * <li class='link'>{@doc DynamicallyAppliedAnnotations} 075 * </ul> 076 */ 077 Beanc[] applyBeanc() default {}; 078 079 /** 080 * Dynamically applies {@link Beanp @Beanp} annotations to specified methods. 081 * 082 * <p> 083 * Provides an alternate approach for applying annotations using {@link Beanp#on() @Beanp.on} to specify the names 084 * to apply the annotation to. 085 * 086 * <ul class='seealso'> 087 * <li class='link'>{@doc DynamicallyAppliedAnnotations} 088 * </ul> 089 */ 090 Beanp[] applyBeanp() default {}; 091 092 /** 093 * Dynamically applies {@link BeanIgnore @BeanIgnore} annotations to specified classes/methods/fields/constructors. 094 * 095 * <p> 096 * Provides an alternate approach for applying annotations using {@link BeanIgnore#on() @BeanIgnore.on} to specify the names 097 * to apply the annotation to. 098 * 099 * <ul class='seealso'> 100 * <li class='link'>{@doc DynamicallyAppliedAnnotations} 101 * </ul> 102 */ 103 BeanIgnore[] applyBeanIgnore() default {}; 104 105 /** 106 * Dynamically applies {@link Example @Example} annotations to specified classes/methods/fields. 107 * 108 * <p> 109 * Provides an alternate approach for applying annotations using {@link Example#on() @Example.on} to specify the names 110 * to apply the annotation to. 111 * 112 * <ul class='seealso'> 113 * <li class='link'>{@doc DynamicallyAppliedAnnotations} 114 * </ul> 115 */ 116 Example[] applyExample() default {}; 117 118 /** 119 * Dynamically applies {@link NameProperty @NameProperty} annotations to specified methods/fields. 120 * 121 * <p> 122 * Provides an alternate approach for applying annotations using {@link NameProperty#on() @NameProperty.on} to specify the names 123 * to apply the annotation to. 124 * 125 * <ul class='seealso'> 126 * <li class='link'>{@doc DynamicallyAppliedAnnotations} 127 * </ul> 128 */ 129 NameProperty[] applyNameProperty() default {}; 130 131 /** 132 * Dynamically applies {@link ParentProperty @ParentProperty} annotations to specified methods/fields. 133 * 134 * <p> 135 * Provides an alternate approach for applying annotations using {@link ParentProperty#on() @ParentProperty.on} to specify the names 136 * to apply the annotation to. 137 * 138 * <ul class='seealso'> 139 * <li class='link'>{@doc DynamicallyAppliedAnnotations} 140 * </ul> 141 */ 142 ParentProperty[] applyParentProperty() default {}; 143 144 /** 145 * Dynamically applies {@link Swap @Swap} annotations to specified classes/methods/fields. 146 * 147 * <p> 148 * Provides an alternate approach for applying annotations using {@link Swap#on() @Swap.on} to specify the names 149 * to apply the annotation to. 150 * 151 * <ul class='seealso'> 152 * <li class='link'>{@doc DynamicallyAppliedAnnotations} 153 * </ul> 154 */ 155 Swap[] applySwap() default {}; 156 157 /** 158 * Dynamically applies {@link URI @URI} annotations to specified classes/methods/fields. 159 * 160 * <p> 161 * Provides an alternate approach for applying annotations using {@link URI#on() @URI.on} to specify the names 162 * to apply the annotation to. 163 * 164 * <ul class='seealso'> 165 * <li class='link'>{@doc DynamicallyAppliedAnnotations} 166 * </ul> 167 */ 168 URI[] applyURI() default {}; 169 170 /** 171 * Configuration property: Minimum bean class visibility. 172 * 173 * <p> 174 * Classes are not considered beans unless they meet the minimum visibility requirements. 175 * 176 * <p> 177 * For example, if the visibility is <c>PUBLIC</c> and the bean class is <jk>protected</jk>, then the class 178 * will not be interpreted as a bean class and be serialized as a string. 179 * <br>Use this setting to reduce the visibility requirement. 180 * 181 * <ul class='notes'> 182 * <li> 183 * Possible values: 184 * <ul> 185 * <li><js>"PUBLIC"</js> (default) 186 * <li><js>"PROTECTED"</js> 187 * <li><js>"DEFAULT"</js> 188 * <li><js>"PRIVATE"</js> 189 * </ul> 190 * <li> 191 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 192 * </ul> 193 * 194 * <ul class='seealso'> 195 * <li class='jf'>{@link BeanContext#BEAN_beanClassVisibility} 196 * </ul> 197 */ 198 String beanClassVisibility() default ""; 199 200 /** 201 * Configuration property: Minimum bean constructor visibility. 202 * 203 * <p> 204 * Only look for constructors with the specified minimum visibility. 205 * 206 * <p> 207 * This setting affects the logic for finding no-arg constructors for bean. 208 * <br>Normally, only <jk>public</jk> no-arg constructors are used. 209 * <br>Use this setting if you want to reduce the visibility requirement. 210 * 211 * <ul class='notes'> 212 * <li> 213 * Possible values: 214 * <ul> 215 * <li><js>"PUBLIC"</js> (default) 216 * <li><js>"PROTECTED"</js> 217 * <li><js>"DEFAULT"</js> 218 * <li><js>"PRIVATE"</js> 219 * </ul> 220 * <li> 221 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 222 * </ul> 223 * 224 * <ul class='seealso'> 225 * <li class='jf'>{@link BeanContext#BEAN_beanConstructorVisibility} 226 * </ul> 227 */ 228 String beanConstructorVisibility() default ""; 229 230 /** 231 * Configuration property: Bean dictionary. 232 * 233 * <p> 234 * The list of classes that make up the bean dictionary in this bean context. 235 * 236 * <p> 237 * A dictionary is a name/class mapping used to find class types during parsing when they cannot be inferred 238 * through reflection. 239 * <br>The names are defined through the {@link Bean#typeName() @Bean(typeName)} annotation defined on the bean class. 240 * <br>For example, if a class <c>Foo</c> has a type-name of <js>"myfoo"</js>, then it would end up serialized 241 * as <js>"{_type:'myfoo',...}"</js>. 242 * 243 * <p> 244 * This setting tells the parsers which classes to look for when resolving <js>"_type"</js> attributes. 245 * 246 * <ul class='seealso'> 247 * <li class='jf'>{@link BeanContext#BEAN_beanDictionary} 248 * <li class='link'>{@doc BeanDictionaries} 249 * </ul> 250 * 251 * <div class='warn'> 252 * <b>Deprecated</b> - Use {@link #dictionary()}. 253 * </div> 254 */ 255 @Deprecated 256 Class<?>[] beanDictionary() default {}; 257 258 /** 259 * Configuration property: Add to bean dictionary. 260 * 261 * <ul class='seealso'> 262 * <li class='jf'>{@link BeanContext#BEAN_beanDictionary} 263 * </ul> 264 * 265 * <div class='warn'> 266 * <b>Deprecated</b> - Use {@link #dictionary_replace()}. 267 * </div> 268 */ 269 @Deprecated 270 Class<?>[] beanDictionary_replace() default {}; 271 272 /** 273 * Configuration property: Remove from bean dictionary. 274 * 275 * <ul class='seealso'> 276 * <li class='jf'>{@link BeanContext#BEAN_beanDictionary_remove} 277 * </ul> 278 * 279 * <div class='warn'> 280 * <b>Deprecated</b> - Use {@link #dictionary_remove()}. 281 * </div> 282 */ 283 @Deprecated 284 Class<?>[] beanDictionary_remove() default {}; 285 286 /** 287 * Configuration property: Minimum bean field visibility. 288 * 289 * <p> 290 * Only look for bean fields with the specified minimum visibility. 291 * 292 * <p> 293 * This affects which fields on a bean class are considered bean properties. 294 * <br>Normally only <jk>public</jk> fields are considered. 295 * <br>Use this setting if you want to reduce the visibility requirement. 296 * 297 * <ul class='notes'> 298 * <li> 299 * Possible values: 300 * <ul> 301 * <li><js>"PUBLIC"</js> (default) 302 * <li><js>"PROTECTED"</js> 303 * <li><js>"DEFAULT"</js> 304 * <li><js>"PRIVATE"</js> 305 * </ul> 306 * <li> 307 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 308 * </ul> 309 * 310 * <ul class='seealso'> 311 * <li class='jf'>{@link BeanContext#BEAN_beanFieldVisibility} 312 * </ul> 313 */ 314 String beanFieldVisibility() default ""; 315 316 /** 317 * Configuration property: Bean filters. 318 * 319 * <p> 320 * This is a programmatic equivalent to the {@link Bean @Bean} annotation. 321 * <br>It's useful when you want to use the <c>@Bean</c> annotation functionality, but you don't have the ability to alter 322 * the bean classes. 323 * 324 * <ul class='notes'> 325 * <li> 326 * Values can consist of any of the following types: 327 * <ul class='spaced-list'> 328 * <li>Any subclass of {@link BeanFilterBuilder}. 329 * <br>These must have a public no-arg constructor. 330 * <li>Any bean interfaces. 331 * <br>A shortcut for defining a {@link InterfaceBeanFilterBuilder}. 332 * <br>Any subclasses of an interface class will only have properties defined on the interface. 333 * <br>All other bean properties will be ignored. 334 * </ul> 335 * </ul> 336 * 337 * <ul class='seealso'> 338 * <li class='jf'>{@link BeanContext#BEAN_beanFilters} 339 * <li class='link'>{@doc BeanFilters} 340 * <li class='link'>{@doc InterfaceFilters} 341 * </ul> 342 * 343 * <div class='warn'> 344 * <b>Deprecated</b> - Use {@link #interfaces()} or other various approaches. 345 * </div> 346 */ 347 @Deprecated 348 Class<?>[] beanFilters() default {}; 349 350 /** 351 * Configuration property: Add to bean filters. 352 * 353 * <div class='warn'> 354 * <b>Deprecated</b> - Use {@link #interfaces()} or other various approaches. 355 * </div> 356 */ 357 @Deprecated 358 Class<?>[] beanFilters_replace() default {}; 359 360 /** 361 * Configuration property: Remove from bean filters. 362 * 363 * <div class='warn'> 364 * <b>Deprecated</b> - Use {@link #interfaces()} or other various approaches. 365 * </div> 366 */ 367 @Deprecated 368 Class<?>[] beanFilters_remove() default {}; 369 370 /** 371 * Configuration property: BeanMap.put() returns old property value. 372 * 373 * <p> 374 * If <js>"true"</js>, then the {@link BeanMap#put(String,Object) BeanMap.put()} method will return old property 375 * values. 376 * <br>Otherwise, it returns <jk>null</jk>. 377 * 378 * <ul class='notes'> 379 * <li> 380 * Possible values: 381 * <ul> 382 * <li><js>"true"</js> 383 * <li><js>"false"</js> (default because it introduces a slight performance penalty during serialization) 384 * </ul> 385 * <li> 386 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 387 * </ul> 388 * 389 * <ul class='seealso'> 390 * <li class='jf'>{@link BeanContext#BEAN_beanMapPutReturnsOldValue} 391 * </ul> 392 */ 393 String beanMapPutReturnsOldValue() default ""; 394 395 /** 396 * Configuration property: Minimum bean method visibility. 397 * 398 * <p> 399 * Only look for bean methods with the specified minimum visibility. 400 * 401 * <p> 402 * This affects which methods are detected as getters and setters on a bean class. 403 * <br>Normally only <jk>public</jk> getters and setters are considered. 404 * <br>Use this setting if you want to reduce the visibility requirement. 405 * 406 * <ul class='notes'> 407 * <li> 408 * Possible values: 409 * <ul> 410 * <li><js>"PUBLIC"</js> (default) 411 * <li><js>"PROTECTED"</js> 412 * <li><js>"DEFAULT"</js> 413 * <li><js>"PRIVATE"</js> 414 * </ul> 415 * <li> 416 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 417 * </ul> 418 * 419 * <ul class='seealso'> 420 * <li class='jf'>{@link BeanContext#BEAN_beanMethodVisibility} 421 * </ul> 422 */ 423 String beanMethodVisibility() default ""; 424 425 /** 426 * Configuration property: Beans require no-arg constructors. 427 * 428 * <p> 429 * If <js>"true"</js>, a Java class must implement a default no-arg constructor to be considered a bean. 430 * <br>Otherwise, the bean will be serialized as a string using the {@link Object#toString()} method. 431 * 432 * <ul class='notes'> 433 * <li> 434 * Possible values: 435 * <ul> 436 * <li><js>"true"</js> 437 * <li><js>"false"</js> (default) 438 * </ul> 439 * <li> 440 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 441 * <li> 442 * The {@link Bean @Bean} annotation can be used on a class to override this setting when <js>"true"</js>. 443 * </ul> 444 * 445 * <ul class='seealso'> 446 * <li class='jf'>{@link BeanContext#BEAN_beansRequireDefaultConstructor} 447 * </ul> 448 */ 449 String beansRequireDefaultConstructor() default ""; 450 451 /** 452 * Configuration property: Beans require Serializable interface. 453 * 454 * <p> 455 * If <js>"true"</js>, a Java class must implement the {@link Serializable} interface to be considered a bean. 456 * <br>Otherwise, the bean will be serialized as a string using the {@link Object#toString()} method. 457 * 458 * <ul class='notes'> 459 * <li> 460 * Possible values: 461 * <ul> 462 * <li><js>"true"</js> 463 * <li><js>"false"</js> (default) 464 * </ul> 465 * <li> 466 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 467 * <li> 468 * The {@link Bean @Bean} annotation can be used on a class to override this setting when <js>"true"</js>. 469 * </ul> 470 * 471 * <ul class='seealso'> 472 * <li class='jf'>{@link BeanContext#BEAN_beansRequireSerializable} 473 * </ul> 474 */ 475 String beansRequireSerializable() default ""; 476 477 /** 478 * Configuration property: Beans require setters for getters. 479 * 480 * <p> 481 * If <js>"true"</js>, only getters that have equivalent setters will be considered as properties on a bean. 482 * <br>Otherwise, they will be ignored. 483 * 484 * <ul class='notes'> 485 * <li> 486 * Possible values: 487 * <ul> 488 * <li><js>"true"</js> 489 * <li><js>"false"</js> (default) 490 * </ul> 491 * <li> 492 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 493 * </ul> 494 * 495 * <ul class='seealso'> 496 * <li class='jf'>{@link BeanContext#BEAN_beansRequireSettersForGetters} 497 * </ul> 498 */ 499 String beansRequireSettersForGetters() default ""; 500 501 /** 502 * Configuration property: Beans require at least one property. 503 * 504 * <p> 505 * If <js>"true"</js>, then a Java class must contain at least 1 property to be considered a bean. 506 * <br>Otherwise, the bean will be serialized as a string using the {@link Object#toString()} method. 507 * 508 * <ul class='notes'> 509 * <li> 510 * Possible values: 511 * <ul> 512 * <li><js>"true"</js> (default) 513 * <li><js>"false"</js> 514 * </ul> 515 * <li> 516 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 517 * </ul> 518 * 519 * <ul class='seealso'> 520 * <li class='jf'>{@link BeanContext#BEAN_beansRequireSomeProperties} 521 * </ul> 522 */ 523 String beansRequireSomeProperties() default ""; 524 525 /** 526 * Configuration property: Bean type property name. 527 * 528 * <p> 529 * This specifies the name of the bean property used to store the dictionary name of a bean type so that the 530 * parser knows the data type to reconstruct. 531 * 532 * <ul class='notes'> 533 * <li> 534 * Default value: <js>"_type"</js>. 535 * <li> 536 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 537 * </ul> 538 539 * <ul class='seealso'> 540 * <li class='jf'>{@link BeanContext#BEAN_typePropertyName} 541 * </ul> 542 */ 543 String typePropertyName() default ""; 544 545 /** 546 * Configuration property: Bean property includes. 547 * 548 * Shortcut for specifying the {@link Bean#bpi()} annotation for all serializers. 549 * 550 * <p> 551 * The typical use case is when you're rendering summary and details views of the same bean in a resource and 552 * you want to expose or hide specific properties depending on the level of detail you want. 553 * 554 * <p> 555 * In the example below, our 'summary' view is a list of beans where we only want to show the ID property, 556 * and our detail view is a single bean where we want to expose different fields: 557 * <p class='bcode w800'> 558 * <jc>// Our bean</jc> 559 * <jk>public class</jk> MyBean { 560 * 561 * <jc>// Summary properties</jc> 562 * <ja>@Html</ja>(link=<js>"servlet:/mybeans/{id}"</js>) 563 * <jk>public</jk> String <jf>id</jf>; 564 * 565 * <jc>// Detail properties</jc> 566 * <jk>public</jk> String <jf>a</jf>, <jf>b</jf>; 567 * } 568 * 569 * <jc>// Only render "id" property.</jc> 570 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/mybeans"</js>) 571 * <ja>@BeanConfig</ja>(bpi=<js>"MyBean: id"</js>) 572 * <jk>public</jk> List<MyBean> getBeanSummary() {...} 573 * 574 * <jc>// Only render "a" and "b" properties.</jc> 575 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/mybeans/{id}"</js>) 576 * <ja>@BeanConfig</ja>(bpi=<js>"MyBean: a,b"</js>) 577 * <jk>public</jk> MyBean getBeanDetails(<ja>@Path</ja> String id) {...} 578 * </p> 579 * 580 * <ul class='notes'> 581 * <li> 582 * The format of each value is: <js>"Key: comma-delimited-tokens"</js>. 583 * <li> 584 * Keys can be fully-qualified or short class names or <js>"*"</js> to represent all classes. 585 * <li> 586 * Values are comma-delimited lists of bean property names. 587 * <li> 588 * Properties apply to specified class and all subclasses. 589 * <li> 590 * Semicolons can be used as an additional separator for multiple values: 591 * <p class='bcode w800'> 592 * <jc>// Equivalent</jc> 593 * bpi={<js>"Bean1: foo"</js>,<js>"Bean2: bar,baz"</js>} 594 * bpi=<js>"Bean1: foo; Bean2: bar,baz"</js> 595 * </p> 596 * <li> 597 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 598 * </ul> 599 * 600 * <ul class='seealso'> 601 * <li class='jm'>{@link BeanContextBuilder#bpi(Class, String)} 602 * <li class='jm'>{@link BeanContextBuilder#bpi(String, String)} 603 * <li class='jm'>{@link BeanContextBuilder#bpi(Map)} 604 * </ul> 605 */ 606 String[] bpi() default {}; 607 608 /** 609 * Configuration property: Bean property includes. 610 * 611 * <p> 612 * Specifies the set and order of names of properties associated with the bean class. 613 * 614 * <h5 class='section'>Example:</h5> 615 * <p class='bcode w800'> 616 * <ja>@BeanConfig</ja>( 617 * bpiMap={ 618 * <ja>@CS</ja>(key=MyBean.<jk>class</jk>, value=<js>"foo,bar"</js>) 619 * } 620 * ) 621 * <p> 622 * 623 * <ul class='notes'> 624 * <li> 625 * Keys are the class applied to. 626 * <br>Values are comma-delimited lists of property names. 627 * <li> 628 * Setting applies to specified class and all subclasses. 629 * <li> 630 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 631 * </ul> 632 * 633 * <ul class='seealso'> 634 * <li class='jm'>{@link BeanContextBuilder#bpi(Class, String)} 635 * <li class='jm'>{@link BeanContextBuilder#bpi(String, String)} 636 * <li class='jm'>{@link BeanContextBuilder#bpi(Map)} 637 * </ul> 638 * 639 * <div class='warn'> 640 * <b>Deprecated</b> - Use {@link #applyBean()} and {@link Bean#bpi()}. 641 * </div> 642 */ 643 @Deprecated 644 CS[] bpiMap() default {}; 645 646 /** 647 * Configuration property: Bean property excludes. 648 * 649 * Shortcut for specifying the {@link Bean#bpx()} annotation for all serializers. 650 * 651 * <p> 652 * Same as {@link #bpi()} except you specify a list of bean property names that you want to exclude from 653 * serialization. 654 * 655 * <p> 656 * In the example below, our 'summary' view is a list of beans where we want to exclude some properties: 657 * <p class='bcode w800'> 658 * <jc>// Our bean</jc> 659 * <jk>public class</jk> MyBean { 660 * 661 * <jc>// Summary properties</jc> 662 * <ja>@Html</ja>(link=<js>"servlet:/mybeans/{id}"</js>) 663 * <jk>public</jk> String <jf>id</jf>; 664 * 665 * <jc>// Detail properties</jc> 666 * <jk>public</jk> String <jf>a</jf>, <jf>b</jf>; 667 * } 668 * 669 * <jc>// Don't show "a" and "b" properties.</jc> 670 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/mybeans"</js>) 671 * <ja>@BeanConfig</ja>(bpx=<js>"MyBean: a,b"</js>) 672 * <jk>public</jk> List<MyBean> getBeanSummary() {...} 673 * 674 * <jc>// Render all properties.</jc> 675 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/mybeans/{id}"</js>) 676 * <jk>public</jk> MyBean getBeanDetails(<ja>@Path</ja> String id) {...} 677 * </p> 678 * 679 * <ul class='notes'> 680 * <li> 681 * The format of each value is: <js>"Key: comma-delimited-tokens"</js>. 682 * <li> 683 * Keys can be fully-qualified or short class names or <js>"*"</js> to represent all classes. 684 * <li> 685 * Values are comma-delimited lists of bean property names. 686 * <li> 687 * Properties apply to specified class and all subclasses. 688 * <li> 689 * Semicolons can be used as an additional separator for multiple values: 690 * <p class='bcode w800'> 691 * <jc>// Equivalent</jc> 692 * bpx={<js>"Bean1: foo"</js>,<js>"Bean2: bar,baz"</js>} 693 * bpx=<js>"Bean1: foo; Bean2: bar,baz"</js> 694 * </p> 695 * <li> 696 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 697 * </ul> 698 * 699 * <ul class='seealso'> 700 * <li class='jm'>{@link BeanContextBuilder#bpx(Class, String)} 701 * <li class='jm'>{@link BeanContextBuilder#bpx(String, String)} 702 * <li class='jm'>{@link BeanContextBuilder#bpx(Map)} 703 * </ul> 704 */ 705 String[] bpx() default {}; 706 707 /** 708 * Configuration property: Bean property excludes. 709 * 710 * <p> 711 * Specifies to exclude the specified list of properties for the specified bean class. 712 * 713 * <h5 class='section'>Example:</h5> 714 * <p class='bcode w800'> 715 * <ja>@BeanConfig</ja>( 716 * bpxMap={ 717 * <ja>@CS</ja>(key=MyBean.<jk>class</jk>, value=<js>"foo,bar"</js>) 718 * } 719 * ) 720 * <p> 721 * 722 * <ul class='notes'> 723 * <li> 724 * Keys are the class applied to. 725 * <br>Values are comma-delimited lists of property names. 726 * <li> 727 * Setting applies to specified class and all subclasses. 728 * <li> 729 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 730 * </ul> 731 * 732 * <ul class='seealso'> 733 * <li class='jm'>{@link BeanContextBuilder#bpx(Class, String)} 734 * <li class='jm'>{@link BeanContextBuilder#bpx(String, String)} 735 * <li class='jm'>{@link BeanContextBuilder#bpx(Map)} 736 * </ul> 737 * 738 * <div class='warn'> 739 * <b>Deprecated</b> - Use {@link #applyBean()} and {@link Bean#bpx()}. 740 * </div> 741 */ 742 @Deprecated 743 CS[] bpxMap() default {}; 744 745 /** 746 * Configuration property: Read-only bean properties. 747 * 748 * Shortcut for specifying the {@link Bean#bpwo()} annotation for all parsers. 749 * 750 * <p> 751 * Specifies one or more properties on a bean that are read-only despite having valid getters. 752 * Serializers will serialize such properties as usual, but parsers will silently ignore them. 753 * 754 * <h5 class='section'>Example:</h5> 755 * <p class='bcode w800'> 756 * <jc>// Ignore 'a' and 'b' properties if they're present in the HTTP request body.</jc> 757 * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>, path=<js>"/mybeans"</js>) 758 * <ja>@BeanConfig</ja>(bpro=<js>"MyBean: a,b"</js>) 759 * <jk>public void</jk> postMyBeans(List<MyBean> l) {...} 760 * </p> 761 * 762 * <ul class='notes'> 763 * <li> 764 * The format of each value is: <js>"Key: comma-delimited-tokens"</js>. 765 * <li> 766 * Keys can be fully-qualified or short class names or <js>"*"</js> to represent all classes. 767 * <li> 768 * Values are comma-delimited lists of bean property names. 769 * <li> 770 * Properties apply to specified class and all subclasses. 771 * <li> 772 * Semicolons can be used as an additional separator for multiple values: 773 * <p class='bcode w800'> 774 * <jc>// Equivalent</jc> 775 * bpro={<js>"Bean1: foo"</js>,<js>"Bean2: bar,baz"</js>} 776 * bpro=<js>"Bean1: foo; Bean2: bar,baz"</js> 777 * </p> 778 * <li> 779 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 780 * </ul> 781 * 782 * <ul class='seealso'> 783 * <li class='jm'>{@link BeanContextBuilder#bpro(Class, String)} 784 * <li class='jm'>{@link BeanContextBuilder#bpro(String, String)} 785 * <li class='jm'>{@link BeanContextBuilder#bpro(Map)} 786 * </ul> 787 */ 788 String[] bpro() default {}; 789 790 /** 791 * Configuration property: Read-only bean properties. 792 * 793 * Shortcut for specifying the {@link Bean#bpro()} annotation for all parsers. 794 * 795 * <p> 796 * Specifies one or more properties on a bean that are read-only despite having valid getters. 797 * Serializers will serialize such properties as usual, but parsers will silently ignore them. 798 * 799 * <h5 class='section'>Example:</h5> 800 * <p class='bcode w800'> 801 * <jc>// Ignore 'a' and 'b' properties if they're present in the HTTP request body.</jc> 802 * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>, path=<js>"/mybeans"</js>) 803 * <ja>@BeanConfig</ja>(bproMap={<ja>@CS</ja>(MyBean.<jk>class</jk>, <js>"a,b"</js>)}) 804 * <jk>public void</jk> postMyBeans(List<MyBean> l) {...} 805 * </p> 806 * 807 * <ul class='notes'> 808 * <li> 809 * Values are comma-delimited lists of bean property names. 810 * <li> 811 * Properties apply to specified class and all subclasses. 812 * <li> 813 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 814 * </ul> 815 * 816 * <ul class='seealso'> 817 * <li class='jm'>{@link BeanContextBuilder#bpro(Class, String)} 818 * <li class='jm'>{@link BeanContextBuilder#bpro(String, String)} 819 * <li class='jm'>{@link BeanContextBuilder#bpro(Map)} 820 * </ul> 821 * 822 * <div class='warn'> 823 * <b>Deprecated</b> - Use {@link #applyBean()} and {@link Bean#bpi()}. 824 * </div> 825 */ 826 @Deprecated 827 CS[] bproMap() default {}; 828 829 /** 830 * Configuration property: Write-only bean properties. 831 * 832 * Shortcut for specifying the {@link Bean#bpwo()} annotation for all serializers. 833 * 834 * <p> 835 * Specifies one or more properties on a bean that are write-only despite having valid setters. 836 * Parsers will parse such properties as usual, but serializers will silently ignore them. 837 * 838 * <h5 class='section'>Example:</h5> 839 * <p class='bcode w800'> 840 * <jc>// Ignore 'a' and 'b' properties when serializing the response body.</jc> 841 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/mybeans"</js>) 842 * <ja>@BeanConfig</ja>(bpwo=<js>"MyBean: a,b"</js>) 843 * <jk>public</jk> List<MyBean> getMyBeans() {...} 844 * </p> 845 * 846 * <ul class='notes'> 847 * <li> 848 * The format of each value is: <js>"Key: comma-delimited-tokens"</js>. 849 * <li> 850 * Keys can be fully-qualified or short class names or <js>"*"</js> to represent all classes. 851 * <li> 852 * Values are comma-delimited lists of bean property names. 853 * <li> 854 * Properties apply to specified class and all subclasses. 855 * <li> 856 * Semicolons can be used as an additional separator for multiple values: 857 * <p class='bcode w800'> 858 * <jc>// Equivalent</jc> 859 * bpwo={<js>"Bean1: foo"</js>,<js>"Bean2: bar,baz"</js>} 860 * bpwo=<js>"Bean1: foo; Bean2: bar,baz"</js> 861 * </p> 862 * <li> 863 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 864 * </ul> 865 * 866 * <ul class='seealso'> 867 * <li class='jm'>{@link BeanContextBuilder#bpwo(Class, String)} 868 * <li class='jm'>{@link BeanContextBuilder#bpwo(String, String)} 869 * <li class='jm'>{@link BeanContextBuilder#bpwo(Map)} 870 * </ul> 871 */ 872 String[] bpwo() default {}; 873 874 /** 875 * Configuration property: Write-only bean properties. 876 * 877 * Shortcut for specifying the {@link Bean#bpwo()} annotation for all serializers. 878 * 879 * <p> 880 * Specifies one or more properties on a bean that are write-only despite having valid setters. 881 * Parsers will parse such properties as usual, but serializers will silently ignore them. 882 * 883 * <h5 class='section'>Example:</h5> 884 * <p class='bcode w800'> 885 * <jc>// Ignore 'a' and 'b' properties if they're present in the HTTP request body.</jc> 886 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/mybeans"</js>) 887 * <ja>@BeanConfig</ja>(bpwoMap={<ja>@CS</ja>(MyBean.<jk>class</jk>, <js>"a,b"</js>)}) 888 * <jk>public void</jk> List<MyBean> getMyBeans() {...} 889 * </p> 890 * 891 * <ul class='notes'> 892 * <li> 893 * Values are comma-delimited lists of bean property names. 894 * <li> 895 * Properties apply to specified class and all subclasses. 896 * <li> 897 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 898 * </ul> 899 * 900 * <ul class='seealso'> 901 * <li class='jm'>{@link BeanContextBuilder#bpwo(Class, String)} 902 * <li class='jm'>{@link BeanContextBuilder#bpwo(String, String)} 903 * <li class='jm'>{@link BeanContextBuilder#bpwo(Map)} 904 * </ul> 905 * 906 * <div class='warn'> 907 * <b>Deprecated</b> - Use {@link #applyBean()} and {@link Bean#bpwo()}. 908 * </div> 909 */ 910 @Deprecated 911 CS[] bpwoMap() default {}; 912 913 /** 914 * Configuration property: Debug mode. 915 * 916 * <p> 917 * Enables the following additional information during serialization: 918 * <ul class='spaced-list'> 919 * <li> 920 * When bean getters throws exceptions, the exception includes the object stack information 921 * in order to determine how that method was invoked. 922 * <li> 923 * Enables {@link Serializer#BEANTRAVERSE_detectRecursions}. 924 * </ul> 925 * 926 * <p> 927 * Enables the following additional information during parsing: 928 * <ul class='spaced-list'> 929 * <li> 930 * When bean setters throws exceptions, the exception includes the object stack information 931 * in order to determine how that method was invoked. 932 * </ul> 933 * 934 * <ul class='notes'> 935 * <li> 936 * Possible values: 937 * <ul> 938 * <li><js>"true"</js> 939 * <li><js>"false"</js> (default) 940 * </ul> 941 * <li> 942 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 943 * </ul> 944 * 945 * <ul class='seealso'> 946 * <li class='jf'>{@link Context#CONTEXT_debug} 947 * </ul> 948 */ 949 String debug() default ""; 950 951 /** 952 * Configuration property: Bean dictionary. 953 * 954 * <p> 955 * The list of classes that make up the bean dictionary in this bean context. 956 * 957 * <p> 958 * A dictionary is a name/class mapping used to find class types during parsing when they cannot be inferred 959 * through reflection. 960 * <br>The names are defined through the {@link Bean#typeName() @Bean(typeName)} annotation defined on the bean class. 961 * <br>For example, if a class <c>Foo</c> has a type-name of <js>"myfoo"</js>, then it would end up serialized 962 * as <js>"{_type:'myfoo',...}"</js>. 963 * 964 * <p> 965 * This setting tells the parsers which classes to look for when resolving <js>"_type"</js> attributes. 966 * 967 * <ul class='seealso'> 968 * <li class='jf'>{@link BeanContext#BEAN_beanDictionary} 969 * <li class='link'>{@doc BeanDictionaries} 970 * </ul> 971 */ 972 Class<?>[] dictionary() default {}; 973 974 /** 975 * Configuration property: Add to bean dictionary. 976 * 977 * <ul class='seealso'> 978 * <li class='jf'>{@link BeanContext#BEAN_beanDictionary} 979 * </ul> 980 */ 981 Class<?>[] dictionary_replace() default {}; 982 983 /** 984 * Configuration property: Remove from bean dictionary. 985 * 986 * <ul class='seealso'> 987 * <li class='jf'>{@link BeanContext#BEAN_beanDictionary_remove} 988 * </ul> 989 */ 990 Class<?>[] dictionary_remove() default {}; 991 992 /** 993 * Configuration property: POJO examples. 994 * 995 * <p> 996 * Specifies an example of the specified class. 997 * 998 * <p> 999 * Examples are used in cases such as POJO examples in Swagger documents. 1000 * 1001 * <h5 class='section'>Example:</h5> 1002 * <p class='bcode w800'> 1003 * <ja>@BeanConfig</ja>( 1004 * examples={ 1005 * <ja>@CS</ja>(key=MyBean.<jk>class</jk>, value=<js>"{foo:'bar'}"</js>) 1006 * } 1007 * ) 1008 * </p> 1009 * 1010 * <ul class='notes'> 1011 * <li> 1012 * Setting applies to specified class and all subclasses. 1013 * <li> 1014 * Keys are the class of the example. 1015 * <br>Values are Simple-JSON representation of that class. 1016 * <li> 1017 * POJO examples can also be defined on classes via the following: 1018 * <ul class='spaced-list'> 1019 * <li>A static field annotated with {@link Example @Example}. 1020 * <li>A static method annotated with {@link Example @Example} with zero arguments or one {@link BeanSession} argument. 1021 * <li>A static method with name <c>example</c> with no arguments or one {@link BeanSession} argument. 1022 * </ul> 1023 * <li> 1024 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1025 * </ul> 1026 * 1027 * <ul class='seealso'> 1028 * <li class='jf'>{@link BeanContext#BEAN_examples} 1029 * </ul> 1030 */ 1031 CS[] example() default {}; 1032 1033 /** 1034 * Configuration property: POJO examples. 1035 * 1036 * <p> 1037 * Same as {@link #example()} but allows you to define examples as a Simple-JSON string. 1038 * 1039 * <h5 class='section'>Example:</h5> 1040 * <p class='bcode w800'> 1041 * <ja>@BeanConfig</ja>( 1042 * examples={ 1043 * <js>"MyBean: {foo:'bar'}"</js> <jc>// Could also be "{MyBean: {foo:'bar'}}"</jc> 1044 * } 1045 * ) 1046 * </p> 1047 * 1048 * <ul class='notes'> 1049 * <li> 1050 * Keys are the class of the example and can be the fully-qualified name or simple name. 1051 * <br>Values are Simple-JSON representation of that class. 1052 * <li> 1053 * The individual strings are concatenated together and the whole string is treated as a JSON Object. 1054 * <br>The leading and trailing <js>'{'</js> and <js>'}'</js> characters are optional. 1055 * <li> 1056 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1057 * </ul> 1058 * 1059 * <ul class='seealso'> 1060 * <li class='jf'>{@link BeanContext#BEAN_examples} 1061 * </ul> 1062 */ 1063 String[] examples() default {}; 1064 1065 /** 1066 * Configuration property: Bean property excludes. 1067 * 1068 * <div class='warn'> 1069 * <b>Deprecated</b> - {@link #bpxMap()}. 1070 * </div> 1071 */ 1072 @Deprecated CS[] excludeProperties() default {}; 1073 1074 /** 1075 * Configuration property: Find fluent setters. 1076 * 1077 * <p> 1078 * When enabled, fluent setters are detected on beans. 1079 * 1080 * <p> 1081 * Fluent setters must have the following attributes: 1082 * <ul> 1083 * <li>Public. 1084 * <li>Not static. 1085 * <li>Take in one parameter. 1086 * <li>Return the bean itself. 1087 * </ul> 1088 * 1089 * <ul class='notes'> 1090 * <li> 1091 * Possible values: 1092 * <ul> 1093 * <li><js>"true"</js> 1094 * <li><js>"false"</js> (default) 1095 * </ul> 1096 * <li> 1097 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1098 * </ul> 1099 * 1100 * <ul class='seealso'> 1101 * <li class='jf'>{@link BeanContext#BEAN_fluentSetters} 1102 * </ul> 1103 */ 1104 String fluentSetters() default ""; 1105 1106 /** 1107 * Configuration property: Ignore invocation errors on getters. 1108 * 1109 * <p> 1110 * If <js>"true"</js>, errors thrown when calling bean getter methods will silently be ignored. 1111 * <br>Otherwise, a {@code BeanRuntimeException} is thrown. 1112 * 1113 * <ul class='notes'> 1114 * <li> 1115 * Possible values: 1116 * <ul> 1117 * <li><js>"true"</js> 1118 * <li><js>"false"</js> (default) 1119 * </ul> 1120 * <li> 1121 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1122 * </ul> 1123 * 1124 * <ul class='seealso'> 1125 * <li class='jf'>{@link BeanContext#BEAN_ignoreInvocationExceptionsOnGetters} 1126 * </ul> 1127 */ 1128 String ignoreInvocationExceptionsOnGetters() default ""; 1129 1130 /** 1131 * Configuration property: Ignore invocation errors on setters. 1132 * 1133 * <p> 1134 * If <js>"true"</js>, errors thrown when calling bean setter methods will silently be ignored. 1135 * <br>Otherwise, a {@code BeanRuntimeException} is thrown. 1136 * 1137 * <ul class='notes'> 1138 * <li> 1139 * Possible values: 1140 * <ul> 1141 * <li><js>"true"</js> 1142 * <li><js>"false"</js> (default) 1143 * </ul> 1144 * <li> 1145 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1146 * </ul> 1147 * 1148 * <ul class='seealso'> 1149 * <li class='jf'>{@link BeanContext#BEAN_ignoreInvocationExceptionsOnSetters} 1150 * </ul> 1151 */ 1152 String ignoreInvocationExceptionsOnSetters() default ""; 1153 1154 /** 1155 * Configuration property: Ignore properties without setters. 1156 * 1157 * <p> 1158 * If <js>"true"</js>, trying to set a value on a bean property without a setter will silently be ignored. 1159 * <br>Otherwise, a {@code RuntimeException} is thrown. 1160 * 1161 * <ul class='notes'> 1162 * <li> 1163 * Possible values: 1164 * <ul> 1165 * <li><js>"true"</js> (default) 1166 * <li><js>"false"</js> 1167 * </ul> 1168 * <li> 1169 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1170 * </ul> 1171 * 1172 * <ul class='seealso'> 1173 * <li class='jf'>{@link BeanContext#BEAN_ignorePropertiesWithoutSetters} 1174 * </ul> 1175 */ 1176 String ignorePropertiesWithoutSetters() default ""; 1177 1178 /** 1179 * Configuration property: Ignore transient fields. 1180 * 1181 * <p> 1182 * If <jk>true</jk>, methods and fields marked as <jk>transient</jk> will be ignored as bean properties. 1183 * 1184 * <ul class='notes'> 1185 * <li> 1186 * Possible values: 1187 * <ul> 1188 * <li><js>"true"</js> (default) 1189 * <li><js>"false"</js> 1190 * </ul> 1191 * <li> 1192 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1193 * </ul> 1194 * 1195 * <ul class='seealso'> 1196 * <li class='jf'>{@link BeanContext#BEAN_ignoreTransientFields} 1197 * </ul> 1198 */ 1199 String ignoreTransientFields() default ""; 1200 1201 /** 1202 * Configuration property: Ignore unknown properties. 1203 * 1204 * <p> 1205 * If <js>"true"</js>, trying to set a value on a non-existent bean property will silently be ignored. 1206 * <br>Otherwise, a {@code RuntimeException} is thrown. 1207 * 1208 * <ul class='notes'> 1209 * <li> 1210 * Possible values: 1211 * <ul> 1212 * <li><js>"true"</js> 1213 * <li><js>"false"</js> (default) 1214 * </ul> 1215 * <li> 1216 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1217 * </ul> 1218 * 1219 * <ul class='seealso'> 1220 * <li class='jf'>{@link BeanContext#BEAN_ignoreUnknownBeanProperties} 1221 * </ul> 1222 */ 1223 String ignoreUnknownBeanProperties() default ""; 1224 1225 /** 1226 * Configuration property: Ignore unknown properties with null values. 1227 * 1228 * <p> 1229 * If <js>"true"</js>, trying to set a <jk>null</jk> value on a non-existent bean property will silently be ignored. 1230 * <br>Otherwise, a {@code RuntimeException} is thrown. 1231 * 1232 * <ul class='notes'> 1233 * <li> 1234 * Possible values: 1235 * <ul> 1236 * <li><js>"true"</js> (default) 1237 * <li><js>"false"</js> 1238 * </ul> 1239 * <li> 1240 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1241 * </ul> 1242 * 1243 * <ul class='seealso'> 1244 * <li class='jf'>{@link BeanContext#BEAN_ignoreUnknownNullBeanProperties} 1245 * </ul> 1246 */ 1247 String ignoreUnknownNullBeanProperties() default ""; 1248 1249 /** 1250 * Configuration property: Implementation classes. 1251 * 1252 * <p> 1253 * For interfaces and abstract classes this method can be used to specify an implementation class for the 1254 * interface/abstract class so that instances of the implementation class are used when instantiated (e.g. during a 1255 * parse). 1256 * 1257 * <h5 class='section'>Example:</h5> 1258 * <p class='bcode w800'> 1259 * <ja>@BeanConfig</ja>( 1260 * implClasses={ 1261 * <ja>@CC</ja>(key=MyInterface.<jk>class</jk>, value=MyInterfaceImpl.<jk>class</jk>) 1262 * } 1263 * ) 1264 * <p> 1265 * 1266 * <ul class='seealso'> 1267 * <li class='jf'>{@link BeanContext#BEAN_implClasses} 1268 * </ul> 1269 */ 1270 CC[] implClasses() default {}; 1271 1272 /** 1273 * Configuration property: Bean property includes. 1274 * 1275 * <div class='warn'> 1276 * <b>Deprecated</b> - {@link #bpiMap()}. 1277 * </div> 1278 */ 1279 @Deprecated CS[] includeProperties() default {}; 1280 1281 /** 1282 * Identifies a set of interfaces. 1283 * 1284 * <p> 1285 * When specified, only the list of properties defined on the interface class will be used during serialization 1286 * of implementation classes. Additional properties on subclasses will be ignored. 1287 * 1288 * <p class='bcode w800'> 1289 * <jc>// Parent class or interface</jc> 1290 * <jk>public abstract class</jk> A { 1291 * <jk>public</jk> String <jf>foo</jf> = <js>"foo"</js>; 1292 * } 1293 * 1294 * <jc>// Sub class</jc> 1295 * <jk>public class</jk> A1 <jk>extends</jk> A { 1296 * <jk>public</jk> String <jf>bar</jf> = <js>"bar"</js>; 1297 * } 1298 * 1299 * <jc>// Apply it to a config</jc> 1300 * <ja>@BeanConfig</ja>( 1301 * interfaces={ 1302 * A.<jk>class</jk> 1303 * } 1304 * ) 1305 * </p> 1306 * 1307 * <p> 1308 * This annotation can be used on the parent class so that it filters to all child classes, or can be set 1309 * individually on the child classes. 1310 * 1311 * <ul class='notes'> 1312 * <li>The {@link Bean#interfaceClass() @Bean(interfaceClass)} annotation is the equivalent annotation-based solution. 1313 * </ul> 1314 */ 1315 Class<?>[] interfaces() default {}; 1316 1317 /** 1318 * Configuration property: Locale. 1319 * 1320 * <p> 1321 * Specifies the default locale for serializer and parser sessions. 1322 * 1323 * <ul class='notes'> 1324 * <li> 1325 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1326 * </ul> 1327 * 1328 * <ul class='seealso'> 1329 * <li class='jf'>{@link Context#CONTEXT_locale} 1330 * </ul> 1331 */ 1332 String locale() default ""; 1333 1334 /** 1335 * Configuration property: Media type. 1336 * 1337 * <p> 1338 * Specifies the default media type value for serializer and parser sessions. 1339 * 1340 * <ul class='notes'> 1341 * <li> 1342 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1343 * </ul> 1344 * 1345 * <ul class='seealso'> 1346 * <li class='jf'>{@link Context#CONTEXT_mediaType} 1347 * </ul> 1348 */ 1349 String mediaType() default ""; 1350 1351 /** 1352 * Configuration property: Bean class exclusions. 1353 * 1354 * <p> 1355 * List of classes that should not be treated as beans even if they appear to be bean-like. 1356 * <br>Not-bean classes are converted to <c>Strings</c> during serialization. 1357 * 1358 * <ul class='notes'> 1359 * <li> 1360 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1361 * </ul> 1362 * 1363 * <ul class='seealso'> 1364 * <li class='jf'>{@link BeanContext#BEAN_notBeanClasses} 1365 * </ul> 1366 */ 1367 Class<?>[] notBeanClasses() default {}; 1368 1369 /** 1370 * Configuration property: Add to classes that should not be considered beans. 1371 * 1372 * <ul class='seealso'> 1373 * <li class='jf'>{@link BeanContext#BEAN_notBeanClasses} 1374 * </ul> 1375 */ 1376 Class<?>[] notBeanClasses_replace() default {}; 1377 1378 /** 1379 * Configuration property: Remove from classes that should not be considered beans. 1380 * 1381 * <ul class='seealso'> 1382 * <li class='jf'>{@link BeanContext#BEAN_notBeanClasses} 1383 * </ul> 1384 */ 1385 Class<?>[] notBeanClasses_remove() default {}; 1386 1387 /** 1388 * Configuration property: Bean package exclusions. 1389 * 1390 * <p> 1391 * When specified, the current list of ignore packages are appended to. 1392 * 1393 * <p> 1394 * Any classes within these packages will be serialized to strings using {@link Object#toString()}. 1395 * 1396 * <p> 1397 * Note that you can specify suffix patterns to include all subpackages. 1398 * 1399 * <ul class='notes'> 1400 * <li> 1401 * The default value excludes the following packages: 1402 * <ul> 1403 * <li><c>java.lang</c> 1404 * <li><c>java.lang.annotation</c> 1405 * <li><c>java.lang.ref</c> 1406 * <li><c>java.lang.reflect</c> 1407 * <li><c>java.io</c> 1408 * <li><c>java.net</c> 1409 * <li><c>java.nio.*</c> 1410 * <li><c>java.util.*</c> 1411 * </ul> 1412 * <li> 1413 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1414 * </ul> 1415 * 1416 * <ul class='seealso'> 1417 * <li class='jf'>{@link BeanContext#BEAN_notBeanPackages} 1418 * </ul> 1419 */ 1420 String[] notBeanPackages() default {}; 1421 1422 /** 1423 * Configuration property: Add to packages whose classes should not be considered beans. 1424 * 1425 * <ul class='seealso'> 1426 * <li class='jf'>{@link BeanContext#BEAN_notBeanPackages} 1427 * </ul> 1428 */ 1429 String[] notBeanPackages_replace() default {}; 1430 1431 /** 1432 * Configuration property: Remove from packages whose classes should not be considered beans. 1433 * 1434 * <ul class='seealso'> 1435 * <li class='jf'>{@link BeanContext#BEAN_notBeanPackages} 1436 * </ul> 1437 */ 1438 String[] notBeanPackages_remove() default {}; 1439 1440 /** 1441 * Configuration property: POJO swaps. 1442 * 1443 * <div class='warn'> 1444 * <b>Deprecated</b> - Use {@link BeanConfig#swaps()} 1445 * </div> 1446 */ 1447 @Deprecated 1448 Class<? extends PojoSwap<?,?>>[] pojoSwaps() default {}; 1449 1450 /** 1451 * Configuration property: Add to POJO swap classes. 1452 * 1453 * 1454 * <div class='warn'> 1455 * <b>Deprecated</b> - Use {@link BeanConfig#swaps_replace()} 1456 * </div> 1457 */ 1458 @Deprecated 1459 Class<? extends PojoSwap<?,?>>[] pojoSwaps_replace() default {}; 1460 1461 /** 1462 * Configuration property: Remove from POJO swap classes. 1463 * 1464 * 1465 * <div class='warn'> 1466 * <b>Deprecated</b> - Use {@link BeanConfig#swaps_remove()} 1467 * </div> 1468 */ 1469 @Deprecated 1470 Class<? extends PojoSwap<?,?>>[] pojoSwaps_remove() default {}; 1471 1472 /** 1473 * Configuration property: Bean property namer. 1474 * 1475 * <p> 1476 * The class to use for calculating bean property names. 1477 * 1478 * <p> 1479 * Predefined classes: 1480 * <ul> 1481 * <li>{@link PropertyNamerDefault} (default) 1482 * <li>{@link PropertyNamerDLC} - Dashed-lower-case names. 1483 * <li>{@link PropertyNamerULC} - Dashed-upper-case names. 1484 * </ul> 1485 * 1486 * <ul class='seealso'> 1487 * <li class='jf'>{@link BeanContext#BEAN_propertyNamer} 1488 * </ul> 1489 */ 1490 Class<? extends PropertyNamer> propertyNamer() default PropertyNamer.Null.class; 1491 1492 /** 1493 * Configuration property: Sort bean properties. 1494 * 1495 * <p> 1496 * When <jk>true</jk>, all bean properties will be serialized and access in alphabetical order. 1497 * <br>Otherwise, the natural order of the bean properties is used which is dependent on the JVM vendor. 1498 * <br>On IBM JVMs, the bean properties are ordered based on their ordering in the Java file. 1499 * <br>On Oracle JVMs, the bean properties are not ordered (which follows the official JVM specs). 1500 * 1501 * <p> 1502 * This property is disabled by default so that IBM JVM users don't have to use {@link Bean @Bean} annotations 1503 * to force bean properties to be in a particular order and can just alter the order of the fields/methods 1504 * in the Java file. 1505 * 1506 * <ul class='notes'> 1507 * <li> 1508 * Possible values: 1509 * <ul> 1510 * <li><js>"true"</js> 1511 * <li><js>"false"</js> (default) 1512 * </ul> 1513 * <li> 1514 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1515 * </ul> 1516 * 1517 * <ul class='seealso'> 1518 * <li class='jf'>{@link BeanContext#BEAN_sortProperties} 1519 * </ul> 1520 */ 1521 String sortProperties() default ""; 1522 1523 /** 1524 * Configuration property: Java object swaps. 1525 * 1526 * <p> 1527 * Swaps are used to "swap out" non-serializable classes with serializable equivalents during serialization, 1528 * and "swap in" the non-serializable class during parsing. 1529 * 1530 * <p> 1531 * An example of a swap would be a <c>Calendar</c> object that gets swapped out for an ISO8601 string. 1532 * 1533 * <p> 1534 * Multiple swaps can be associated with a single class. 1535 * <br>When multiple swaps are applicable to the same class, the media type pattern defined by 1536 * {@link PojoSwap#forMediaTypes()} or {@link Swap#mediaTypes() @Swap(mediaTypes)} are used to come up with the best match. 1537 * 1538 * <ul class='seealso'> 1539 * <li class='jf'>{@link BeanContext#BEAN_swaps} 1540 * <li class='link'>{@doc PojoSwaps} 1541 * <li class='link'>{@doc PerMediaTypePojoSwaps} 1542 * <li class='link'>{@doc OneWayPojoSwaps} 1543 * <li class='link'>{@doc SwapAnnotation} 1544 * <li class='link'>{@doc AutoPojoSwaps} 1545 * <li class='link'>{@doc SurrogateClasses} 1546 * </ul> 1547 */ 1548 Class<?>[] swaps() default {}; 1549 1550 /** 1551 * Configuration property: Add to Java object swap classes. 1552 * 1553 * <ul class='seealso'> 1554 * <li class='jf'>{@link BeanContext#BEAN_swaps} 1555 * </ul> 1556 */ 1557 Class<?>[] swaps_replace() default {}; 1558 1559 /** 1560 * Configuration property: Remove from Java object swap classes. 1561 * 1562 * <ul class='seealso'> 1563 * <li class='jf'>{@link BeanContext#BEAN_swaps} 1564 * </ul> 1565 */ 1566 Class<?>[] swaps_remove() default {}; 1567 1568 /** 1569 * Configuration property: Time zone. 1570 * 1571 * <p> 1572 * Specifies the default timezone for serializer and parser sessions. 1573 * 1574 * <ul class='notes'> 1575 * <li> 1576 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1577 * </ul> 1578 * 1579 * <ul class='seealso'> 1580 * <li class='jf'>{@link Context#CONTEXT_timeZone} 1581 * </ul> 1582 */ 1583 String timeZone() default ""; 1584 1585 /** 1586 * Configuration property: Use enum names. 1587 * 1588 * <p> 1589 * When enabled, enums are always serialized by name, not using {@link Object#toString()}. 1590 * 1591 * <ul class='notes'> 1592 * <li> 1593 * Possible values: 1594 * <ul> 1595 * <li><js>"true"</js> 1596 * <li><js>"false"</js> (default) 1597 * </ul> 1598 * <li> 1599 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1600 * </ul> 1601 * 1602 * <ul class='seealso'> 1603 * <li class='jf'>{@link BeanContext#BEAN_useEnumNames} 1604 * </ul> 1605 */ 1606 String useEnumNames() default ""; 1607 1608 /** 1609 * Configuration property: Use interface proxies. 1610 * 1611 * <p> 1612 * If <js>"true"</js>, then interfaces will be instantiated as proxy classes through the use of an 1613 * {@link InvocationHandler} if there is no other way of instantiating them. 1614 * <br>Otherwise, throws a {@link BeanRuntimeException}. 1615 * 1616 * <ul class='notes'> 1617 * <li> 1618 * Possible values: 1619 * <ul> 1620 * <li><js>"true"</js> (default) 1621 * <li><js>"false"</js> 1622 * </ul> 1623 * <li> 1624 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1625 * </ul> 1626 * 1627 * <ul class='seealso'> 1628 * <li class='jf'>{@link BeanContext#BEAN_useInterfaceProxies} 1629 * </ul> 1630 */ 1631 String useInterfaceProxies() default ""; 1632 1633 /** 1634 * Configuration property: Use Java Introspector. 1635 * 1636 * <p> 1637 * Using the built-in Java bean introspector will not pick up fields or non-standard getters/setters. 1638 * <br>Most {@link Bean @Bean} annotations will be ignored. 1639 * 1640 * <ul class='notes'> 1641 * <li> 1642 * Possible values: 1643 * <ul> 1644 * <li><js>"true"</js> 1645 * <li><js>"false"</js> (default) 1646 * </ul> 1647 * <li> 1648 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1649 * </ul> 1650 * 1651 * <ul class='seealso'> 1652 * <li class='jf'>{@link BeanContext#BEAN_useJavaBeanIntrospector} 1653 * </ul> 1654 */ 1655 String useJavaBeanIntrospector() default ""; 1656 1657 //----------------------------------------------------------------------------------------------------------------- 1658 // BeanTraverseContext 1659 //----------------------------------------------------------------------------------------------------------------- 1660 1661 /** 1662 * Configuration property: Automatically detect POJO recursions. 1663 * 1664 * <p> 1665 * Specifies that recursions should be checked for during traversal. 1666 * 1667 * <p> 1668 * Recursions can occur when traversing models that aren't true trees but rather contain loops. 1669 * <br>In general, unchecked recursions cause stack-overflow-errors. 1670 * <br>These show up as {@link ParseException ParseExceptions} with the message <js>"Depth too deep. Stack overflow occurred."</js>. 1671 * 1672 * <p> 1673 * The behavior when recursions are detected depends on the value for {@link BeanTraverseContext#BEANTRAVERSE_ignoreRecursions}. 1674 * 1675 * <p> 1676 * For example, if a model contains the links A->B->C->A, then the JSON generated will look like 1677 * the following when <jsf>BEANTRAVERSE_ignoreRecursions</jsf> is <jk>true</jk>... 1678 * 1679 * <p class='bcode w800'> 1680 * {A:{B:{C:<jk>null</jk>}}} 1681 * </p> 1682 * 1683 * <ul class='notes'> 1684 * <li> 1685 * Checking for recursion can cause a small performance penalty. 1686 * <li> 1687 * Possible values: 1688 * <ul> 1689 * <li><js>"true"</js> 1690 * <li><js>"false"</js> (default) 1691 * </ul> 1692 * <li> 1693 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1694 * </ul> 1695 * 1696 * <ul class='seealso'> 1697 * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_detectRecursions} 1698 * </ul> 1699 */ 1700 String detectRecursions() default ""; 1701 1702 /** 1703 * Configuration property: Ignore recursion errors. 1704 * 1705 * <p> 1706 * Used in conjunction with {@link BeanTraverseContext#BEANTRAVERSE_detectRecursions}. 1707 * <br>Setting is ignored if <jsf>BEANTRAVERSE_detectRecursions</jsf> is <js>"false"</js>. 1708 * 1709 * <p> 1710 * If <js>"true"</js>, when we encounter the same object when traversing a tree, we set the value to <jk>null</jk>. 1711 * <br>Otherwise, a {@link BeanRecursionException} is thrown with the message <js>"Recursion occurred, stack=..."</js>. 1712 * 1713 * <ul class='notes'> 1714 * <li> 1715 * Possible values: 1716 * <ul> 1717 * <li><js>"true"</js> 1718 * <li><js>"false"</js> (default) 1719 * </ul> 1720 * <li> 1721 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1722 * </ul> 1723 * 1724 * <ul class='seealso'> 1725 * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_ignoreRecursions} 1726 * </ul> 1727 */ 1728 String ignoreRecursions() default ""; 1729 1730 /** 1731 * Configuration property: Initial depth. 1732 * 1733 * <p> 1734 * The initial indentation level at the root. 1735 * <br>Useful when constructing document fragments that need to be indented at a certain level. 1736 * 1737 * <ul class='notes'> 1738 * <li> 1739 * Format: integer 1740 * <li> 1741 * Default value: <js>"0"</js> 1742 * <li> 1743 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1744 * </ul> 1745 * 1746 * <ul class='seealso'> 1747 * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_initialDepth} 1748 * </ul> 1749 */ 1750 String initialDepth() default ""; 1751 1752 /** 1753 * Configuration property: Max traversal depth. 1754 * 1755 * <p> 1756 * Abort traversal if specified depth is reached in the POJO tree. 1757 * <br>If this depth is exceeded, an exception is thrown. 1758 * 1759 * <ul class='notes'> 1760 * <li> 1761 * Format: integer 1762 * <li> 1763 * Default value: <js>"100"</js> 1764 * <li> 1765 * Supports {@doc DefaultVarResolver} (e.g. <js>"$C{myConfigVar}"</js>). 1766 * </ul> 1767 * 1768 * <ul class='seealso'> 1769 * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_maxDepth} 1770 * </ul> 1771 */ 1772 String maxDepth() default ""; 1773}