Source code

001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.marshall;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023import java.math.*;
024import java.util.*;
025
026import org.apache.juneau.commons.*;
027import org.apache.juneau.commons.bean.*;
028
029/**
030 * Annotation that can be applied to classes to control how they are marshalled.
031 *
032 * <p>
033 * Carries the marshalling-only attributes for a class — bean-modeling attributes (such as
034 * {@code properties}, {@code excludeProperties}, {@code findFluentSetters}, {@code interfaceClass},
035 * {@code stopClass}, {@code propertyNamer}, {@code unsorted}, {@code factory}, etc.) live on
036 * {@link BeanType @BeanType} in <c>juneau-commons</c>.
037 *
038 * <p>
039 * Can be used in the following locations:
040 * <ul>
041 *    <li>Bean classes and parent interfaces.
042 *    <li>Non-bean marshalled classes.
043 *    <li><ja>@Rest</ja>-annotated classes and <ja>@RestOp</ja>-annotated methods when used with {@link MarshalledApply @MarshalledApply}.
044 * </ul>
045 *
046 * <h5 class='section'>See Also:</h5><ul>
047 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/MarshalledAnnotation">@Marshalled Annotation</a>
048 * </ul>
049 */
050@Documented
051@Target({ TYPE })
052@Retention(RUNTIME)
053@Inherited
054@SuppressWarnings({
055   "java:S1452"  // Wildcard required - Class<? extends BeanInterceptor<?>> for interceptor definition
056})
057public @interface Marshalled {
058
059   /**
060    * Specifies the marshalling strategy for this type.
061    *
062    * <p>
063    * Defaults to {@link MarshalledAs#DETECT} (auto-detection).
064    * Use {@link MarshalledAs#STRING} to serialize via {@code toString()} and deserialize via
065    * {@code fromString}/{@code valueOf}/single-String constructor — equivalent to the former
066    * {@code MarshallingStringSwap} pattern.
067    *
068    * @return The marshalling strategy.
069    */
070   MarshalledAs as() default MarshalledAs.DETECT;
071
072   /**
073    * Optional description for the exposed API.
074    *
075    * @return The annotation value.
076    * @since 9.2.0
077    */
078   String[] description() default {};
079
080   /**
081    * Short, concise summary of the exposed API.
082    *
083    * <p>
084    * Intended as a brief, single-line description suitable for AI/LLM consumption, compact documentation,
085    * or any context where brevity matters. See {@link Schema#summary()}
086    * for the canonical definition; this field is the type-level counterpart.
087    *
088    * @return The annotation value.
089    * @since 10.0.0
090    */
091   String summary() default "";
092
093   /**
094    * Bean dictionary.
095    *
096    * <p>
097    * The list of classes that make up the bean dictionary for all properties in this class and all subclasses.
098    *
099    * <h5 class='section'>See Also:</h5><ul>
100    *    <li class='ja'>{@link MarshalledProp#dictionary()}
101    *    <li class='ja'>{@link MarshalledConfig#dictionary()}
102    *    <li class='ja'>{@link MarshalledConfig#dictionary_replace()}
103    *    <li class='jm'>{@link MarshallingContext.Builder#beanDictionary(Class...)}
104    * </ul>
105    *
106    * @return The annotation value.
107    */
108   Class<?>[] dictionary() default {};
109
110   /**
111    * Calendar wire format override.
112    *
113    * @return The annotation value.
114    */
115   CalendarFormat calendarFormat() default CalendarFormat.NOT_SET;
116
117   /**
118    * Date wire format override.
119    *
120    * @return The annotation value.
121    */
122   DateFormat dateFormat() default DateFormat.NOT_SET;
123
124   /**
125    * Duration wire format override.
126    *
127    * @return The annotation value.
128    */
129   DurationFormat durationFormat() default DurationFormat.NOT_SET;
130
131   /**
132    * Locale wire format override.
133    *
134    * @return The annotation value.
135    */
136   LocaleFormat localeFormat() default LocaleFormat.NOT_SET;
137
138   /**
139    * Temporal wire format override.
140    *
141    * @return The annotation value.
142    */
143   TemporalFormat temporalFormat() default TemporalFormat.NOT_SET;
144
145   /**
146    * Time-zone wire format override.
147    *
148    * @return The annotation value.
149    */
150   TimeZoneFormat timeZoneFormat() default TimeZoneFormat.NOT_SET;
151
152   /**
153    * Binary wire format override for <code><jk>byte</jk>[]</code> values.
154    *
155    * @return The annotation value.
156    */
157   BinaryFormat binaryFormat() default BinaryFormat.NOT_SET;
158
159   /**
160    * Enum wire format override.
161    *
162    * @return The annotation value.
163    */
164   EnumFormat enumFormat() default EnumFormat.NOT_SET;
165
166   /**
167    * UUID wire format override.
168    *
169    * @return The annotation value.
170    */
171   UuidFormat uuidFormat() default UuidFormat.NOT_SET;
172
173   /**
174    * BitSet wire format override.
175    *
176    * @return The annotation value.
177    */
178   BitSetFormat bitSetFormat() default BitSetFormat.NOT_SET;
179
180   /**
181    * Big-number wire format override for {@link BigInteger} / {@link BigDecimal} values.
182    *
183    * @return The annotation value.
184    */
185   BigNumberFormat bigNumberFormat() default BigNumberFormat.NOT_SET;
186
187   /**
188    * Boolean wire format override for {@link Boolean} / <code><jk>boolean</jk></code> values.
189    *
190    * @return The annotation value.
191    */
192   BooleanFormat booleanFormat() default BooleanFormat.NOT_SET;
193
194   /**
195    * Float / Double non-finite wire format override for {@link Float} / {@link Double} values.
196    *
197    * @return The annotation value.
198    */
199   FloatFormat floatFormat() default FloatFormat.NOT_SET;
200
201   /**
202    * Currency wire format override for {@link Currency} values.
203    *
204    * @return The annotation value.
205    */
206   CurrencyFormat currencyFormat() default CurrencyFormat.NOT_SET;
207
208   /**
209    * Class wire format override for {@link Class} values.
210    *
211    * @return The annotation value.
212    */
213   ClassFormat classFormat() default ClassFormat.NOT_SET;
214
215   /**
216    * POJO example.
217    *
218    * <p>
219    * Specifies an example of the specified class in Simplified JSON format.
220    *
221    * <p>
222    * Examples are used in cases such as POJO examples in Swagger documents.
223    *
224    * <h5 class='section'>Example:</h5>
225    * <p class='bjava'>
226    *    <ja>@Marshalled</ja>(example=<js>"{foo:'bar'}"</js>)
227    *    <jk>public class</jk> MyClass {...}
228    * </p>
229    *
230    * <h5 class='section'>Notes:</h5><ul>
231    *    <li class='note'>
232    *       Setting applies to specified class and all subclasses.
233    *    <li class='note'>
234    *       Keys are the class of the example.
235    *       <br>Values are JSON 5 representation of that class.
236    *    <li class='note'>
237    *       POJO examples can also be defined on classes via the following:
238    *       <ul class='spaced-list'>
239    *          <li>A static field annotated with {@link Example @Example}.
240    *          <li>A static method annotated with {@link Example @Example} with zero arguments or one {@link MarshallingSession} argument.
241    *          <li>A static method with name <c>example</c> with no arguments or one {@link MarshallingSession} argument.
242    *       </ul>
243    *    <li class='note'>
244    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>).
245    * </ul>
246    *
247    * <h5 class='section'>See Also:</h5><ul>
248    *    <li class='ja'>{@link Example}
249    * </ul>
250    *
251    * @return The annotation value.
252    */
253   String example() default "";
254
255   /**
256    * Period wire format override.
257    *
258    * @return The annotation value.
259    */
260   PeriodFormat periodFormat() default PeriodFormat.NOT_SET;
261
262   /**
263    * Implementation class.
264    *
265    * <p>
266    * For interfaces and abstract classes this method can be used to specify an implementation class for the
267    * interface/abstract class so that instances of the implementation class are used when instantiated (e.g. during a
268    * parse).
269    *
270    * <h5 class='section'>Example:</h5>
271    * <p class='bjava'>
272    *    <ja>@Marshalled</ja>(implClass=MyInterfaceImpl.<jk>class</jk>)
273    *    <jk>public class</jk> MyInterface {...}
274    * <p>
275    *
276    * @return The annotation value.
277    */
278   Class<?> implClass() default void.class;
279
280   /**
281    * Bean property interceptor.
282    *
283    * <p>
284    * Bean interceptors can be used to intercept calls to getters and setters and alter their values in transit.
285    *
286    * <h5 class='section'>See Also:</h5><ul>
287    *    <li class='jc'>{@link BeanInterceptor}
288    * </ul>
289    *
290    * @return The annotation value.
291    */
292   Class<? extends BeanInterceptor<?>> interceptor() default BeanInterceptor.Void.class;
293
294   /**
295    * An identifying name for this class.
296    *
297    * <p>
298    * The name is used to identify the class type during parsing when it cannot be inferred through reflection.
299    * <br>For example, if a bean property is of type <c>Object</c>, then the serializer will add the name to the
300    * output so that the class can be determined during parsing.
301    *
302    * <p>
303    * It is also used to specify element names in XML.
304    *
305    * <h5 class='section'>Example:</h5>
306    * <p class='bjava'>
307    *    <jc>// Use _type='mybean' to identify this bean.</jc>
308    *    <ja>@Marshalled</ja>(typeName=<js>"mybean"</js>)
309    *    <jk>public class</jk> MyBean {...}
310    * </p>
311    *
312    * <h5 class='section'>See Also:</h5><ul>
313    *    <li class='jm'>{@link MarshallingContext.Builder#beanDictionary(Class...)}
314    * </ul>
315    *
316    * @return The annotation value.
317    */
318   String typeName() default "";
319
320   /**
321    * The property name to use for representing the type name.
322    *
323    * <p>
324    * This can be used to override the name used for the <js>"_type"</js> property used by the {@link #typeName()} setting.
325    *
326    * <p>
327    * The default value if not specified is <js>"_type"</js>.
328    *
329    * <h5 class='section'>Example:</h5>
330    * <p class='bjava'>
331    *    <jc>// Use 'type' instead of '_type' for bean names.</jc>
332    *    <ja>@Marshalled</ja>(typePropertyName=<js>"type"</js>)
333    *    <jk>public class</jk> MyBean {...}
334    * </p>
335    *
336    * <h5 class='section'>See Also:</h5><ul>
337    *    <li class='ja'>{@link MarshalledConfig#typePropertyName()}
338    *    <li class='jm'>{@link MarshallingContext.Builder#typePropertyName(String)}
339    * </ul>
340    *
341    * @return The annotation value.
342    */
343   String typePropertyName() default "";
344}