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.bean.*; 027import org.apache.juneau.commons.http.*; 028import org.apache.juneau.marshall.swap.spi.*; 029 030/** 031 * Annotation for specifying marshalling-only config properties defined in {@link MarshallingContext} and {@link MarshallingTraverseContext}. 032 * 033 * <p> 034 * Used primarily for specifying marshalling configuration properties on REST classes and methods. 035 * 036 * <p> 037 * This annotation is the marshalling-only sibling of {@code @BeanConfig}. 038 * Bean-modeling attributes (visibility settings, fluent-setter detection, property naming, not-bean 039 * exclusions, etc.) live on {@link BeanConfig @BeanConfig} in 040 * {@code juneau-commons}. Attributes that affect wire format, type discriminators, swap classes, 041 * locale/media-type/timezone, and debug mode stay here on {@code @MarshalledConfig}. 042 */ 043@Target({ TYPE, METHOD }) 044@Retention(RUNTIME) 045@Inherited 046@ContextApply(MarshalledConfigAnnotation.Applier.class) 047@SuppressWarnings({ 048 "java:S100" // Annotation methods use underscore suffix to avoid Java keyword conflicts 049}) 050public @interface MarshalledConfig { 051 052 /** 053 * Debug mode. 054 * 055 * <p> 056 * Enables the following additional information during serialization: 057 * <ul class='spaced-list'> 058 * <li> 059 * When bean getters throws exceptions, the exception includes the object stack information 060 * in order to determine how that method was invoked. 061 * <li> 062 * Enables {@link MarshallingTraverseContext.Builder#detectRecursions()}. 063 * </ul> 064 * 065 * <p> 066 * Enables the following additional information during parsing: 067 * <ul class='spaced-list'> 068 * <li> 069 * When bean setters throws exceptions, the exception includes the object stack information 070 * in order to determine how that method was invoked. 071 * </ul> 072 * 073 * <ul class='values'> 074 * <li><js>"true"</js> 075 * <li><js>"false"</js> (default) 076 * </ul> 077 * 078 * <h5 class='section'>Notes:</h5><ul> 079 * <li class='note'> 080 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 081 * </ul> 082 * 083 * <h5 class='section'>See Also:</h5><ul> 084 * <li class='jm'>{@link Context.Builder#debug()} 085 * </ul> 086 * 087 * @return The annotation value. 088 */ 089 String debug() default ""; 090 091 /** 092 * Bean dictionary. 093 * 094 * <p> 095 * The list of classes that make up the bean dictionary in this bean context. 096 * 097 * <p> 098 * A dictionary is a name/class mapping used to find class types during parsing when they cannot be inferred 099 * through reflection. 100 * <br>The names are defined through the {@link Marshalled#typeName() @Marshalled(typeName)} annotation defined on the bean class. 101 * <br>For example, if a class <c>Foo</c> has a type-name of <js>"myfoo"</js>, then it would end up serialized 102 * as <js>"{_type:'myfoo',...}"</js>. 103 * 104 * <p> 105 * This setting tells the parsers which classes to look for when resolving <js>"_type"</js> attributes. 106 * 107 * <h5 class='section'>See Also:</h5><ul> 108 * <li class='ja'>{@link Marshalled#dictionary()} 109 * <li class='ja'>{@link MarshalledProp#dictionary()} 110 * <li class='ja'>{@link MarshalledConfig#dictionary_replace()} 111 * <li class='jm'>{@link MarshallingContext.Builder#beanDictionary(Class...)} 112 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/BeanDictionaries">Bean Dictionary</a> 113 * </ul> 114 * 115 * @return The annotation value. 116 */ 117 Class<?>[] dictionary() default {}; 118 119 /** 120 * Replace bean dictionary. 121 * 122 * <p> 123 * Same as {@link #dictionary()} but replaces any existing value. 124 * 125 * <h5 class='section'>See Also:</h5><ul> 126 * <li class='ja'>{@link Marshalled#dictionary()} 127 * <li class='ja'>{@link MarshalledProp#dictionary()} 128 * <li class='ja'>{@link MarshalledConfig#dictionary()} 129 * <li class='jm'>{@link MarshallingContext.Builder#beanDictionary(Class...)} 130 * </ul> 131 * 132 * @return The annotation value. 133 */ 134 Class<?>[] dictionary_replace() default {}; 135 136 /** 137 * Locale. 138 * 139 * <p> 140 * Specifies the default locale for serializer and parser sessions. 141 * 142 * <h5 class='section'>Notes:</h5><ul> 143 * <li class='note'> 144 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 145 * </ul> 146 * 147 * <h5 class='section'>See Also:</h5><ul> 148 * <li class='jm'>{@link MarshallingSession.Builder#locale(Locale)} 149 * <li class='jm'>{@link MarshallingContext.Builder#locale(Locale)} 150 * </ul> 151 * 152 * @return The annotation value. 153 */ 154 String locale() default ""; 155 156 /** 157 * Media type. 158 * 159 * <p> 160 * Specifies the default media type value for serializer and parser sessions. 161 * 162 * <h5 class='section'>Notes:</h5><ul> 163 * <li class='note'> 164 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 165 * </ul> 166 * 167 * <h5 class='section'>See Also:</h5><ul> 168 * <li class='jm'>{@link MarshallingSession.Builder#mediaType(MediaType)} 169 * <li class='jm'>{@link MarshallingContext.Builder#mediaType(MediaType)} 170 * </ul> 171 * 172 * @return The annotation value. 173 */ 174 String mediaType() default ""; 175 176 /** 177 * Optional rank for this config. 178 * 179 * <p> 180 * Can be used to override default ordering and application of config annotations. 181 * 182 * @return The annotation value. 183 */ 184 int rank() default 0; 185 186 /** 187 * Java object swaps. 188 * 189 * <p> 190 * Swaps are used to "swap out" non-serializable classes with serializable equivalents during serialization, 191 * and "swap in" the non-serializable class during parsing. 192 * 193 * <p> 194 * An example of a swap would be a <c>Calendar</c> object that gets swapped out for an ISO8601 string. 195 * 196 * <p> 197 * Multiple swaps can be associated with a single class. 198 * <br>When multiple swaps are applicable to the same class, the media type pattern defined by 199 * {@link ObjectSwap#forMediaTypes()} or {@link Swap#mediaTypes() @Swap(mediaTypes)} are used to come up with the best match. 200 * 201 * <h5 class='section'>See Also:</h5><ul> 202 * <li class='jm'>{@link MarshallingContext.Builder#swaps(Class...)} 203 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Swaps">Swap</a> 204 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Swaps#per-media-type-swaps">Per-media-type swaps</a> 205 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/OneWaySwaps">One-way Swaps</a> 206 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SwapAnnotation">@Swap Annotation</a> 207 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/AutoSwaps">Auto-detected swaps</a> 208 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SurrogateClasses">Surrogate Classes</a> 209 * </ul> 210 * 211 * @return The annotation value. 212 */ 213 Class<?>[] swaps() default {}; 214 215 /** 216 * Replace Java object swap classes. 217 * 218 * <p> 219 * Same as {@link #swaps()} but replaces any existing value. 220 * 221 * <h5 class='section'>See Also:</h5><ul> 222 * <li class='jm'>{@link MarshallingContext.Builder#swaps(Class...)} 223 * </ul> 224 * 225 * @return The annotation value. 226 */ 227 Class<?>[] swaps_replace() default {}; 228 229 /** 230 * Calendar wire format. 231 * 232 * @return The annotation value. 233 */ 234 CalendarFormat calendarFormat() default CalendarFormat.NOT_SET; 235 236 /** 237 * Date wire format. 238 * 239 * @return The annotation value. 240 */ 241 DateFormat dateFormat() default DateFormat.NOT_SET; 242 243 /** 244 * Duration wire format. 245 * 246 * @return The annotation value. 247 */ 248 DurationFormat durationFormat() default DurationFormat.NOT_SET; 249 250 /** 251 * Locale wire format. 252 * 253 * @return The annotation value. 254 */ 255 LocaleFormat localeFormat() default LocaleFormat.NOT_SET; 256 257 /** 258 * Period wire format. 259 * 260 * @return The annotation value. 261 */ 262 PeriodFormat periodFormat() default PeriodFormat.NOT_SET; 263 264 /** 265 * Temporal wire format. 266 * 267 * @return The annotation value. 268 */ 269 TemporalFormat temporalFormat() default TemporalFormat.NOT_SET; 270 271 /** 272 * Time-zone wire format. 273 * 274 * @return The annotation value. 275 */ 276 TimeZoneFormat timeZoneFormat() default TimeZoneFormat.NOT_SET; 277 278 /** 279 * Binary wire format for <code><jk>byte</jk>[]</code> values. 280 * 281 * @return The annotation value. 282 */ 283 BinaryFormat binaryFormat() default BinaryFormat.NOT_SET; 284 285 /** 286 * Enum wire format. 287 * 288 * @return The annotation value. 289 */ 290 EnumFormat enumFormat() default EnumFormat.NOT_SET; 291 292 /** 293 * UUID wire format. 294 * 295 * @return The annotation value. 296 */ 297 UuidFormat uuidFormat() default UuidFormat.NOT_SET; 298 299 /** 300 * BitSet wire format. 301 * 302 * @return The annotation value. 303 */ 304 BitSetFormat bitSetFormat() default BitSetFormat.NOT_SET; 305 306 /** 307 * Big-number wire format for {@link BigInteger} / {@link BigDecimal} values. 308 * 309 * @return The annotation value. 310 */ 311 BigNumberFormat bigNumberFormat() default BigNumberFormat.NOT_SET; 312 313 /** 314 * Boolean wire format for {@link Boolean} / <code><jk>boolean</jk></code> values. 315 * 316 * @return The annotation value. 317 */ 318 BooleanFormat booleanFormat() default BooleanFormat.NOT_SET; 319 320 /** 321 * Float / Double non-finite wire format for {@link Float} / {@link Double} values. 322 * 323 * @return The annotation value. 324 */ 325 FloatFormat floatFormat() default FloatFormat.NOT_SET; 326 327 /** 328 * Currency wire format for {@link Currency} values. 329 * 330 * @return The annotation value. 331 */ 332 CurrencyFormat currencyFormat() default CurrencyFormat.NOT_SET; 333 334 /** 335 * Class wire format for {@link Class} values. 336 * 337 * @return The annotation value. 338 */ 339 ClassFormat classFormat() default ClassFormat.NOT_SET; 340 341 /** 342 * Time zone. 343 * 344 * <p> 345 * Specifies the default timezone for serializer and parser sessions. 346 * 347 * <h5 class='section'>Notes:</h5><ul> 348 * <li class='note'> 349 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 350 * </ul> 351 * 352 * <h5 class='section'>See Also:</h5><ul> 353 * <li class='jm'>{@link MarshallingSession.Builder#timeZone(TimeZone)} 354 * <li class='jm'>{@link MarshallingContext.Builder#timeZone(TimeZone)} 355 * </ul> 356 * 357 * @return The annotation value. 358 */ 359 String timeZone() default ""; 360 361 /** 362 * Bean type property name. 363 * 364 * <p> 365 * This specifies the name of the bean property used to store the dictionary name of a bean type so that the 366 * parser knows the data type to reconstruct. 367 * 368 * <h5 class='section'>Notes:</h5><ul> 369 * <li class='note'> 370 * Default value: <js>"_type"</js>. 371 * <li class='note'> 372 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 373 * </ul> 374 * 375 * <h5 class='section'>See Also:</h5><ul> 376 * <li class='ja'>{@link Marshalled#typePropertyName()} 377 * <li class='jm'>{@link MarshallingContext.Builder#typePropertyName(String)} 378 * </ul> 379 * 380 * @return The annotation value. 381 */ 382 String typePropertyName() default ""; 383}