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 collecting) values of attributes defined by the Attribute annotation.

Nested Class Summary

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.FilteringAnnotationsPredicate A predicate that evaluates to true if the attribute is annotated with at least one of the provided annotations.
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 <T> void	bind(T object, AttributeBinder.IAttributeBinderAction[] attributeBinderActions, Class<? extends Annotation> bindingDirectionAnnotation, Class<? extends Annotation>... filteringAnnotations) A more flexible version of bind(Object, Map, Class, Class...) that accepts custom AttributeBinder.IAttributeBinderActions.
static <T> void	bind(T object, AttributeBinder.IAttributeBinderAction[] attributeBinderActions, Class<? extends Annotation> bindingDirectionAnnotation, com.google.common.base.Predicate<Field> predicate) A more flexible version of bind(Object, Map, Class, Class...) that accepts custom AttributeBinder.IAttributeBinderActions.
static <T> Map<String,Object>	bind(T object, Map<String,Object> values, boolean checkRequired, Class<? extends Annotation> bindingDirectionAnnotation, Class<? extends Annotation>... filteringAnnotations) A version of bind(Object, Map, Class, Class...) that can optionally skip Required attribute checking.
static <T> Map<String,Object>	bind(T object, Map<String,Object> values, boolean checkRequired, Class<? extends Annotation> bindingDirectionAnnotation, com.google.common.base.Predicate<Field> predicate) A version of bind(Object, Map, boolean, Class, Class...) with a AttributeBinder.FilteringAnnotationsPredicate instead of filtering annotations.
static <T> Map<String,Object>	bind(T object, Map<String,Object> values, Class<? extends Annotation> bindingDirectionAnnotation, Class<? extends Annotation>... filteringAnnotations) Performs binding (setting or collecting) of Attribute values on the provided instance.
static <T> Map<String,Object>	unbind(T object, Map<String,Object> values, Class<? extends Annotation> bindingDirectionAnnotation, Class<? extends Annotation>... filteringAnnotations) A complementary version of the bind(Object, Map, Class, Class...) method.

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

bind

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

Performs binding (setting or collecting) of Attribute values on the provided instance. The direction of binding, i.e. whether attributes will be set or collected from the object depends on the provided bindingDirectionAnnotation, which can be either Input or Output for setting and collecting attribute values of the object, respectively.

Binding will be performed for all attributes of the provided object, no matter where in the object's hierarchy the attribute is declared. Binding 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, 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 bind attributes of the newly created object using the values map, current bindingDirectionAnnotation and 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 or collect attributes from. The type of the provided object must be annotated with Bindable.

values - the values of Input attributes to be set or a placeholder for Output attributes to be collected. If attribute values are to be collected, the provided Map must be modifiable.

bindingDirectionAnnotation - Input if attribute values are to be set on the provided object, or Output if attribute values are to be collected from the object.

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

Returns:

entries from the values map that did not get bound to any of the Input 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 bindingDirectionAnnotation is different from Input or Output.

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.

bind

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

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

Throws:

InstantiationException

AttributeBindingException

bind

public static <T> Map<String,Object> bind(T object,
                                          Map<String,Object> values,
                                          boolean checkRequired,
                                          Class<? extends Annotation> bindingDirectionAnnotation,
                                          com.google.common.base.Predicate<Field> predicate)
                               throws InstantiationException,
                                      AttributeBindingException

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

Throws:

InstantiationException

AttributeBindingException

unbind

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

A complementary version of the bind(Object, Map, Class, Class...) method. This method collects values of Input attributes and sets values of Output attributes.

Returns:

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

Throws:

InstantiationException

AttributeBindingException

bind

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

A more flexible version of bind(Object, Map, Class, Class...) that accepts custom AttributeBinder.IAttributeBinderActions. For experts only.

Throws:

InstantiationException

AttributeBindingException

bind

public static <T> void bind(T object,
                            AttributeBinder.IAttributeBinderAction[] attributeBinderActions,
                            Class<? extends Annotation> bindingDirectionAnnotation,
                            com.google.common.base.Predicate<Field> predicate)
                 throws InstantiationException,
                        AttributeBindingException

A more flexible version of bind(Object, Map, Class, Class...) that accepts custom AttributeBinder.IAttributeBinderActions. For experts only.

Throws:

InstantiationException

AttributeBindingException