org.apache.juneau.annotation.Beanp Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
// * with the License. You may obtain a copy of the License at *
// * *
// * http://www.apache.org/licenses/LICENSE-2.0 *
// * *
// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
// * specific language governing permissions and limitations under the License. *
// ***************************************************************************************************************************
package org.apache.juneau.annotation;
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
import java.util.*;
import org.apache.juneau.*;
/**
* Used tailor how bean properties get interpreted by the framework.
*
*
* Can be used in the following locations:
*
* - Methods/Fields - Bean getters/setters and properties.
*
@Rest -annotated classes and @RestOp -annotated methods when an {@link #on()} value is specified.
*
*
* This annotation is applied to public fields and public getter/setter methods of beans.
*
*
See Also:
*/
@Documented
@Target({FIELD,METHOD,PARAMETER,TYPE})
@Retention(RUNTIME)
@Inherited
@Repeatable(BeanpAnnotation.Array.class)
@ContextApply(BeanpAnnotation.Applier.class)
public @interface Beanp {
/**
* Bean dictionary.
*
*
* The list of classes that make up the bean dictionary this bean property.
*
*
See Also:
* - {@link org.apache.juneau.annotation.Bean#dictionary()}
*
- {@link org.apache.juneau.annotation.BeanConfig#dictionary()}
*
- {@link org.apache.juneau.annotation.BeanConfig#dictionary_replace()}
*
- {@link org.apache.juneau.BeanContext.Builder#beanDictionary(Class...)}
*
*
*
* This annotation can also be used on private fields of a property.
*
* @return The annotation value.
*/
Class[] dictionary() default {};
/**
* Specifies a String format for converting the bean property value to a formatted string.
*
*
* Note that this is usually a one-way conversion during serialization.
*
*
* During parsing, we will attempt to convert the value to the original form by using the
* {@link BeanSession#convertToType(Object, Class)} but there is no guarantee that this will succeed.
*
*
Example:
*
* @Beanp (format="$%.2f" )
* public float price ;
*
*
*
* This annotation can also be used on private fields of a property like so:
*
*
Example:
*
* public class MyBean {
*
* @Beanp (format="$%.2f" )
* private float price ;
*
* public float getPrice() {
* return price ;
* }
* }
*
*
* @return The annotation value.
*/
String format() default "";
/**
* Identifies the name of the property.
*
*
* Normally, this is automatically inferred from the field name or getter method name of the property.
* However, this property can be used to assign a different property name from the automatically inferred value.
*
*
* If the {@link org.apache.juneau.BeanContext.Builder#beanFieldVisibility(Visibility)} setting on the bean context excludes this field (e.g. the
* visibility is set to PUBLIC, but the field is PROTECTED), this annotation can be used to force the field to be
* identified as a property.
*
*
Dynamic beans
*
* The bean property named "*" is the designated "dynamic property" which allows for "extra" bean
* properties not otherwise defined.
* This is similar in concept to the Jackson @JsonGetterAll and @JsonSetterAll annotations.
* The primary purpose is for backwards compatibility in parsing newer streams with addition information into older
* beans.
*
*
* The following examples show how to define dynamic bean properties.
*
* // Option #1 - A simple public Map field.
* // The field name can be anything.
* public class BeanWithDynaField {
*
* @Beanp (name="*" )
* public Map<String,Object> extraStuff = new LinkedHashMap<>();
* }
*
* // Option #2 - Getters and setters.
* // Method names can be anything.
* // Getter must return a Map with String keys.
* // Setter must take in two arguments.
* public class BeanWithDynaMethods {
*
* @Beanp (name="*" )
* public Map<String,Object> getMyExtraStuff() {
* ...
* }
*
* @Beanp (name="*" )
* public void setAnExtraField(String name , Object value ) {
* ...
* }
* }
*
* // Option #3 - Getter only.
* // Properties will be added through the getter.
* public class BeanWithDynaGetterOnly {
*
* @Beanp (name="*" )
* public Map<String,Object> getMyExtraStuff() {
* ...
* }
* }
*
* // Option #4 - Getter, setter, and extra-keys method .
* // Define a method that returns a Collection<String> with currently-set property names.
* public class BeanWithDynaExtraKeys {
*
* @Beanp (name="*" )
* public Object get(String name ) {
* ...
* }
*
* @Beanp (name="*" )
* public void set(String name , Object value ) {
* ...
* }
*
* @Beanp (name="*" )
* public Collection<String> extraKeys() {
* ...
* }
* }
*
*
*
* Similar rules apply for value types and swaps.
* The property values optionally can be any serializable type or use swaps.
*
* // A serializable type other than Object.
* public class BeanWithDynaFieldWithListValues {
*
* @Beanp (name="*" )
* public Map<String,List<String>> getMyExtraStuff() {
* ...
* }
* }
*
* // A swapped value.
* public class BeanWithDynaFieldWithSwappedValues {
*
* @Beanp (name="*" , swap=TemporalCalendarSwap.IsoLocalDateTime.class )
* public Map<String,Calendar> getMyExtraStuff() {
* ...
* }
* }
*
*
*
* Note that if you're not interested in these additional properties, you can also use the
* {@link org.apache.juneau.BeanContext.Builder#ignoreUnknownBeanProperties()} setting to ignore values that don't fit into existing
* properties.
*
*
* Note that the {@link Name @Name} annotation can also be used for identifying a property name.
*
*
* @return The annotation value.
*/
String name() default "";
/**
* Dynamically apply this annotation to the specified fields/methods.
*
*
* Used in conjunction with {@link org.apache.juneau.BeanContext.Builder#applyAnnotations(Class...)} to dynamically apply an annotation to an existing field/method.
* It is ignored when the annotation is applied directly to fields/methods.
*
*
Valid patterns:
*
* - Methods:
*
* - Fully qualified with args:
*
* "com.foo.MyClass.myMethod(String,int)"
* "com.foo.MyClass.myMethod(java.lang.String,int)"
* "com.foo.MyClass.myMethod()"
*
* - Fully qualified:
*
* "com.foo.MyClass.myMethod"
*
* - Simple with args:
*
* "MyClass.myMethod(String,int)"
* "MyClass.myMethod(java.lang.String,int)"
* "MyClass.myMethod()"
*
* - Simple:
*
* "MyClass.myMethod"
*
* - Simple inner class:
*
* "MyClass$Inner1$Inner2.myMethod"
* "Inner1$Inner2.myMethod"
* "Inner2.myMethod"
*
*
* - Fields:
*
* - Fully qualified:
*
* "com.foo.MyClass.myField"
*
* - Simple:
*
* "MyClass.myField"
*
* - Simple inner class:
*
* "MyClass$Inner1$Inner2.myField"
* "Inner1$Inner2.myField"
* "Inner2.myField"
*
*
* - A comma-delimited list of anything on this list.
*
*
* See Also:
*
* @return The annotation value.
*/
String[] on() default {};
/**
* For bean properties of maps and collections, this annotation can be used to identify the class types of the
* contents of the bean property object when the generic parameter types are interfaces or abstract classes.
*
* Example:
*
* public class MyBean {
*
* // Identify concrete map type with String keys and Integer values.
* @Beanp (type=HashMap.class , params={String.class ,Integer.class })
* public Map p1 ;
* }
*
*
*
* This annotation can also be used on private fields of a property like so:
*
*
Example:
*
* public class MyBean {
*
* @Beanp (type=HashMap.class , params={String.class ,Integer.class })
* private Map p1 ;
*
* public Map getP1() {
* return p1 ;
* }
* }
*
*
* @return The annotation value.
*/
Class[] params() default {};
/**
* Used to limit which child properties are rendered by the serializers.
*
*
* Can be used on any of the following bean property types:
*
* - Beans - Only render the specified properties of the bean.
*
- Maps - Only render the specified entries in the map.
*
- Bean/Map arrays - Same, but applied to each element in the array.
*
- Bean/Map collections - Same, but applied to each element in the collection.
*
*
* Example:
*
* public class MyClass {
*
* // Only render 'f1' when serializing this bean property.
* @Beanp (properties="f1" )
* public MyChildClass x1 = new MyChildClass();
* }
*
* public class MyChildClass {
* public int f1 = 1;
* public int f2 = 2;
* }
*
* // Renders "{x1:{f1:1}}"
* String json = JsonSerializer.DEFAULT .serialize(new MyClass());
*
*
*
* This annotation can also be used on private fields of a property like so:
*
*
Example:
*
* public class MyBean {
*
* @Beanp (properties="f1" )
* private MyChildClass x1 ;
*
* public MyChildClass getX1() {
* return x1 ;
* }
* }
*
*
* @return The annotation value.
*/
String properties() default "";
/**
* Identifies a property as read-only.
*
*
* Serializers will serialize such properties as usual, but parsers will silently ignore them.
*
*
Example:
*
* public class MyBean {
* @Beanp (ro="true" )
* public float price ;
* }
*
*
* See Also:
* - {@link org.apache.juneau.BeanContext.Builder#beanPropertiesReadOnly(Class, String)}
*
- {@link org.apache.juneau.BeanContext.Builder#beanPropertiesReadOnly(String, String)}
*
- {@link org.apache.juneau.BeanContext.Builder#beanPropertiesReadOnly(Map)}
*
*
* @return The annotation value.
*/
String ro() default "";
/**
* Identifies a specialized class type for the property.
*
*
* Normally this can be inferred through reflection of the field type or getter return type.
* However, you'll want to specify this value if you're parsing beans where the bean property class is an interface
* or abstract class to identify the bean type to instantiate.
* Otherwise, you may cause an {@link InstantiationException} when trying to set these fields.
*
*
* This property must denote a concrete bean class with a no-arg constructor.
*
*
Example:
*
* public class MyBean {
*
* // Identify concrete map type.
* @Beanp (type=HashMap.class )
* public Map p1 ;
* }
*
*
*
* This annotation can also be used on private fields of a property like so:
*
*
Example:
*
* public class MyBean {
*
* @Beanp (type=HashMap.class )
* private Map p1 ;
*
* public Map getP1() {
* return p1 ;
* }
* }
*
*
* @return The annotation value.
*/
Class type() default void.class;
/**
* A synonym for {@link #name()}.
*
*
* The following annotations are equivalent:
*
*
* @Beanp (name="foo" )
*
* @Beanp ("foo" )
*
*
* @return The annotation value.
*/
String value() default "";
/**
* Identifies a property as write-only.
*
*
* Parsers will parse such properties as usual, but serializers will silently ignore them.
*
*
Example:
*
* public class MyBean {
* @Beanp (wo="true" )
* public float price ;
* }
*
*
* See Also:
* - {@link org.apache.juneau.BeanContext.Builder#beanPropertiesWriteOnly(Class, String)}
*
- {@link org.apache.juneau.BeanContext.Builder#beanPropertiesWriteOnly(String, String)}
*
- {@link org.apache.juneau.BeanContext.Builder#beanPropertiesWriteOnly(Map)}
*
*
* @return The annotation value.
*/
String wo() default "";
}