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.swap.*;
025
026/**
027 * Annotation for specifying config properties defined in {@link BeanContext} and {@link BeanTraverseContext}.
028 *
029 * <p>
030 * Used primarily for specifying bean configuration properties on REST classes and methods.
031 *
032 * <h5 class='section'>See Also:</h5><ul>
033 * </ul>
034 */
035@Target({TYPE,METHOD})
036@Retention(RUNTIME)
037@Inherited
038@ContextApply(BeanConfigAnnotation.Applier.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    * @return The annotation value.
048    */
049   int rank() default 0;
050
051   //-----------------------------------------------------------------------------------------------------------------
052   // BeanContext
053   //-----------------------------------------------------------------------------------------------------------------
054
055   /**
056    * Minimum bean class visibility.
057    *
058    * <p>
059    * Classes are not considered beans unless they meet the minimum visibility requirements.
060    *
061    * <p>
062    * For example, if the visibility is <c>PUBLIC</c> and the bean class is <jk>protected</jk>, then the class
063    * will not be interpreted as a bean class and be serialized as a string.
064    * <br>Use this setting to reduce the visibility requirement.
065    *
066    * <ul class='values'>
067    *    <li><js>"PUBLIC"</js> (default)
068    *    <li><js>"PROTECTED"</js>
069    *    <li><js>"DEFAULT"</js>
070    *    <li><js>"PRIVATE"</js>
071    * </ul>
072    *
073    * <h5 class='section'>Notes:</h5><ul>
074    *    <li class='note'>
075    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
076    * </ul>
077    *
078    * <h5 class='section'>See Also:</h5><ul>
079    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#beanClassVisibility(Visibility)}
080    * </ul>
081    *
082    * @return The annotation value.
083    */
084   String beanClassVisibility() default "";
085
086   /**
087    * Minimum bean constructor visibility.
088    *
089    * <p>
090    * Only look for constructors with the specified minimum visibility.
091    *
092    * <p>
093    * This setting affects the logic for finding no-arg constructors for bean.
094    * <br>Normally, only <jk>public</jk> no-arg constructors are used.
095    * <br>Use this setting if you want to reduce the visibility requirement.
096    *
097    * <ul class='values'>
098    *    <li><js>"PUBLIC"</js> (default)
099    *    <li><js>"PROTECTED"</js>
100    *    <li><js>"DEFAULT"</js>
101    *    <li><js>"PRIVATE"</js>
102    * </ul>
103    *
104    * <h5 class='section'>Notes:</h5><ul>
105    *    <li class='note'>
106    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
107    * </ul>
108    *
109    * <h5 class='section'>See Also:</h5><ul>
110    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#beanConstructorVisibility(Visibility)}
111    * </ul>
112    *
113    * @return The annotation value.
114    */
115   String beanConstructorVisibility() default "";
116
117   /**
118    * Minimum bean field visibility.
119    *
120    * <p>
121    * Only look for bean fields with the specified minimum visibility.
122    *
123    * <p>
124    * This affects which fields on a bean class are considered bean properties.
125    * <br>Normally only <jk>public</jk> fields are considered.
126    * <br>Use this setting if you want to reduce the visibility requirement.
127    *
128    * <ul class='values'>
129    *    <li><js>"PUBLIC"</js> (default)
130    *    <li><js>"PROTECTED"</js>
131    *    <li><js>"DEFAULT"</js>
132    *    <li><js>"PRIVATE"</js>
133    * </ul>
134    *
135    * <h5 class='section'>Notes:</h5><ul>
136    *    <li class='note'>
137    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
138    * </ul>
139    *
140    * <h5 class='section'>See Also:</h5><ul>
141    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#beanFieldVisibility(Visibility)}
142    * </ul>
143    *
144    * @return The annotation value.
145    */
146   String beanFieldVisibility() default "";
147
148   /**
149    * BeanMap.put() returns old property value.
150    *
151    * <p>
152    * If <js>"true"</js>, then the {@link BeanMap#put(String,Object) BeanMap.put()} method will return old property
153    * values.
154    * <br>Otherwise, it returns <jk>null</jk>.
155    *
156    * <ul class='values'>
157    *    <li><js>"true"</js>
158    *    <li><js>"false"</js> (default because it introduces a slight performance penalty during serialization)
159    * </ul>
160    *
161    * <h5 class='section'>Notes:</h5><ul>
162    *    <li class='note'>
163    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
164    * </ul>
165    *
166    * <h5 class='section'>See Also:</h5><ul>
167    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#beanMapPutReturnsOldValue()}
168    * </ul>
169    *
170    * @return The annotation value.
171    */
172   String beanMapPutReturnsOldValue() default "";
173
174   /**
175    * Minimum bean method visibility.
176    *
177    * <p>
178    * Only look for bean methods with the specified minimum visibility.
179    *
180    * <p>
181    * This affects which methods are detected as getters and setters on a bean class.
182    * <br>Normally only <jk>public</jk> getters and setters are considered.
183    * <br>Use this setting if you want to reduce the visibility requirement.
184    *
185    * <ul class='values'>
186    *    <li><js>"PUBLIC"</js> (default)
187    *    <li><js>"PROTECTED"</js>
188    *    <li><js>"DEFAULT"</js>
189    *    <li><js>"PRIVATE"</js>
190    * </ul>
191    *
192    * <h5 class='section'>Notes:</h5><ul>
193    *    <li class='note'>
194    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
195    * </ul>
196    *
197    * <h5 class='section'>See Also:</h5><ul>
198    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#beanMethodVisibility(Visibility)}
199    * </ul>
200    *
201    * @return The annotation value.
202    */
203   String beanMethodVisibility() default "";
204
205   /**
206    * Beans require no-arg constructors.
207    *
208    * <p>
209    * If <js>"true"</js>, a Java class must implement a default no-arg constructor to be considered a bean.
210    * <br>Otherwise, the bean will be serialized as a string using the {@link Object#toString()} method.
211    *
212    * <ul class='values'>
213    *    <li><js>"true"</js>
214    *    <li><js>"false"</js> (default)
215    * </ul>
216    *
217    * <h5 class='section'>Notes:</h5><ul>
218    *    <li class='note'>
219    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
220    *    <li class='note'>
221    *       The {@link Bean @Bean} annotation can be used on a class to override this setting when <js>"true"</js>.
222    * </ul>
223    *
224    * <h5 class='section'>See Also:</h5><ul>
225    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#beansRequireDefaultConstructor()}
226    * </ul>
227    *
228    * @return The annotation value.
229    */
230   String beansRequireDefaultConstructor() default "";
231
232   /**
233    * Beans require Serializable interface.
234    *
235    * <p>
236    * If <js>"true"</js>, a Java class must implement the {@link Serializable} interface to be considered a bean.
237    * <br>Otherwise, the bean will be serialized as a string using the {@link Object#toString()} method.
238    *
239    * <ul class='values'>
240    *    <li><js>"true"</js>
241    *    <li><js>"false"</js> (default)
242    * </ul>
243    *
244    * <h5 class='section'>Notes:</h5><ul>
245    *    <li class='note'>
246    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
247    *    <li class='note'>
248    *       The {@link Bean @Bean} annotation can be used on a class to override this setting when <js>"true"</js>.
249    * </ul>
250    *
251    * <h5 class='section'>See Also:</h5><ul>
252    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#beansRequireSerializable()}
253    * </ul>
254    *
255    * @return The annotation value.
256    */
257   String beansRequireSerializable() default "";
258
259   /**
260    * Beans require setters for getters.
261    *
262    * <p>
263    * If <js>"true"</js>, only getters that have equivalent setters will be considered as properties on a bean.
264    * <br>Otherwise, they will be ignored.
265    *
266    * <ul class='values'>
267    *    <li><js>"true"</js>
268    *    <li><js>"false"</js> (default)
269    * </ul>
270    *
271    * <h5 class='section'>Notes:</h5><ul>
272    *    <li class='note'>
273    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
274    * </ul>
275    *
276    * <h5 class='section'>See Also:</h5><ul>
277    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#beansRequireSettersForGetters()}
278    * </ul>
279    *
280    * @return The annotation value.
281    */
282   String beansRequireSettersForGetters() default "";
283
284   /**
285    * Beans don't require at least one property.
286    *
287    * <p>
288    * If <js>"true"</js>, then a Java class doesn't need to contain at least 1 property to be considered a bean.
289    * <br>Otherwise, the bean will be serialized as a string using the {@link Object#toString()} method.
290    *
291    * <ul class='values'>
292    *    <li><js>"true"</js>
293    *    <li><js>"false"</js> (default)
294    * </ul>
295    *
296    * <h5 class='section'>Notes:</h5><ul>
297    *    <li class='note'>
298    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
299    * </ul>
300    *
301    * <h5 class='section'>See Also:</h5><ul>
302    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#disableBeansRequireSomeProperties()}
303    * </ul>
304    *
305    * @return The annotation value.
306    */
307   String disableBeansRequireSomeProperties() default "";
308
309   /**
310    * Bean type property name.
311    *
312    * <p>
313    * This specifies the name of the bean property used to store the dictionary name of a bean type so that the
314    * parser knows the data type to reconstruct.
315    *
316    * <h5 class='section'>Notes:</h5><ul>
317    *    <li class='note'>
318    *       Default value: <js>"_type"</js>.
319    *    <li class='note'>
320    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
321    * </ul>
322
323    * <h5 class='section'>See Also:</h5><ul>
324    *    <li class='ja'>{@link Bean#typePropertyName()}
325    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#typePropertyName(String)}
326    * </ul>
327    *
328    * @return The annotation value.
329    */
330   String typePropertyName() default "";
331
332   /**
333    * Debug mode.
334    *
335    * <p>
336    * Enables the following additional information during serialization:
337    * <ul class='spaced-list'>
338    *    <li>
339    *       When bean getters throws exceptions, the exception includes the object stack information
340    *       in order to determine how that method was invoked.
341    *    <li>
342    *       Enables {@link org.apache.juneau.BeanTraverseContext.Builder#detectRecursions()}.
343    * </ul>
344    *
345    * <p>
346    * Enables the following additional information during parsing:
347    * <ul class='spaced-list'>
348    *    <li>
349    *       When bean setters throws exceptions, the exception includes the object stack information
350    *       in order to determine how that method was invoked.
351    * </ul>
352    *
353    * <ul class='values'>
354    *    <li><js>"true"</js>
355    *    <li><js>"false"</js> (default)
356    * </ul>
357    *
358    * <h5 class='section'>Notes:</h5><ul>
359    *    <li class='note'>
360    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
361    * </ul>
362    *
363    * <h5 class='section'>See Also:</h5><ul>
364    *    <li class='jm'>{@link org.apache.juneau.Context.Builder#debug()}
365    * </ul>
366    *
367    * @return The annotation value.
368    */
369   String debug() default "";
370
371   /**
372    * Bean dictionary.
373    *
374    * <p>
375    * The list of classes that make up the bean dictionary in this bean context.
376    *
377    * <p>
378    * A dictionary is a name/class mapping used to find class types during parsing when they cannot be inferred
379    * through reflection.
380    * <br>The names are defined through the {@link Bean#typeName() @Bean(typeName)} annotation defined on the bean class.
381    * <br>For example, if a class <c>Foo</c> has a type-name of <js>"myfoo"</js>, then it would end up serialized
382    * as <js>"{_type:'myfoo',...}"</js>.
383    *
384    * <p>
385    * This setting tells the parsers which classes to look for when resolving <js>"_type"</js> attributes.
386    *
387    * <h5 class='section'>See Also:</h5><ul>
388    *    <li class='ja'>{@link Bean#dictionary()}
389    *    <li class='ja'>{@link Beanp#dictionary()}
390    *    <li class='ja'>{@link BeanConfig#dictionary_replace()}
391    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#beanDictionary(Class...)}
392    *    <li class='link'><a class="doclink" href="../../../../index.html#jm.BeanDictionaries">Bean Names and Dictionaries</a>
393    * </ul>
394    *
395    * @return The annotation value.
396    */
397   Class<?>[] dictionary() default {};
398
399   /**
400    * Replace bean dictionary.
401    *
402    * <p>
403    * Same as {@link #dictionary()} but replaces any existing value.
404    *
405    * <h5 class='section'>See Also:</h5><ul>
406    *    <li class='ja'>{@link Bean#dictionary()}
407    *    <li class='ja'>{@link Beanp#dictionary()}
408    *    <li class='ja'>{@link BeanConfig#dictionary()}
409    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#beanDictionary(Class...)}
410    * </ul>
411    *
412    * @return The annotation value.
413    */
414   Class<?>[] dictionary_replace() default {};
415
416   /**
417    * Find fluent setters.
418    *
419    * <p>
420    * When enabled, fluent setters are detected on beans.
421    *
422    * <p>
423    * Fluent setters must have the following attributes:
424    * <ul>
425    *    <li>Public.
426    *    <li>Not static.
427    *    <li>Take in one parameter.
428    *    <li>Return the bean itself.
429    * </ul>
430    *
431    * <ul class='values'>
432    *    <li><js>"true"</js>
433    *    <li><js>"false"</js> (default)
434    * </ul>
435    *
436    * <h5 class='section'>Notes:</h5><ul>
437    *    <li class='note'>
438    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
439    * </ul>
440    *
441    * <h5 class='section'>See Also:</h5><ul>
442    *    <li class='ja'>{@link Bean#findFluentSetters()}
443    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#findFluentSetters()}
444    * </ul>
445    *
446    * @return The annotation value.
447    */
448   String findFluentSetters() default "";
449
450   /**
451    * Ignore invocation errors on getters.
452    *
453    * <p>
454    * If <js>"true"</js>, errors thrown when calling bean getter methods will silently be ignored.
455    * <br>Otherwise, a {@code BeanRuntimeException} is thrown.
456    *
457    * <ul class='values'>
458    *    <li><js>"true"</js>
459    *    <li><js>"false"</js> (default)
460    * </ul>
461    *
462    * <h5 class='section'>Notes:</h5><ul>
463    *    <li class='note'>
464    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
465    * </ul>
466    *
467    * <h5 class='section'>See Also:</h5><ul>
468    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#ignoreInvocationExceptionsOnGetters()}
469    * </ul>
470    *
471    * @return The annotation value.
472    */
473   String ignoreInvocationExceptionsOnGetters() default "";
474
475   /**
476    * Ignore invocation errors on setters.
477    *
478    * <p>
479    * If <js>"true"</js>, errors thrown when calling bean setter methods will silently be ignored.
480    * <br>Otherwise, a {@code BeanRuntimeException} is thrown.
481    *
482    * <ul class='values'>
483    *    <li><js>"true"</js>
484    *    <li><js>"false"</js> (default)
485    * </ul>
486    *
487    * <h5 class='section'>Notes:</h5><ul>
488    *    <li class='note'>
489    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
490    * </ul>
491    *
492    * <h5 class='section'>See Also:</h5><ul>
493    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#ignoreInvocationExceptionsOnSetters()}
494    * </ul>
495    *
496    * @return The annotation value.
497    */
498   String ignoreInvocationExceptionsOnSetters() default "";
499
500   /**
501    * Don't silently ignore missing setters.
502    *
503    * <p>
504    * If <js>"true"</js>, trying to set a value on a bean property without a setter will throw a {@code BeanRuntimeException}.
505    * <br>Otherwise it will be sliently ignored.
506    *
507    * <ul class='values'>
508    *    <li><js>"true"</js>
509    *    <li><js>"false"</js> (default)
510    * </ul>
511    *
512    * <h5 class='section'>Notes:</h5><ul>
513    *    <li class='note'>
514    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
515    * </ul>
516    *
517    * <h5 class='section'>See Also:</h5><ul>
518    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#disableIgnoreMissingSetters()}
519    * </ul>
520    *
521    * @return The annotation value.
522    */
523   String disableIgnoreMissingSetters() default "";
524
525   /**
526    * Don't ignore transient fields.
527    *
528    * <p>
529    * If <jk>true</jk>, methods and fields marked as <jk>transient</jk> will not be ignored as bean properties.
530    *
531    * <ul class='values'>
532    *    <li><js>"true"</js>
533    *    <li><js>"false"</js> (default)
534    * </ul>
535    *
536    * <h5 class='section'>Notes:</h5><ul>
537    *    <li class='note'>
538    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
539    * </ul>
540    *
541    * <h5 class='section'>See Also:</h5><ul>
542    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#disableIgnoreTransientFields()}
543    * </ul>
544    *
545    * @return The annotation value.
546    */
547   String disableIgnoreTransientFields() default "";
548
549   /**
550    * Ignore unknown properties.
551    *
552    * <p>
553    * If <js>"true"</js>, trying to set a value on a non-existent bean property will silently be ignored.
554    * <br>Otherwise, a {@code RuntimeException} is thrown.
555    *
556    * <ul class='values'>
557    *    <li><js>"true"</js>
558    *    <li><js>"false"</js> (default)
559    * </ul>
560    *
561    * <h5 class='section'>Notes:</h5><ul>
562    *    <li class='note'>
563    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
564    * </ul>
565    *
566    * <h5 class='section'>See Also:</h5><ul>
567    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#ignoreUnknownBeanProperties()}
568    * </ul>
569    *
570    * @return The annotation value.
571    */
572   String ignoreUnknownBeanProperties() default "";
573
574   /**
575    * Ignore unknown enum values.
576    *
577    * <p>
578    * If <js>"true"</js>, unknown enum values are set to <jk>null</jk> instead of throwing an exception.
579    *
580    * <ul class='values'>
581    *    <li><js>"true"</js>
582    *    <li><js>"false"</js> (default)
583    * </ul>
584    *
585    * <h5 class='section'>Notes:</h5><ul>
586    *    <li class='note'>
587    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
588    * </ul>
589    *
590    * <h5 class='section'>See Also:</h5><ul>
591    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#ignoreUnknownEnumValues()}
592    * </ul>
593    *
594    * @return The annotation value.
595    */
596   String ignoreUnknownEnumValues() default "";
597
598   /**
599    * Don't ignore unknown properties with null values.
600    *
601    * <p>
602    * If <js>"true"</js>, trying to set a <jk>null</jk> value on a non-existent bean property will throw a {@code BeanRuntimeException}.
603    * Otherwise it will be silently ignored.
604    *
605    * <ul class='values'>
606    *    <li><js>"true"</js>
607    *    <li><js>"false"</js> (default)
608    * </ul>
609    *
610    * <h5 class='section'>Notes:</h5><ul>
611    *    <li class='note'>
612    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
613    * </ul>
614    *
615    * <h5 class='section'>See Also:</h5><ul>
616    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#disableIgnoreUnknownNullBeanProperties()}
617    * </ul>
618    *
619    * @return The annotation value.
620    */
621   String disableIgnoreUnknownNullBeanProperties() default "";
622
623   /**
624    * Identifies a set of interfaces.
625    *
626    * <p>
627    * When specified, only the list of properties defined on the interface class will be used during serialization
628    * of implementation classes.  Additional properties on subclasses will be ignored.
629    *
630    * <p class='bjava'>
631    *    <jc>// Parent class or interface</jc>
632    *    <jk>public abstract class</jk> A {
633    *       <jk>public</jk> String <jf>foo</jf> = <js>"foo"</js>;
634    *    }
635    *
636    *    <jc>// Sub class</jc>
637    *    <jk>public class</jk> A1 <jk>extends</jk> A {
638    *       <jk>public</jk> String <jf>bar</jf> = <js>"bar"</js>;
639    *    }
640    *
641    *    <jc>// Apply it to a config</jc>
642    *    <ja>@BeanConfig</ja>(
643    *       interfaces={
644    *          A.<jk>class</jk>
645    *       }
646    *    )
647    * </p>
648    *
649    * <p>
650    * This annotation can be used on the parent class so that it filters to all child classes, or can be set
651    * individually on the child classes.
652    *
653    * <h5 class='section'>Notes:</h5><ul>
654    *    <li class='note'>The {@link Bean#interfaceClass() @Bean(interfaceClass)} annotation is the equivalent annotation-based solution.
655    * </ul>
656    *
657    * @return The annotation value.
658    */
659   Class<?>[] interfaces() default {};
660
661   /**
662    * Locale.
663    *
664    * <p>
665    * Specifies the default locale for serializer and parser sessions.
666    *
667    * <h5 class='section'>Notes:</h5><ul>
668    *    <li class='note'>
669    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
670    * </ul>
671    *
672    * <h5 class='section'>See Also:</h5><ul>
673    *    <li class='jm'>{@link org.apache.juneau.BeanSession.Builder#locale(Locale)}
674    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#locale(Locale)}
675    * </ul>
676    *
677    * @return The annotation value.
678    */
679   String locale() default "";
680
681   /**
682    * Media type.
683    *
684    * <p>
685    * Specifies the default media type value for serializer and parser sessions.
686    *
687    * <h5 class='section'>Notes:</h5><ul>
688    *    <li class='note'>
689    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
690    * </ul>
691    *
692    * <h5 class='section'>See Also:</h5><ul>
693    *    <li class='jm'>{@link org.apache.juneau.BeanSession.Builder#mediaType(MediaType)}
694    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#mediaType(MediaType)}
695    * </ul>
696    *
697    * @return The annotation value.
698    */
699   String mediaType() default "";
700
701   /**
702    * Bean class exclusions.
703    *
704    * <p>
705    * List of classes that should not be treated as beans even if they appear to be bean-like.
706    * <br>Not-bean classes are converted to <c>Strings</c> during serialization.
707    *
708    * <h5 class='section'>Notes:</h5><ul>
709    *    <li class='note'>
710    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
711    * </ul>
712    *
713    * <h5 class='section'>See Also:</h5><ul>
714    *    <li class='ja'>{@link BeanIgnore}
715    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#notBeanClasses(Class...)}
716    * </ul>
717    *
718    * @return The annotation value.
719    */
720   Class<?>[] notBeanClasses() default {};
721
722   /**
723    * Replace classes that should not be considered beans.
724    *
725    * <p>
726    * Same as {@link #notBeanClasses()} but replaces any existing value.
727    *
728    * <h5 class='section'>See Also:</h5><ul>
729    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#notBeanClasses(Class...)}
730    * </ul>
731    *
732    * @return The annotation value.
733    */
734   Class<?>[] notBeanClasses_replace() default {};
735
736   /**
737    * Bean package exclusions.
738    *
739    * <p>
740    * When specified, the current list of ignore packages are appended to.
741    *
742    * <p>
743    * Any classes within these packages will be serialized to strings using {@link Object#toString()}.
744    *
745    * <p>
746    * Note that you can specify suffix patterns to include all subpackages.
747    *
748    * <h5 class='section'>Notes:</h5><ul>
749    *    <li class='note'>
750    *       The default value excludes the following packages:
751    *       <ul class='compact'>
752    *          <li class='jp'><c>java.lang</c>
753    *          <li class='jp'><c>java.lang.annotation</c>
754    *          <li class='jp'><c>java.lang.ref</c>
755    *          <li class='jp'><c>java.lang.reflect</c>
756    *          <li class='jp'><c>java.io</c>
757    *          <li class='jp'><c>java.net</c>
758    *          <li class='jp'><c>java.nio.*</c>
759    *          <li class='jp'><c>java.util.*</c>
760    *       </ul>
761    *    <li class='note'>
762    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
763    * </ul>
764    *
765    * <h5 class='section'>See Also:</h5><ul>
766    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#notBeanPackages(String...)}
767    * </ul>
768    *
769    * @return The annotation value.
770    */
771   String[] notBeanPackages() default {};
772
773   /**
774    * Replace packages whose classes should not be considered beans.
775    *
776    * <p>
777    * Same as {@link #notBeanPackages()} but replaces any existing value.
778    *
779    * <h5 class='section'>See Also:</h5><ul>
780    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#notBeanPackages(String...)}
781    * </ul>
782    *
783    * @return The annotation value.
784    */
785   String[] notBeanPackages_replace() default {};
786
787   /**
788    * Bean property namer.
789    *
790    * <p>
791    * The class to use for calculating bean property names.
792    *
793    * <p>
794    * Predefined classes:
795    * <ul>
796    *    <li>{@link BasicPropertyNamer} (default)
797    *    <li>{@link PropertyNamerDLC} - Dashed-lower-case names.
798    *    <li>{@link PropertyNamerULC} - Dashed-upper-case names.
799    * </ul>
800    *
801    * <h5 class='section'>See Also:</h5><ul>
802    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#propertyNamer(Class)}
803    * </ul>
804    *
805    * @return The annotation value.
806    */
807   Class<? extends PropertyNamer> propertyNamer() default PropertyNamer.Void.class;
808
809   /**
810    * Sort bean properties.
811    *
812    * <p>
813    * When <jk>true</jk>, all bean properties will be serialized and access in alphabetical order.
814    * <br>Otherwise, the natural order of the bean properties is used which is dependent on the JVM vendor.
815    * <br>On IBM JVMs, the bean properties are ordered based on their ordering in the Java file.
816    * <br>On Oracle JVMs, the bean properties are not ordered (which follows the official JVM specs).
817    *
818    * <p>
819    * This property is disabled by default so that IBM JVM users don't have to use {@link Bean @Bean} annotations
820    * to force bean properties to be in a particular order and can just alter the order of the fields/methods
821    * in the Java file.
822    *
823    * <ul class='values'>
824    *    <li><js>"true"</js>
825    *    <li><js>"false"</js> (default)
826    * </ul>
827    *
828    * <h5 class='section'>Notes:</h5><ul>
829    *    <li>
830    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
831    * </ul>
832    *
833    * <h5 class='section'>See Also:</h5><ul>
834    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#sortProperties()}
835    * </ul>
836    *
837    * @return The annotation value.
838    */
839   String sortProperties() default "";
840
841   /**
842    * Java object swaps.
843    *
844    * <p>
845    * Swaps are used to "swap out" non-serializable classes with serializable equivalents during serialization,
846    * and "swap in" the non-serializable class during parsing.
847    *
848    * <p>
849    * An example of a swap would be a <c>Calendar</c> object that gets swapped out for an ISO8601 string.
850    *
851    * <p>
852    * Multiple swaps can be associated with a single class.
853    * <br>When multiple swaps are applicable to the same class, the media type pattern defined by
854    * {@link ObjectSwap#forMediaTypes()} or {@link Swap#mediaTypes() @Swap(mediaTypes)} are used to come up with the best match.
855    *
856    * <h5 class='section'>See Also:</h5><ul>
857    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#swaps(Class...)}
858    *    <li class='link'><a class="doclink" href="../../../../index.html#jm.Swaps">Swaps</a>
859    *    <li class='link'><a class="doclink" href="../../../../index.html#jm.PerMediaTypeSwaps">Per-media-type Swaps</a>
860    *    <li class='link'><a class="doclink" href="../../../../index.html#jm.OneWaySwaps">One-way Swaps</a>
861    *    <li class='link'><a class="doclink" href="../../../../index.html#jm.SwapAnnotation">@Swap Annotation</a>
862    *    <li class='link'><a class="doclink" href="../../../../index.html#jm.AutoSwaps">Auto-detected swaps</a>
863    *    <li class='link'><a class="doclink" href="../../../../index.html#jm.SurrogateClasses">Surrogate Classes</a>
864    * </ul>
865    *
866    * @return The annotation value.
867    */
868   Class<?>[] swaps() default {};
869
870   /**
871    * Replace Java object swap classes.
872    *
873    * <p>
874    * Same as {@link #swaps()} but replaces any existing value.
875    *
876    * <h5 class='section'>See Also:</h5><ul>
877    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#swaps(Class...)}
878    * </ul>
879    *
880    * @return The annotation value.
881    */
882   Class<?>[] swaps_replace() default {};
883
884   /**
885    * Time zone.
886    *
887    * <p>
888    * Specifies the default timezone for serializer and parser sessions.
889    *
890    * <h5 class='section'>Notes:</h5><ul>
891    *    <li class='note'>
892    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
893    * </ul>
894    *
895    * <h5 class='section'>See Also:</h5><ul>
896    *    <li class='jm'>{@link org.apache.juneau.BeanSession.Builder#timeZone(TimeZone)}
897    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#timeZone(TimeZone)}
898    * </ul>
899    *
900    * @return The annotation value.
901    */
902   String timeZone() default "";
903
904   /**
905    * Use enum names.
906    *
907    * <p>
908    * When enabled, enums are always serialized by name, not using {@link Object#toString()}.
909    *
910    * <ul class='values'>
911    *    <li><js>"true"</js>
912    *    <li><js>"false"</js> (default)
913    * </ul>
914    *
915    * <h5 class='section'>Notes:</h5><ul>
916    *    <li class='note'>
917    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
918    * </ul>
919    *
920    * <h5 class='section'>See Also:</h5><ul>
921    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#useEnumNames()}
922    * </ul>
923    *
924    * @return The annotation value.
925    */
926   String useEnumNames() default "";
927
928   /**
929    * Don't use interface proxies.
930    *
931    * <p>
932    * Disables the feature where interfaces will be instantiated as proxy classes through the use of an
933    * {@link InvocationHandler} if there is no other way of instantiating them.
934    * <br>Setting this to <js>"true"</js> causes this to be a {@link BeanRuntimeException}.
935    *
936    * <ul class='values'>
937    *    <li><js>"true"</js>
938    *    <li><js>"false"</js> (default)
939    * </ul>
940    *
941    * <h5 class='section'>Notes:</h5><ul>
942    *    <li class='note'>
943    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
944    * </ul>
945    *
946    * <h5 class='section'>See Also:</h5><ul>
947    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#disableInterfaceProxies()}
948    * </ul>
949    *
950    * @return The annotation value.
951    */
952   String disableInterfaceProxies() default "";
953
954   /**
955    * Use Java Introspector.
956    *
957    * <p>
958    * Using the built-in Java bean introspector will not pick up fields or non-standard getters/setters.
959    * <br>Most {@link Bean @Bean} annotations will be ignored.
960    *
961    * <ul class='values'>
962    *    <li><js>"true"</js>
963    *    <li><js>"false"</js> (default)
964    * </ul>
965    *
966    * <h5 class='section'>Notes:</h5><ul>
967    *    <li class='note'>
968    *       Supports <a class="doclink" href="../../../../index.html#jm.DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
969    * </ul>
970    *
971    * <h5 class='section'>See Also:</h5><ul>
972    *    <li class='jm'>{@link org.apache.juneau.BeanContext.Builder#useJavaBeanIntrospector()}
973    * </ul>
974    *
975    * @return The annotation value.
976    */
977   String useJavaBeanIntrospector() default "";
978}