org.apache.commons.attributes
Class Attributes

java.lang.Object
  |
  +--org.apache.commons.attributes.Attributes

public class Attributes
extends Object

API for accessing attributes.

General Notes on Errors

All Methods in this class may throw RepositoryError or subclasses thereof. This Error is thrown if an attribute repository can not be loaded for some Exceptional reason.

Rationale for Errors instead of Exceptions

The methods in this class throws Errors instead of Exceptions. This rationale behind this is that:

Performance Notes

The process of loading attributes for a class is a (relatively) time-consuming process, as it involves some dynamic linking in the form of inheritable attributes, a lot of reflection and so on. However, once loaded the attributes are cached, so repeated access to them are fast. But despite this the process of finding one attribute of a given type or such operations does involve some iteration of HashSets that runs in linear time in the number of attributes associated with the program element, and you should avoid accessing attributes in your innermost loops if you can avoid it. For example, instead of:

 Class myClass = ...;
 for (int i = 0; i < 10000; i++) {
     if (Attributes.hasAttributeType (myClass, MyAttribute.class)) {
         doThis(myClass);
     } else {
         doThat(myClass);
     }
 }
 
do:

 Class myClass = ...;
 boolean shouldDoThis = Attributes.hasAttributeType (myClass, MyAttribute.class);
 for (int i = 0; i < 10000; i++) {
     if (shouldDoThis) {
         doThis(myClass);
     } else {
         doThat(myClass);
     }
 }
 
if the loop should run at maximum speed.


Constructor Summary
Attributes()
           
 
Method Summary
static Object getAttribute(Class clazz, Class attributeClass)
          Get one attributes of a given type from a class.
static Object getAttribute(Constructor ctor, Class attributeClass)
          Get one attributes of a given type from a constructor.
static Object getAttribute(Field field, Class attributeClass)
          Get one attributes of a given type from a field.
static Object getAttribute(Method method, Class attributeClass)
          Get one attributes of a given type from a method.
static Collection getAttributes(Class clazz)
          Gets all attributes for a class.
static Collection getAttributes(Class clazz, Class attributeClass)
          Get all attributes of a given type from a class.
static Collection getAttributes(Constructor cons)
          Gets all attributes for a constructor.
static Collection getAttributes(Constructor ctor, Class attributeClass)
          Get all attributes of a given type from a constructor.
static Collection getAttributes(Field field)
          Gets all attributes for a field.
static Collection getAttributes(Field field, Class attributeClass)
          Get all attributes of a given type from a field.
static Collection getAttributes(Method method)
          Gets all attributes for a method.
static Collection getAttributes(Method method, Class attributeClass)
          Get all attributes of a given type from a method.
static Object getParameterAttribute(Constructor constructor, int parameter, Class attributeClass)
          Get one attributes of a given type from a constructor's parameter.
static Object getParameterAttribute(Method method, int parameter, Class attributeClass)
          Get one attributes of a given type from a parameter.
static Collection getParameterAttributes(Constructor constructor, int parameter)
          Gets all attributes for a parameter of a constructor.
static Collection getParameterAttributes(Constructor constructor, int parameter, Class attributeClass)
          Get all attributes of a given type from a method's parameter.
static Collection getParameterAttributes(Method method, int parameter)
          Gets all attributes for a parameter of a method.
static Collection getParameterAttributes(Method method, int parameter, Class attributeClass)
          Get all attributes of a given type from a method's parameter.
static Object getReturnAttribute(Method method, Class attributeClass)
          Get one attributes of a given type from a method's return value.
static Collection getReturnAttributes(Method method)
          Gets all attributes for the return value of a method.
static Collection getReturnAttributes(Method method, Class attributeClass)
          Get all attributes of a given type from a method's return value.
static boolean hasAttribute(Class clazz, Object attribute)
          Tests if a class has an attribute.
static boolean hasAttribute(Constructor ctor, Object attribute)
          Tests if a constructor has an attribute.
static boolean hasAttribute(Field field, Object attribute)
          Tests if a field has an attribute.
static boolean hasAttribute(Method method, Object attribute)
          Tests if a method has an attribute.
static boolean hasAttributeType(Class clazz, Class attributeClass)
          Tests if a class has an attribute of a given type.
static boolean hasAttributeType(Constructor ctor, Class attributeClass)
          Tests if a constructor has an attribute of a given type.
static boolean hasAttributeType(Field field, Class attributeClass)
          Tests if a field has an attribute of a given type.
static boolean hasAttributeType(Method method, Class attributeClass)
          Tests if a method has an attribute of a given type.
static boolean hasParameterAttribute(Constructor constructor, int parameter, Object attribute)
          Tests if a constructor's parameter has an attribute.
static boolean hasParameterAttribute(Method method, int parameter, Object attribute)
          Tests if a method's parameter has an attribute.
static boolean hasParameterAttributeType(Constructor constructor, int parameter, Class attributeClass)
          Tests if a constructor's parameter has an attribute of a given type.
static boolean hasParameterAttributeType(Method method, int parameter, Class attributeClass)
          Tests if a method's parameter has an attribute of a given type.
