org.carrot2.util.attribute
Class AttributeBinder

java.lang.Object
  org.carrot2.util.attribute.AttributeBinder

public class AttributeBinder
extends Object

Provides methods for binding (setting and getting) values of attributes defined by the Attribute annotation.

Nested Class Summary

static class	AttributeBinder.AllAnnotationsPresentPredicate A predicate that evaluates to true if the attribute is annotated with all of the provided annotations.
static class	AttributeBinder.AttributeBinderActionBind An action that binds all Input attributes.
static class	AttributeBinder.AttributeBinderActionCollect An action that binds all Output attributes.
static class	AttributeBinder.AttributeTransformerFromString Transforms String attribute values to the types required by the target field by: Leaving non-String typed values unchanged. Looking for a static valueOf(String) in the target type and using it for conversion. If the method is not available, trying to load a class named as the value of the attribute, so that this class can be further coerced to the class instance. If the class cannot be loaded, leaving the the value unchanged.
static class	AttributeBinder.BindingTracker Tracks which attributes have already been collected and prevents overwriting of collected values.
static interface	AttributeBinder.IAttributeBinderAction An action to be applied during attribute binding.
static interface	AttributeBinder.IAttributeTransformer Transforms attribute values.

Constructor Summary

AttributeBinder()

Method Summary

static void	bind(Object object, AttributeBinder.IAttributeBinderAction[] attributeBinderActions, Class<? extends Annotation>... filteringAnnotations) A generic method for performing actions on the object's hierarchy of attributes.
static void	bind(Object object, AttributeBinder.IAttributeBinderAction[] attributeBinderActions, com.google.common.base.Predicate<Field> predicate) A generic method for performing actions on the object's hierarchy of attributes.
static void	get(Object object, Map<String,Object> values, Class<? extends Annotation>... filteringAnnotations) Gets (collects) Attribute values from the provided instance into the provided Map.
static Map<String,Object>	set(Object object, Map<String,Object> values, boolean checkRequired, com.google.common.base.Predicate<Field> predicate) A version of set(Object, Map, boolean, Class...) with a AttributeBinder.AllAnnotationsPresentPredicate instead of filtering annotations.
static Map<String,Object>	set(Object object, Map<String,Object> values, Class<? extends Annotation>... filteringAnnotations) Sets Attribute values on the provided instance.
static <T> Map<String,Object>	set(T object, Map<String,Object> values, boolean checkRequired, Class<? extends Annotation>... filteringAnnotations) A version of set(Object, Map, Class...) that can optionally skip Required attribute checking.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AttributeBinder

public AttributeBinder()

Method Detail

set

public static Map<String,Object> set(Object object,
                                     Map<String,Object> values,
                                     Class<? extends Annotation>... filteringAnnotations)
                              throws InstantiationException,
                                     AttributeBindingException

Sets Attribute values on the provided instance.

Setting of attribute values will be performed for all attributes of the provided object, no matter where in the object's hierarchy the attribute is declared. This method will recursively descend into all fields of the object whose types are marked with Bindable, no matter whether these fields are attributes or not.

Keys of the values map are interpreted as attribute keys as defined by Attribute.key(). When setting attribute values, the map must contain non- null mappings for all Required attributes that have not yet been set on the object to a non-null value. Otherwise an AttributeBindingException will be thrown. If the map has no mapping for some non-Required attribute, the value of that attribute will not be changed. However, if the map contains a null mapping for some non- Required attribute, the value that attribute will be set to null.

When setting attributes, values will be transferred from the map without any conversion with two exceptions:

1. If the type of the value is String and the type of the attribute field is not String, the AttributeBinder.AttributeTransformerFromString will be applied to the value prior to transferring it to the attribute field. If you want to bypass this conversion, use bind(Object, IAttributeBinderAction[], Class...).
2. If the type of the attribute field is not Class and the corresponding value in the values map is of type Class, an attempt will be made to coerce the class to a corresponding instance by calling its parameterless constructor. If the created type is Bindable, an attempt will also be made to set attributes of the newly created object using the values map and current filteringAnnotations.

