Property (minimalcode-reflect 0.5.1 API)

java.lang.Object
- org.minimalcode.reflect.Property

All Implemented Interfaces:

java.lang.reflect.AnnotatedElement
```
public final class Property
extends java.lang.Object
implements java.lang.reflect.AnnotatedElement
```
A Property provides instrospected information about, and dynamic access to, a single property of a Bean.
Accessors are matched based on the "get", "is" (for boolean) and "set" Method prefix. The following patterns are automatically discovered as valid property accessors:
- Read Method: T getField() || boolean isField()
- Write Method: void setField(T field)
Static and synthetic members are not considered valid accessors of a property. Read-only and write-only properties are all valid options.
If a backing Field with the same name and type as the property is present is the declaring class, it will be retrieved not taking into account its modifier. If it is present in a superclass instead, it will be retrieved only if it has a not-private modifier.
In any case, accessors don't have to specifically map the backing field with the same name, and the field is only used as an annotations provider, considering that annotating directly the backing field is a well established pattern.
While public properties are guaranteed to have at least a public accessor method (and consequently are always readable or writable), for declared properties it may happen that all the accessors methods are not accessible.
To preserve immutability, this class not provides a way to forcefully alter the property's accessibility. It is responsability of the developer to deal with it using directly the property's accessors.
Introspected information (like type or annotations) is collected from all the property's Members (and their ancestors), following a "best-available" design pattern.

Author:

Fabio Piro

See Also:

Bean, Bean.getProperties(), Bean.getProperty(String), Bean.getDeclaredProperties(), Bean.getDeclaredProperty(String)

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`equals(java.lang.Object obj)` Compares this property against the specified object.
`java.lang.Object`	`get(java.lang.Object obj)` Returns the value of the representation of this property from the specified object.
`java.lang.Class<?>`	`getActualType()` Returns the actual type of this property, from simple type or generics.
`<T extends java.lang.annotation.Annotation> T`	`getAnnotation(java.lang.Class<T> annotationClass)` Returns an annotation collectively present on this property's members, else `null`.
`java.lang.annotation.Annotation[]`	`getAnnotations()` Returns all the annotations that are collectively present on this property's members.
`<T extends java.lang.annotation.Annotation> T`	`getDeclaredAnnotation(java.lang.Class<T> annotationClass)` Returns this property's annotation for the specified type if such an annotation is collectively and directly present, else `null`.
`java.lang.annotation.Annotation[]`	`getDeclaredAnnotations()` Returns all the annotations that are collectively and directly present on this property's members.
`Bean<?>`	`getDeclaringBean()` Returns the `Bean` object that declares this property.
`java.lang.reflect.Field`	`getField()` Returns a copy of this property's `Field`, if present, else `null`.
`java.lang.reflect.Type`	`getGenericType()` Returns a `Type` object that represents the declared type for the property represented by this `Property` object.
`java.lang.String`	`getName()` Returns the simple name of this property.
`java.lang.reflect.Method`	`getReadMethod()` Returns a copy of this property's read`Method`, if present, else `null`.
`java.lang.Class<?>`	`getType()` Returns the type of this property.
`java.lang.reflect.Method`	`getWriteMethod()` Returns a copy of this property's write`Method`, if present, else `null`.
`int`	`hashCode()` Returns a hashcode for this `Property`.
`boolean`	`isAnnotationPresent(java.lang.Class<? extends java.lang.annotation.Annotation> annotationClass)` Returns true if an annotation for the specified type is collectively present on this property's members, else false.
`boolean`	`isReadable()` Returns true if this property has a valid getter\isser.
`boolean`	`isWritable()` Returns true if this property has a valid setter.
`void`	`set(java.lang.Object obj, java.lang.Object value)` Sets a new value to the representation of this property on the specified object.
`java.lang.String`	`toString()` Returns a textual rapresentation of this property.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.reflect.AnnotatedElement
getAnnotationsByType, getDeclaredAnnotationsByType