static boolean hasReturnAttribute(Method method, Object attribute)
          Tests if a method's return value has an attribute.
static boolean hasReturnAttributeType(Method method, Class attributeClass)
          Tests if a method's return value has an attribute of a given type.
static void setAttributes(RuntimeAttributeRepository repo)
          Set attributes for a given class.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Attributes

public Attributes()
Method Detail

getAttribute

public static Object getAttribute(Class clazz,
                                  Class attributeClass)
                           throws RepositoryError,
                                  MultipleAttributesError
Get one attributes of a given type from a class.

Returns:
the attribute instance, or null of none could be found.
Throws:
MultipleAttributesError - if the collection contains more than one instance of the specified class.
RepositoryError

getAttribute

public static Object getAttribute(Field field,
                                  Class attributeClass)
                           throws RepositoryError,
                                  MultipleAttributesError
Get one attributes of a given type from a field.

Returns:
the attribute instance, or null of none could be found.
Throws:
MultipleAttributesError - if the collection contains more than one instance of the specified class.
RepositoryError

getAttribute

public static Object getAttribute(Constructor ctor,
                                  Class attributeClass)
                           throws RepositoryError,
                                  MultipleAttributesError
Get one attributes of a given type from a constructor.

Returns:
the attribute instance, or null of none could be found.
Throws:
MultipleAttributesError - if the collection contains more than one instance of the specified class.
RepositoryError

getAttribute

public static Object getAttribute(Method method,
                                  Class attributeClass)
                           throws RepositoryError,
                                  MultipleAttributesError
Get one attributes of a given type from a method.

Returns:
the attribute instance, or null of none could be found.
Throws:
MultipleAttributesError - if the collection contains more than one instance of the specified class.
RepositoryError

getParameterAttribute

public static Object getParameterAttribute(Method method,
                                           int parameter,
                                           Class attributeClass)
                                    throws RepositoryError,
                                           MultipleAttributesError
Get one attributes of a given type from a parameter.

Returns:
the attribute instance, or null of none could be found.
Throws:
MultipleAttributesError - if the collection contains more than one instance of the specified class.
RepositoryError

getParameterAttribute

public static Object getParameterAttribute(Constructor constructor,
                                           int parameter,
                                           Class attributeClass)
                                    throws RepositoryError,
                                           MultipleAttributesError
Get one attributes of a given type from a constructor's parameter.

Returns:
the attribute instance, or null of none could be found.
Throws:
MultipleAttributesError - if the collection contains more than one instance of the specified class.
RepositoryError

getReturnAttribute

public static Object getReturnAttribute(Method method,
                                        Class attributeClass)
                                 throws RepositoryError,
                                        MultipleAttributesError
Get one attributes of a given type from a method's return value.

Returns:
the attribute instance, or null of none could be found.
Throws:
MultipleAttributesError - if the collection contains more than one instance of the specified class.
RepositoryError

getAttributes

public static Collection getAttributes(Class clazz)
                                throws RepositoryError
Gets all attributes for a class.

RepositoryError

getAttributes

public static Collection getAttributes(Method method)
                                throws RepositoryError
Gets all attributes for a method.

RepositoryError

getParameterAttributes

public static Collection getParameterAttributes(Method method,
                                                int parameter)
                                         throws RepositoryError
Gets all attributes for a parameter of a method.

RepositoryError

getParameterAttributes

public static Collection getParameterAttributes(Constructor constructor,
                                                int parameter)
                                         throws RepositoryError
Gets all attributes for a parameter of a constructor.

RepositoryError

getReturnAttributes

public static Collection getReturnAttributes(Method method)
                                      throws RepositoryError
Gets all attributes for the return value of a method.

RepositoryError

getAttributes

public static Collection getAttributes(Field field)
                                throws RepositoryError
Gets all attributes for a field.

RepositoryError

getAttributes

public static Collection getAttributes(Constructor cons)
                                throws RepositoryError
Gets all attributes for a constructor.

RepositoryError

getAttributes

public static Collection getAttributes(Class clazz,
                                       Class attributeClass)
                                throws RepositoryError
Get all attributes of a given type from a class. For all objects o in the returned collection, o.getClass() == attributeClass.

RepositoryError

getAttributes

public static Collection getAttributes(Field field,
                                       Class attributeClass)
                                throws RepositoryError
Get all attributes of a given type from a field. For all objects o in the returned collection, o.getClass() == attributeClass.

RepositoryError

getAttributes

public static Collection getAttributes(Constructor ctor,
                                       Class attributeClass)
                                throws RepositoryError
Get all attributes of a given type from a constructor. For all objects o in the returned collection, o.getClass() == attributeClass.

RepositoryError

getAttributes

public static Collection getAttributes(Method method,
                                       Class attributeClass)
                                throws RepositoryError
Get all attributes of a given type from a method. For all objects o in the returned collection, o.getClass() == attributeClass.

RepositoryError

getParameterAttributes