Before value of an attribute is set, the new value is checked against all constraints defined for the attribute and must meet all these constraints. Otherwise, the ConstraintViolationException will be thrown.

Parameters:

object - the object to set the attributes on. The type of the provided object must be annotated with Bindable.

values - the values of attributes to be set.

filteringAnnotations - additional domain-specific annotations that the attribute fields must have in order to be bound. This parameter can be used to selectively set different sets of attributes depending, e.g. on the life cycle of the object.

Returns:

entries from the values map that did not get transferred to any of the attributes.

Throws:

InstantiationException - if coercion of a class attribute value to an instance fails, e.g. because the parameterless constructor is not present/ visible.

AttributeBindingException - if in the values map there are no or null values provided for one or more Required attributes.

AttributeBindingException - reflection-based setting or reading field values fails.

IllegalArgumentException - if object's type is not Bindable.

IllegalArgumentException - for debugging purposes, if an attribute field is found that is missing some of the required annotations.

UnsupportedOperationException - if an attempt is made to bind values of attributes with circular references.

set

public static <T> Map<String,Object> set(T object,
                                         Map<String,Object> values,
                                         boolean checkRequired,
                                         Class<? extends Annotation>... filteringAnnotations)
                              throws InstantiationException,
                                     AttributeBindingException

A version of set(Object, Map, Class...) that can optionally skip Required attribute checking. For experts only.

Throws:

InstantiationException

AttributeBindingException

set

public static Map<String,Object> set(Object object,
                                     Map<String,Object> values,
                                     boolean checkRequired,
                                     com.google.common.base.Predicate<Field> predicate)
                              throws InstantiationException,
                                     AttributeBindingException

A version of set(Object, Map, boolean, Class...) with a AttributeBinder.AllAnnotationsPresentPredicate instead of filtering annotations. For experts only.

Throws:

InstantiationException

AttributeBindingException

get

public static void get(Object object,
                       Map<String,Object> values,
                       Class<? extends Annotation>... filteringAnnotations)
                throws InstantiationException,
                       AttributeBindingException

Gets (collects) Attribute values from the provided instance into the provided Map.

Values will be collected for all attributes of the provided object, no matter where in the object's hierarchy the attribute is declared. This method will recursively descend into all fields of the object whose types are marked with Bindable, no matter whether these fields are attributes or not.

Values of each attribute, including null values, will be stored in the provided map under a key equal to the attribute's as defined by Attribute.key().

Parameters:

object - the object to collect attributes from. The type of the provided object must be annotated with Bindable.

values - placeholder for attributes to be collected. The provided Map must be modifiable.

filteringAnnotations - additional domain-specific annotations that the attribute fields must have in order to be bound. This parameter can be used to selectively collect different sets of attributes depending, e.g. on the life cycle of the object.

Throws:

AttributeBindingException - if reflection-based reading of field values fails.

IllegalArgumentException - if object's type is not Bindable.

IllegalArgumentException - for debugging purposes, if an attribute field is found that is missing some of the required annotations.

UnsupportedOperationException - if an attempt is made to collect values of attributes with circular references.

InstantiationException

bind

public static void bind(Object object,
                        AttributeBinder.IAttributeBinderAction[] attributeBinderActions,
                        Class<? extends Annotation>... filteringAnnotations)
                 throws InstantiationException,
                        AttributeBindingException

A generic method for performing actions on the object's hierarchy of attributes. For experts only.

Throws:

InstantiationException

AttributeBindingException

bind

public static void bind(Object object,
                        AttributeBinder.IAttributeBinderAction[] attributeBinderActions,
                        com.google.common.base.Predicate<Field> predicate)
                 throws InstantiationException,
                        AttributeBindingException

A generic method for performing actions on the object's hierarchy of attributes. For experts only.

Throws:

InstantiationException

AttributeBindingException