Package org.apache.juneau.commons.bean

Class BeanPropertyMeta

java.lang.Object
org.apache.juneau.commons.bean.BeanPropertyMeta
All Implemented Interfaces:
Comparable<BeanPropertyMeta>
public class BeanPropertyMeta extends Object implements Comparable<BeanPropertyMeta>
Contains metadata about a bean property.

Contains information such as type of property (e.g. field/getter/setter), class type of property value, and whether any transforms are associated with this property.

Developers will typically not need access to this class. The information provided by it is already exposed through several methods on the BeanMap API.

Thread safety
Instances are immutable after construction and are safe for concurrent read access.

  • Field Details

    • SKIP_VALUE

      public static final Object SKIP_VALUE
      Sentinel value that, when returned from BeanPropertyMeta.Builder.writeTransform during set(BeanMap, String, Object), causes the set to be skipped entirely — neither the configured setter is invoked nor the property cache updated.

      Provided as a generic SPI hook so the marshalling layer (or any other transform-installing extension) can implement "leave the bean's pre-existing value in place" semantics — used by the per-property null-coercion SKIP mode added to the marshalling layer in 10.0.0.

      Since:
      10.0.0

  • Constructor Details

    • BeanPropertyMeta

      protected BeanPropertyMeta(BeanPropertyMeta.Builder b)
      Creates a new BeanPropertyMeta using the contents of the specified builder.
      Parameters:
      b - The builder to copy fields from. Must not be null.

  • Method Details

    • builder

      public static BeanPropertyMeta.Builder builder(BeanMeta<?> beanMeta, String name)
      Creates a builder for BeanPropertyMeta(org.apache.juneau.commons.bean.BeanPropertyMeta.Builder) objects.
      Parameters:
      beanMeta - The metadata on the bean. Must not be null.
      name - The bean property name.
      Returns:
      A new builder.

    • add

      public void add(BeanMap<?> m, String pName, Object value) throws BeanRuntimeException
      Adds a value to a Collection or array property.

      Note that adding values to an array property is inefficient for large arrays since it must copy the array into a larger array on each operation.

      Marshalling-only path. Requires a property built via the marshalling-side construction path (i.e. with a non-null rawTypeMeta and a non-null backing MarshallingSession on the supplied BeanMap). When the owning BeanMeta was built via BeanMeta.of(Class, BeanConfigContext), this method throws UnsupportedOperationException because adding into a Collection/array property requires type-aware element conversion (the marshalling session's convertToType) that is not available in the bean-modeling-only path.

      Parameters:
      m - The bean of the field being set.
      pName - The property name if this is a dyna property (i.e. "*").
      Otherwise can be null.
      value - The value to add to the field. Can be null.
      Throws:
      BeanRuntimeException - If field is not a collection or array.
      UnsupportedOperationException - If this property was built via the bean-modeling-only path (BeanMeta.of(Class, BeanConfigContext)).

    • add

      public void add(BeanMap<?> m, String pName, String key, Object value) throws BeanRuntimeException
      Adds a value to a Map or bean property.

      Marshalling-only path. Requires a property built via the marshalling-side construction path (i.e. with a non-null rawTypeMeta and a non-null backing MarshallingSession on the supplied BeanMap). When the owning BeanMeta was built via BeanMeta.of(Class, BeanConfigContext), this method throws UnsupportedOperationException because adding into a Map/bean property requires type-aware value conversion (the marshalling session's convertToType / toBeanMap) that is not available in the bean-modeling-only path.

      Parameters:
      m - The bean of the field being set.
      pName - The property name if this is a dyna property (i.e. "*").
      Otherwise can be null.
      key - The key to add to the field.
      value - The value to add to the field. Can be null.
      Throws:
      BeanRuntimeException - If field is not a map or array.
      UnsupportedOperationException - If this property was built via the bean-modeling-only path (BeanMeta.of(Class, BeanConfigContext)).

    • canRead

      public boolean canRead()
      Returns true if this property can be read.

      Write-only properties (see isWriteOnly()) are never readable, so serializers, tabular column sets and schemas skip them. They remain settable through canWrite() and parsing.

      Returns:
      true if this property can be read.

    • canWrite

      public boolean canWrite()
      Returns true if this property can be written.
      Returns:
      true if this property can be written.

    • compareTo

      public int compareTo(BeanPropertyMeta o)
      Specified by:
      compareTo in interface Comparable<BeanPropertyMeta>

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • getAnnotations

      public List<AnnotationInfo> getAnnotations()
      Returns all annotations on this property (field, getter, and setter).

      The annotations are found on:

      • The field (if present)
      • The getter method (if present) - including annotations on the method, its return type, and package
      • The setter method (if present) - including annotations on the method, its return type, and package

      The result is memoized and computed only once.

      Returns:
      A list of all annotation infos on this property. Never null.

    • getAnnotations

      public <A extends Annotation> Stream<AnnotationInfo<A>> getAnnotations(Class<A> a)
      Returns a stream of annotations of the specified type on this property.

      The annotations are found on:

      • The field (if present)
      • The getter method (if present) - including annotations on the method, its return type, and package
      • The setter method (if present) - including annotations on the method, its return type, and package
      Type Parameters:
      A - The annotation type to find.
      Parameters:
      a - The annotation class to find. Can be null, in which case an empty stream is returned.
      Returns:
      A stream of annotation infos of the specified type. Never null.

    • get

      public Object get(BeanMap<?> m, String pName)
      Equivalent to calling BeanMap.get(Object), but is faster since it avoids looking up the property meta.
      Parameters:
      m - The bean map to get the transformed value from.
      pName - The property name if this is a dyna property (i.e. "*").
      Otherwise can be null.
      Returns:
      The property value.
      Returns null if this is a write-only property.

    • getBeanMeta

      public BeanMeta<?> getBeanMeta()
      Returns the bean meta that this property belongs to.
      Returns:
      The bean meta that this property belongs to.

    • getBeanRegistry

      public BeanRegistryLookup getBeanRegistry()
      Returns the bean dictionary in use for this bean property.

      The order of lookup for the dictionary is as follows:

      1. Dictionary defined via @MarshalledProp(dictionary).
      2. Dictionary defined via MarshallingContext.Builder<?>#beanDictionary(Class...).

      The per-property registry no longer lives on this object; it is stored in a marshalling-side side-map on BeanMeta keyed by BeanPropertyMeta. This method delegates to BeanMeta.getPropertyBeanRegistry(BeanPropertyMeta) for backwards compatibility with existing call sites in the marshalling layer (parser/serializer sessions, XML content-property handling, etc.).

      Returns the bean-modeling-side SPI type (BeanRegistryLookup). Marshalling-side callers that need implementation-specific behavior cast at the call site.

      Returns:
      The bean dictionary in use for this bean property, or null if no registry was registered.

    • getBeanInfo

      public BeanInfo<?> getBeanInfo()
      Returns the BeanInfo of the class of this property.

      If this property or the property type class has a ObjectSwap associated with it, this method returns the transformed class meta. This matches the class type that is used by the get(BeanMap,String) and set(BeanMap,String,Object) methods.

      Returns the bean-modeling-side SPI type (BeanInfo). Marshalling-side callers that need the ClassMeta narrowing must cast — the concrete instance in-tree is always a ClassMeta.

      Returns:
      The BeanInfo of the class of this property, or null if this property was built via the bean-modeling-only path.

    • getDelegateFor

      public BeanPropertyMeta getDelegateFor()
      Returns the metadata on the property that this metadata is a delegate for.
      Returns:
      the metadata on the property that this metadata is a delegate for, or this object if it's not a delegate.

    • getDynaMap

      public Map<String,Object> getDynaMap(Object bean) throws IllegalArgumentException, IllegalAccessException, InvocationTargetException
      Returns the Map object returned by the DynaBean getter.

      The DynaBean property is the property whose name is "*" and returns a map of "extra" properties on the bean.

      Parameters:
      bean - The bean.
      Returns:
      The map returned by the getter, or an empty map if the getter returned null or this isn't a DynaBean property.
      Throws:
      IllegalArgumentException - Thrown by method invocation.
      IllegalAccessException - Thrown by method invocation.
      InvocationTargetException - Thrown by method invocation.

    • getField

      public FieldInfo getField()
      Returns the field for this property.
      Returns:
      The field info for this bean property, or null if there is no field associated with this bean property.

    • getGetter

      public MethodInfo getGetter()
      Returns the getter method for this property.
      Returns:
      The getter method info for this bean property, or null if there is no getter method.

    • getInnerField

      public FieldInfo getInnerField()
      Returns the field for this property even if the field is private.
      Returns:
      The field info for this bean property, or null if there is no field associated with this bean property.

    • getName

      public String getName()
      Returns the name of this bean property.
      Returns:
      The name of the bean property.

    • getRaw

      public Object getRaw(BeanMap<?> m, String pName)
      Equivalent to calling BeanMap.getRaw(Object), but is faster since it avoids looking up the property meta.
      Parameters:
      m - The bean map to get the transformed value from.
      pName - The property name if this is a dyna property (i.e. "*").
      Otherwise can be null.
      Returns:
      The raw property value.

    • getSetter

      public MethodInfo getSetter()
      Returns the setter method for this property.
      Returns:
      The setter method info for this bean property, or null if there is no setter method.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • isDyna

      public boolean isDyna()
      Returns true if this bean property is named "*".
      Returns:
      true if this bean property is named "*".

    • isRequired

      public boolean isRequired()
      Returns whether this property is marked @BeanProp(required=true).

      Required properties must be present in parser input (or in the source map of a Map-to-bean conversion); see BeanProp.required().

      Returns:
      true if this property is required.

    • isReadOnly

      public boolean isReadOnly()
      Returns true if this property is read-only.

      This implies the property MIGHT be writable, but that parsers should not set a value for it.

      Returns:
      true if this property is read-only.

    • isUri

      public boolean isUri()
      Returns true if this bean property is a URI.

      A bean property can be considered a URI if any of the following are true:

      • Property class type is URL or URI.
      • Property class type is annotated with @Uri.
      • Property getter, setter, or field is annotated with @Uri.
      Returns:
      true if this bean property is a URI.

    • getViews

      public Set<String> getViews()
      Returns the set of named views this property belongs to, or null if the property is untagged.

      An untagged property (one with no @MarshalledProp(view=...) annotation) follows the default-view-inclusion policy: it is included under every active view when the policy is enabled (the default behavior), or excluded from all views when the policy is disabled.

      A tagged property is included only when the active view name is contained in this set.

      Returns:
      The set of named views, or null if no view membership was declared.

    • set

      public Object set(BeanMap<?> m, String pName, Object value) throws BeanRuntimeException
      Equivalent to calling BeanMap.put(String, Object), but is faster since it avoids looking up the property meta.

      This is a no-op on a read-only property.

      Parameters:
      m - The bean map to set the property value on.
      pName - The property name if this is a dyna property (i.e. "*").
      Otherwise can be null.
      value - The value to set. Can be null to set the property to null.
      Returns:
      The previous property value.
      Throws:
      BeanRuntimeException - If property could not be set.

    • properties

      protected FluentMap<String,Object> properties()

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • isWriteOnly

      public boolean isWriteOnly()
      Returns true if this property is write-only.

      This implies the property MIGHT be readable, but that serializers should not serialize it.

      Returns:
      true if this property is write-only.

    • setArray

      protected void setArray(Object bean, List l) throws IllegalArgumentException, IllegalAccessException, InvocationTargetException
      Sets an array field on this bean.

      Works on both Object and primitive arrays.

      Marshalling-only path. Requires a property built via the marshalling-side construction path (i.e. with a non-null rawTypeMeta). When the owning BeanMeta was built via BeanMeta.of(Class, BeanConfigContext), this method throws UnsupportedOperationException because the array element type is only known via rawTypeMeta, which is not populated in the bean-modeling-only path.

      Parameters:
      bean - The bean of the field.
      l - The collection to use to set the array field.
      Throws:
      IllegalArgumentException - Thrown by method invocation.
      IllegalAccessException - Thrown by method invocation.
      InvocationTargetException - Thrown by method invocation.
      UnsupportedOperationException - If this property was built via the bean-modeling-only path (BeanMeta.of(Class, BeanConfigContext)).