public static Collection getParameterAttributes(Method method,
                                                int parameter,
                                                Class attributeClass)
                                         throws RepositoryError
Get all attributes of a given type from a method's parameter. For all objects o in the returned collection, o.getClass() == attributeClass.

RepositoryError

getParameterAttributes

public static Collection getParameterAttributes(Constructor constructor,
                                                int parameter,
                                                Class attributeClass)
                                         throws RepositoryError
Get all attributes of a given type from a method's parameter. For all objects o in the returned collection, o.getClass() == attributeClass.

RepositoryError

getReturnAttributes

public static Collection getReturnAttributes(Method method,
                                             Class attributeClass)
                                      throws RepositoryError
Get all attributes of a given type from a method's return value. For all objects o in the returned collection, o.getClass() == attributeClass.

RepositoryError

hasAttributeType

public static boolean hasAttributeType(Class clazz,
                                       Class attributeClass)
                                throws RepositoryError
Tests if a class has an attribute of a given type. That is, is there any attribute attr such that attr.getClass() == attributeClass?

RepositoryError

hasAttributeType

public static boolean hasAttributeType(Field field,
                                       Class attributeClass)
                                throws RepositoryError
Tests if a field has an attribute of a given type. That is, is there any attribute attr such that attr.getClass() == attributeClass?

RepositoryError

hasAttributeType

public static boolean hasAttributeType(Constructor ctor,
                                       Class attributeClass)
                                throws RepositoryError
Tests if a constructor has an attribute of a given type. That is, is there any attribute attr such that attr.getClass() == attributeClass?

RepositoryError

hasAttributeType

public static boolean hasAttributeType(Method method,
                                       Class attributeClass)
                                throws RepositoryError
Tests if a method has an attribute of a given type. That is, is there any attribute attr such that attr.getClass() == attributeClass?

RepositoryError

hasParameterAttributeType

public static boolean hasParameterAttributeType(Method method,
                                                int parameter,
                                                Class attributeClass)
                                         throws RepositoryError
Tests if a method's parameter has an attribute of a given type. That is, is there any attribute attr such that attr.getClass() == attributeClass?

RepositoryError

hasParameterAttributeType

public static boolean hasParameterAttributeType(Constructor constructor,
                                                int parameter,
                                                Class attributeClass)
                                         throws RepositoryError
Tests if a constructor's parameter has an attribute of a given type. That is, is there any attribute attr such that attr.getClass() == attributeClass?

RepositoryError

hasReturnAttributeType

public static boolean hasReturnAttributeType(Method method,
                                             Class attributeClass)
                                      throws RepositoryError
Tests if a method's return value has an attribute of a given type. That is, is there any attribute attr such that attr.getClass() == attributeClass?

RepositoryError

hasAttribute

public static boolean hasAttribute(Class clazz,
                                   Object attribute)
                            throws RepositoryError
Tests if a class has an attribute. That is, is there any attribute attr such that attr.equals(attribute)?

RepositoryError

hasAttribute

public static boolean hasAttribute(Field field,
                                   Object attribute)
                            throws RepositoryError
Tests if a field has an attribute. That is, is there any attribute attr such that attr.equals(attribute)?

RepositoryError

hasAttribute

public static boolean hasAttribute(Constructor ctor,
                                   Object attribute)
                            throws RepositoryError
Tests if a constructor has an attribute. That is, is there any attribute attr such that attr.equals(attribute)?

RepositoryError

hasAttribute

public static boolean hasAttribute(Method method,
                                   Object attribute)
                            throws RepositoryError
Tests if a method has an attribute. That is, is there any attribute attr such that attr.equals(attribute)?

RepositoryError

hasParameterAttribute

public static boolean hasParameterAttribute(Method method,
                                            int parameter,
                                            Object attribute)
                                     throws RepositoryError
Tests if a method's parameter has an attribute. That is, is there any attribute attr such that attr.equals(attribute)?

RepositoryError

hasParameterAttribute

public static boolean hasParameterAttribute(Constructor constructor,
                                            int parameter,
                                            Object attribute)
                                     throws RepositoryError
Tests if a constructor's parameter has an attribute. That is, is there any attribute attr such that attr.equals(attribute)?

RepositoryError

hasReturnAttribute

public static boolean hasReturnAttribute(Method method,
                                         Object attribute)
                                  throws RepositoryError
Tests if a method's return value has an attribute. That is, is there any attribute attr such that attr.equals(attribute)?

RepositoryError

setAttributes

public static void setAttributes(RuntimeAttributeRepository repo)
                          throws IllegalStateException
Set attributes for a given class. The class must not have attributes set for it already (i.e. you can't redefine the attributes of a class at runtime). This because it really messes up the concept of inheritable attributes, and because the attribute set associated with a class is immutable, like the set of methods and fields.

Parameters:
repo - The repository. The repository will be sealed before any attributes are set. This to guarantee that the repository remains constant during setting.
Throws:
IllegalStateException - if the class whose attributes are defined already have attributes defined for it (even if it has no attributes).


Copyright © The Apache Software Foundation. All Rights Reserved.