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.*; 027 028/** 029 * Used to tailor how bean properties get marshalled by the framework. 030 * 031 * <p> 032 * The marshalling-only sibling of {@link BeanProp @BeanProp}. 033 * Where {@code @BeanProp} (in <c>juneau-commons</c>) carries the bean-modeling attributes 034 * (such as {@code name}, {@code ro}, {@code wo}, {@code type}, {@code params}, {@code elementType}, 035 * and {@code factory}), this annotation carries the wire-format-specific attributes used by serializers 036 * and parsers: a per-property format string and a bean dictionary for polymorphic types. 037 * 038 * <p> 039 * Can be used in the following locations: 040 * <ul> 041 * <li>Methods/Fields - Bean getters/setters and properties. 042 * <li><ja>@Rest</ja>-annotated classes and <ja>@RestOp</ja>-annotated methods when used with {@link MarshalledPropApply @MarshalledPropApply}. 043 * </ul> 044 * 045 * <p> 046 * This annotation does <b>not</b> support renaming a property, nor the read-only/write-only, concrete-type, 047 * generic-params, element-type, or bean-factory attributes — those are bean-modeling concerns that live on 048 * {@link BeanProp @BeanProp} instead. To rename a property, use {@link BeanProp @BeanProp} 049 * (e.g. <c>@BeanProp("newName")</c>), not this annotation. 050 * 051 * <h5 class='section'>See Also:</h5><ul> 052 * <li class='ja'>{@link BeanProp} 053 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/BeanPropAnnotation">@BeanProp Annotation</a> 054 * </ul> 055 */ 056@Documented 057@Target({ FIELD, METHOD, PARAMETER }) 058@Retention(RUNTIME) 059@Inherited 060public @interface MarshalledProp { 061 062 /** 063 * Optional description for the exposed API. 064 * 065 * @return The annotation value. 066 * @since 9.2.0 067 */ 068 String[] description() default {}; 069 070 /** 071 * Declares the named views this property belongs to. 072 * 073 * <p> 074 * When an active view is selected (via 075 * {@link MarshallingContext.Builder#activeView(String)} or the per-call session 076 * override), this property is included only when its declared view set contains the active view name. 077 * 078 * <p> 079 * If this member is empty (the default), the property follows the default-view-inclusion policy: 080 * by default an untagged property is included under every active view (matching Jackson's 081 * {@code DEFAULT_VIEW_INCLUSION} behavior). The policy can be flipped via 082 * {@link MarshallingContext.Builder#disableDefaultViewInclusion()}. 083 * 084 * <p> 085 * Multiple view names are supported — a property tagged {@code view={"summary","detail"}} is included 086 * when <em>either</em> {@code "summary"} or {@code "detail"} is the active view (union semantics). 087 * 088 * <h5 class='section'>Example:</h5> 089 * <p class='bjava'> 090 * <jk>public class</jk> MyBean { 091 * 092 * <jc>// Included in all views (untagged = default inclusion)</jc> 093 * <jk>public</jk> String <jf>id</jf>; 094 * 095 * <jc>// Included only in the "summary" and "detail" views</jc> 096 * <ja>@MarshalledProp</ja>(view={<js>"summary"</js>, <js>"detail"</js>}) 097 * <jk>public</jk> String <jf>name</jf>; 098 * 099 * <jc>// Included only in the "detail" view</jc> 100 * <ja>@MarshalledProp</ja>(view=<js>"detail"</js>) 101 * <jk>public</jk> String <jf>description</jf>; 102 * } 103 * </p> 104 * 105 * <h5 class='section'>See Also:</h5><ul> 106 * <li class='jm'>{@link MarshallingContext.Builder#activeView(String)} 107 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/ViewProjection">View-Based Projection</a> 108 * </ul> 109 * 110 * @return The annotation value. 111 * @since 10.0.0 112 */ 113 String[] view() default {}; 114 115 /** 116 * Bean dictionary. 117 * 118 * <p> 119 * The list of classes that make up the bean dictionary for this bean property, used during 120 * polymorphic marshalling. 121 * 122 * <h5 class='section'>See Also:</h5><ul> 123 * <li class='ja'>{@link Marshalled#dictionary()} 124 * <li class='ja'>{@link MarshalledConfig#dictionary()} 125 * <li class='ja'>{@link MarshalledConfig#dictionary_replace()} 126 * <li class='jm'>{@link MarshallingContext.Builder#beanDictionary(Class...)} 127 * </ul> 128 * 129 * <p> 130 * This annotation can also be used on private fields of a property. 131 * 132 * @return The annotation value. 133 */ 134 Class<?>[] dictionary() default {}; 135 136 /** 137 * Calendar wire format override. 138 * 139 * @return The annotation value. 140 */ 141 CalendarFormat calendarFormat() default CalendarFormat.NOT_SET; 142 143 /** 144 * Date wire format override. 145 * 146 * @return The annotation value. 147 */ 148 DateFormat dateFormat() default DateFormat.NOT_SET; 149 150 /** 151 * Duration wire format override. 152 * 153 * @return The annotation value. 154 */ 155 DurationFormat durationFormat() default DurationFormat.NOT_SET; 156 157 /** 158 * Specifies a String format for converting the bean property value to a formatted string. 159 * 160 * <p> 161 * Note that this is usually a one-way conversion during serialization. 162 * 163 * <p> 164 * During parsing, we will attempt to convert the value to the original form by using the 165 * {@link MarshallingSession#convertToType(Object, Class)} but there is no guarantee that this will succeed. 166 * 167 * <h5 class='section'>Example:</h5> 168 * <p class='bjava'> 169 * <ja>@MarshalledProp</ja>(format=<js>"$%.2f"</js>) 170 * <jk>public float</jk> <jf>price</jf>; 171 * </p> 172 * 173 * <p> 174 * This annotation can also be used on private fields of a property like so: 175 * 176 * <h5 class='section'>Example:</h5> 177 * <p class='bjava'> 178 * <jk>public class</jk> MyBean { 179 * 180 * <ja>@MarshalledProp</ja>(format=<js>"$%.2f"</js>) 181 * <jk>private float</jk> <jf>price</jf>; 182 * 183 * <jk>public float</jk> getPrice() { 184 * <jk>return</jk> <jf>price</jf>; 185 * } 186 * } 187 * </p> 188 * 189 * @return The annotation value. 190 */ 191 String format() default ""; 192 193 /** 194 * Locale wire format override. 195 * 196 * @return The annotation value. 197 */ 198 LocaleFormat localeFormat() default LocaleFormat.NOT_SET; 199 200 /** 201 * Period wire format override. 202 * 203 * @return The annotation value. 204 */ 205 PeriodFormat periodFormat() default PeriodFormat.NOT_SET; 206 207 /** 208 * Temporal wire format override. 209 * 210 * @return The annotation value. 211 */ 212 TemporalFormat temporalFormat() default TemporalFormat.NOT_SET; 213 214 /** 215 * Time-zone wire format override. 216 * 217 * @return The annotation value. 218 */ 219 TimeZoneFormat timeZoneFormat() default TimeZoneFormat.NOT_SET; 220 221 /** 222 * Binary wire format override for <code><jk>byte</jk>[]</code> property values. 223 * 224 * @return The annotation value. 225 */ 226 BinaryFormat binaryFormat() default BinaryFormat.NOT_SET; 227 228 /** 229 * Enum wire format override for {@link Enum} property values. 230 * 231 * @return The annotation value. 232 */ 233 EnumFormat enumFormat() default EnumFormat.NOT_SET; 234 235 /** 236 * UUID wire format override for {@link UUID} property values. 237 * 238 * @return The annotation value. 239 */ 240 UuidFormat uuidFormat() default UuidFormat.NOT_SET; 241 242 /** 243 * BitSet wire format override for {@link BitSet} property values. 244 * 245 * @return The annotation value. 246 */ 247 BitSetFormat bitSetFormat() default BitSetFormat.NOT_SET; 248 249 /** 250 * Big-number wire format override for {@link BigInteger} / {@link BigDecimal} property values. 251 * 252 * @return The annotation value. 253 */ 254 BigNumberFormat bigNumberFormat() default BigNumberFormat.NOT_SET; 255 256 /** 257 * Boolean wire format override for {@link Boolean} / <code><jk>boolean</jk></code> property values. 258 * 259 * @return The annotation value. 260 */ 261 BooleanFormat booleanFormat() default BooleanFormat.NOT_SET; 262 263 /** 264 * Float / Double non-finite wire format override for {@link Float} / {@link Double} property values. 265 * 266 * @return The annotation value. 267 */ 268 FloatFormat floatFormat() default FloatFormat.NOT_SET; 269 270 /** 271 * Currency wire format override for {@link Currency} property values. 272 * 273 * @return The annotation value. 274 */ 275 CurrencyFormat currencyFormat() default CurrencyFormat.NOT_SET; 276 277 /** 278 * Class wire format override for {@link Class} property values. 279 * 280 * @return The annotation value. 281 */ 282 ClassFormat classFormat() default ClassFormat.NOT_SET; 283 284 /** 285 * Per-property null-coercion policy applied when a {@code null} JSON-equivalent value reaches this property during 286 * parsing. 287 * 288 * <p> 289 * Juneau's analog of Jackson's {@code @JsonSetter(nulls=…)}. When the parser encounters an explicit {@code null} 290 * (or an absent {@link Optional}) for this property, the configured policy decides whether to: 291 * <ul> 292 * <li>{@link Nulls#LEAVE LEAVE} (default) — set the property to {@code null} (or, for an {@link Optional}-typed 293 * property, to {@link Optional#empty()}). 294 * <li>{@link Nulls#EMPTY EMPTY} — substitute the type's "empty" value (empty {@link String}/{@link Collection}/ 295 * {@link Map}, primitive default for primitives, {@code Optional.empty()} for {@link Optional}). 296 * <li>{@link Nulls#DEFAULT DEFAULT} — substitute the bean-constructed default for the property (i.e. the value the 297 * property holds on a fresh no-arg-constructed instance of the bean). When no reference instance can be built, 298 * falls back to {@link Nulls#LEAVE LEAVE}. 299 * <li>{@link Nulls#SKIP SKIP} — do not call the setter at all, leaving any pre-existing value in place. 300 * </ul> 301 * 302 * <p> 303 * For an {@link Optional}-typed property, {@code EMPTY}/{@code DEFAULT} resolve to {@link Optional#empty()} — 304 * never a bare {@code null} inside an {@link Optional}. The same contract applies to {@link OptionalInt}, 305 * {@link OptionalLong}, and {@link OptionalDouble}. 306 * 307 * <p> 308 * When this member is {@link Nulls#NOT_SET NOT_SET} (the default), the context-level default configured on 309 * {@link org.apache.juneau.marshall.parser.Parser.Builder#nulls(Nulls)} applies. 310 * 311 * @return The annotation value. 312 * @since 10.0.0 313 */ 314 Nulls nulls() default Nulls.NOT_SET; 315}