- Method Detail
  - getAnnotations
```
public java.lang.annotation.Annotation[] getAnnotations()
```
    Returns all the annotations that are collectively present on this property's members.
    Annotation may be inherited from members declared in a superclass.
    In the case of collision of an annotation with the same type in the leaf class from a different AnnotatedElement, the overriding order is: field, readMethod and finally writeMethod.
    If there are no annotations found, the return value is an array of length 0.
    The caller of this method is free to modify the returned array; it will have no effect on the arrays returned to other callers.
    The elements in the returned array are not sorted and are not in any particular order.
    
    Specified by:
    
    getAnnotations in interface java.lang.reflect.AnnotatedElement
    
    Returns:
    
    annotations collectively present on this property's members
  - getDeclaredAnnotations
```
public java.lang.annotation.Annotation[] getDeclaredAnnotations()
```
    Returns all the annotations that are collectively and directly present on this property's members. This method ignores inherited annotations.
    If there are no annotations collectively and directly present on this property's members, the return value is an array of length 0.
    The caller of this method is free to modify the returned array; it will have no effect on the arrays returned to other callers.
    The elements in the returned array are not sorted and are not in any particular order.
    
    Specified by:
    
    getDeclaredAnnotations in interface java.lang.reflect.AnnotatedElement
    
    Returns:
    
    annotations collectively and directly present on this property's members
  - getAnnotation
```
public <T extends java.lang.annotation.Annotation> T getAnnotation(java.lang.Class<T> annotationClass)
```
    Returns an annotation collectively present on this property's members, else null.
    
    Specified by:
    
    getAnnotation in interface java.lang.reflect.AnnotatedElement
    
    Type Parameters:
    
    T - the type of the annotation to query for and return, if collectively present
    
    Parameters:
    
    annotationClass - the Class object corresponding to the annotation type
    
    Returns:
    
    the specified annotation type if collectively present on this property, else null
    
    Throws:
    
    java.lang.NullPointerException - if the given annotation class is null
  - getDeclaredAnnotation
```
public <T extends java.lang.annotation.Annotation> T getDeclaredAnnotation(java.lang.Class<T> annotationClass)
```
    Returns this property's annotation for the specified type if such an annotation is collectively and directly present, else null.
    This method ignores inherited annotations. and returns null if no annotations are collectively and directly present on this property's members.
    
    Specified by:
    
    getDeclaredAnnotation in interface java.lang.reflect.AnnotatedElement
    
    Type Parameters:
    
    T - the type of the annotation to query for and return if collectively and directly present
    
    Parameters:
    
    annotationClass - the Class corresponding to the annotation type
    
    Returns:
    
    this property's annotation for the specified annotation type if collectively and directly present on this element, else null
    
    Throws:
    
    java.lang.NullPointerException - if the given annotation class is null
  - isAnnotationPresent
```
public boolean isAnnotationPresent(java.lang.Class<? extends java.lang.annotation.Annotation> annotationClass)
```
    Returns true if an annotation for the specified type is collectively present on this property's members, else false.
    
    Specified by:
    
    isAnnotationPresent in interface java.lang.reflect.AnnotatedElement
    
    Parameters:
    
    annotationClass - the Class object corresponding to the annotation type
    
    Returns:
    
    true if an annotation for the specified type is collectively present on this property, else false
    
    Throws:
    
    java.lang.NullPointerException - if the given annotationClass is null
  - getDeclaringBean
```
public Bean<?> getDeclaringBean()
```
    Returns the Bean object that declares this property.
    
    Returns:
    
    an object representing the declaring bean
  - getName
```
public java.lang.String getName()
```
    Returns the simple name of this property.
    The name is the lowercased method's name without the relative prefix (get\is\set).
    
    Returns:
    
    the simple name of this property
  - getType
