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 * <h2 class='section'>See Also:</h2><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 * <h4 class='section'>See Also:</h4><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 * <h4 class='section'>Example:</h4> 225 * <p class='bjava'> 226 * <ja>@Marshalled</ja>(example=<js>"{foo:'bar'}"</js>) 227 * <jk>public class</jk> MyClass {...} 228 * </p> 229 * 230 * <h4 class='section'>Notes:</h4><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 * <h4 class='section'>See Also:</h4><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 * <h4 class='section'>Example:</h4> 271 * <p class='bjava'> 272 * <ja>@Marshalled</ja>(implClass=MyInterfaceImpl.<jk>class</jk>) 273 * <jk>public class</jk> MyInterface {...} 274 * 275 * @return The annotation value. 276 */ 277 Class<?> implClass() default void.class; 278 279 /** 280 * Bean property interceptor. 281 * 282 * <p> 283 * Bean interceptors can be used to intercept calls to getters and setters and alter their values in transit. 284 * 285 * <h4 class='section'>See Also:</h4><ul> 286 * <li class='jc'>{@link BeanInterceptor} 287 * </ul> 288 * 289 * @return The annotation value. 290 */ 291 Class<? extends BeanInterceptor<?>> interceptor() default BeanInterceptor.Void.class; 292 293 /** 294 * An identifying name for this class. 295 * 296 * <p> 297 * The name is used to identify the class type during parsing when it cannot be inferred through reflection. 298 * <br>For example, if a bean property is of type <c>Object</c>, then the serializer will add the name to the 299 * output so that the class can be determined during parsing. 300 * 301 * <p> 302 * It is also used to specify element names in XML. 303 * 304 * <h4 class='section'>Example:</h4> 305 * <p class='bjava'> 306 * <jc>// Use _type='mybean' to identify this bean.</jc> 307 * <ja>@Marshalled</ja>(typeName=<js>"mybean"</js>) 308 * <jk>public class</jk> MyBean {...} 309 * </p> 310 * 311 * <h4 class='section'>See Also:</h4><ul> 312 * <li class='jm'>{@link MarshallingContext.Builder#beanDictionary(Class...)} 313 * </ul> 314 * 315 * @return The annotation value. 316 */ 317 String typeName() default ""; 318 319 /** 320 * The property name to use for representing the type name. 321 * 322 * <p> 323 * This can be used to override the name used for the <js>"_type"</js> property used by the {@link #typeName()} setting. 324 * 325 * <p> 326 * The default value if not specified is <js>"_type"</js>. 327 * 328 * <h4 class='section'>Example:</h4> 329 * <p class='bjava'> 330 * <jc>// Use 'type' instead of '_type' for bean names.</jc> 331 * <ja>@Marshalled</ja>(typePropertyName=<js>"type"</js>) 332 * <jk>public class</jk> MyBean {...} 333 * </p> 334 * 335 * <h4 class='section'>See Also:</h4><ul> 336 * <li class='ja'>{@link MarshalledConfig#typePropertyName()} 337 * <li class='jm'>{@link MarshallingContext.Builder#typePropertyName(String)} 338 * </ul> 339 * 340 * @return The annotation value. 341 */ 342 String typePropertyName() default ""; 343}