Package org.apache.juneau.annotation

Annotation Type Beanp

@Documented @Target({FIELD,METHOD,PARAMETER,TYPE}) @Retention(RUNTIME) @Inherited @Repeatable(Array.class) @ContextApply(Applier.class) public @interface Beanp
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 on() value is specified.

This annotation is applied to public fields and public getter/setter methods of beans.

See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Class<?>[]
    dictionary
    Bean dictionary.
    String
    format
    Specifies a String format for converting the bean property value to a formatted string.
    String
    name
    Identifies the name of the property.
    String[]
    on
    Dynamically apply this annotation to the specified fields/methods.
    Class<?>[]
    params
    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.
    String
    properties
    Used to limit which child properties are rendered by the serializers.
    String
    ro
    Identifies a property as read-only.
    Class<?>
    type
    Identifies a specialized class type for the property.
    String
    value
    A synonym for name().
    String
    wo
    Identifies a property as write-only.

  • Element Details

    • dictionary

      Class<?>[] dictionary
      Bean dictionary.

      The list of classes that make up the bean dictionary this bean property.

      See Also:

      This annotation can also be used on private fields of a property.

      Returns:
      The annotation value.
      Default:
      {}

    • format

      String format
      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 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; } }

      Returns:
      The annotation value.
      Default:
      ""

    • name

      String name
      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 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 BeanContext.Builder.ignoreUnknownBeanProperties() setting to ignore values that don't fit into existing properties.
      Note that the @Name annotation can also be used for identifying a property name.
      Returns:
      The annotation value.
      Default:
      ""

    • on

      String[] on
      Dynamically apply this annotation to the specified fields/methods.

      Used in conjunction with 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:
      Returns:
      The annotation value.
      Default:
      {}

    • params

      Class<?>[] params
      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; } }

      Returns:
      The annotation value.
      Default:
      {}

    • properties

      String properties
      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; } }

      Returns:
      The annotation value.
      Default:
      ""

    • ro

      String ro
      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:
      Returns:
      The annotation value.
      Default:
      ""

    • type

      Class<?> type
      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 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; } }

      Returns:
      The annotation value.
      Default:
      void.class

    • value

      String value
      A synonym for name().

      The following annotations are equivalent:

      @Beanp(name="foo") @Beanp("foo")

      Returns:
      The annotation value.
      Default:
      ""

    • wo

      String wo
      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:
      Returns:
      The annotation value.
      Default:
      ""