```
public java.lang.Class<?> getType()
```
    Returns the type of this property.
    
    Returns:
    
    the type class
  - getActualType
```
public java.lang.Class<?> getActualType()
```
    Returns the actual type of this property, from simple type or generics.
    The actual type is the plain type for simple property, the generic element resolved type for List, Iterable, array and Map property, or null for not resolved generic type.
    
    Returns:
    
    the actual type of this property, or null if unresolved
  - getGenericType
```
public java.lang.reflect.Type getGenericType()
```
    Returns a Type object that represents the declared type for the property represented by this Property object.
    
    Returns:
    
    the type object for this property
  - getReadMethod
```
public java.lang.reflect.Method getReadMethod()
```
    Returns a copy of this property's readMethod, if present, else null.
    
    Returns:
    
    A copy of the getter/isser method, or null if this property has no valid getter/isser
  - getWriteMethod
```
public java.lang.reflect.Method getWriteMethod()
```
    Returns a copy of this property's writeMethod, if present, else null.
    
    Returns:
    
    A copy of the setter method, or null if this proprety has no valid setter
  - getField
```
public java.lang.reflect.Field getField()
```
    Returns a copy of this property's Field, if present, else null.
    
    Returns:
    
    A copy of the underlying field, or null if this property has no field
  - isReadable
```
public boolean isReadable()
```
    Returns true if this property has a valid getter\isser.
    
    Returns:
    
    true if this property is readable from an object, else false
  - isWritable
```
public boolean isWritable()
```
    Returns true if this property has a valid setter.
    
    Returns:
    
    true if this property is writable to an object, else false
  - get
```
public java.lang.Object get(java.lang.Object obj)
                     throws ReflectionException
```
    Returns the value of the representation of this property from the specified object.
    The underlying property's value is obtained trying to invoke the readMethod.
    If this Property object has no public readMethod, it is considered write-only, and the action will be prevented throwing a ReflectionException.
    The value is automatically wrapped in an object if it has a primitive type.
    
    Parameters:
    
    obj - object from which the property's value is to be extracted
    
    Returns:
    
    the value of the represented property in object obj
    
    Throws:
    
    ReflectionException - if access to the underlying method throws an exception
    
    ReflectionException - if this property is write-only (no public readMethod)
  - set
```
public void set(java.lang.Object obj,
                java.lang.Object value)
         throws ReflectionException
```
    Sets a new value to the representation of this property on the specified object.
    The underlying property's value will be updated trying to invoke the writeMethod.
    If this Property object has no public writeMethod, it is considered read-only, and the action will be prevented throwing a ReflectionException.
    The new value is automatically unwrapped if the property has a primitive type.
    
    Parameters:
    
    obj - the object whose property should be modified
    
    value - the new value for the property of obj, can be null
    
    Throws:
    
    ReflectionException - if accessing to the underlying method throws an exception
    
    ReflectionException - if this property is read-only (no public writeMethod)
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Compares this property against the specified object.
    Two properties are the same if they were declared in the same bean and have the same name and the same accessors. Under the right circumstances a property and a declared property can be "technically" equivalent.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    
    obj - the object to compare
    
    Returns:
    
    true if the objects are the same
  - hashCode
```
public int hashCode()
```
    Returns a hashcode for this Property. This is computed as the exclusive-or of the hashcodes for the underlying bean's type class name and its simple name.
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    
    this property's hashcode
  - toString
```
public java.lang.String toString()
```
    Returns a textual rapresentation of this property.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    a String with this property's type followed by a dot and this property's name

Class Property

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.reflect.AnnotatedElement

Method Detail

getAnnotations

getDeclaredAnnotations

getAnnotation

getDeclaredAnnotation

isAnnotationPresent

getDeclaringBean

getName

getType

getActualType

getGenericType

getReadMethod

getWriteMethod

getField

isReadable

isWritable

get

set

equals

hashCode

toString