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
Error
s instead of
Exception
s.
This rationale behind this is that:
- The programmer should not have to wrap all accesses to
the Attributes API in a try/catch clause.
- An Exception being thrown here is caused by missing classes
or other "Error-like" conditions.
Null References
If a parameter to a method may not be null, and a null is passed to the
method, a
java.lang.NullPointerException
will be thrown, with the
parameter name in the message.
Rationale for using this instead of
java.lang.IllegalArgumentException
is that it is more precise - the reference was null.
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 <3210000; 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 <3210000; i++) {
if (shouldDoThis) {
doThis(myClass);
} else {
doThat(myClass);
}
}
if the loop should run at maximum speed.
getAttribute
public static Object getAttribute(Class clazz,
Class attributeClass)
throws RepositoryError,
MultipleAttributesError
Get one attributes of a given type from a class.
clazz
- the class. May not be null
.attributeClass
- the type of attribute wanted. May be null
, but this will not match anything.
- the attribute instance, or
null
of none could be found.
getAttribute
private static Object getAttribute(Collection attrs,
Class attributeClass)
throws MultipleAttributesError
Selects from a collection of attributes one attribute with a given class.
attrs
- the collection of attribute instances to select from.attributeClass
- the type of attribute wanted. May be null
, but this will not match anything.
- the attribute instance, or
null
of none could be found.
getAttribute
public static Object getAttribute(Constructor constructor,
Class attributeClass)
throws RepositoryError,
MultipleAttributesError
Get one attributes of a given type from a constructor.
constructor
- the constructor. May not be null
.attributeClass
- the type of attribute wanted. May be null
, but this will not match anything.
- the attribute instance, or
null
of none could be found.
getAttribute
public static Object getAttribute(Field field,
Class attributeClass)
throws RepositoryError,
MultipleAttributesError
Get one attributes of a given type from a field.
field
- the field. May not be null
.attributeClass
- the type of attribute wanted. May be null
, but this will not match anything.
- the attribute instance, or
null
of none could be found.
getAttribute
public static Object getAttribute(Method method,
Class attributeClass)
throws RepositoryError,
MultipleAttributesError
Get one attributes of a given type from a method.
method
- the method. May not be null
.attributeClass
- the type of attribute wanted. May be null
, but this will not match anything.
- the attribute instance, or
null
of none could be found.
getAttributes
public static Collection getAttributes(Class clazz)
throws RepositoryError
Gets all attributes for a class.
clazz
- the class. May not be null
.
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
.
clazz
- the class. May not be null
.attributeClass
- the type of attribute wanted. May be null
, but this will not match anything.
getAttributes
private static Collection getAttributes(Collection attrs,
Class attributeClass)
Selects from a collection of attributes only those with a given class.
getAttributes
public static Collection getAttributes(Constructor constructor)
throws RepositoryError
Gets all attributes for a constructor.
constructor
- the constructor. May not be null
.
getAttributes
public static Collection getAttributes(Constructor constructor,
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
.
constructor
- the constructor. May not be null
.attributeClass
- the type of attribute wanted. May be null
, but this will not match anything.
getAttributes
public static Collection getAttributes(Field field)
throws RepositoryError
Gets all attributes for a field.
field
- the field. May not be null
.
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
.
field
- the field. May not be null
.attributeClass
- the type of attribute wanted. May be null
, but this will not match anything.
getAttributes
public static Collection getAttributes(Method method)
throws RepositoryError
Gets all attributes for a method.
method
- the method. May not be null
.
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
.
method
- the method. May not be null
.attributeClass
- the type of attribute wanted. May be null
, but this will not match anything.
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.
constructor
- the constructor. May not be null
.parameter
- index of the parameter in the method's parameter list.attributeClass
- the type of attribute wanted. May be null
, but this will not match anything.
- the attribute instance, or
null
of none could be found.
getParameterAttribute
public static Object getParameterAttribute(Method method,
int parameter,
Class attributeClass)
throws RepositoryError,
MultipleAttributesError
Get one attributes of a given type from a parameter.
method
- the method. May not be null
.parameter
- index of the parameter in the method's parameter list.attributeClass
- the type of attribute wanted. May be null
, but this will not match anything.
- the attribute instance, or
null
of none could be found.
getParameterAttributes
public static Collection getParameterAttributes(Constructor constructor,
int parameter)
throws RepositoryError
Gets all attributes for a parameter of a constructor.
constructor
- the constructor. May not be null
.parameter
- the index of the parameter in the constructor's parameter list.
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
.
constructor
- the constructor. May not be null
.parameter
- index of the parameter in the constructor's parameter listattributeClass
- the type of attribute. May be null
, but this will not match anything.
getParameterAttributes
public static Collection getParameterAttributes(Method method,
int parameter)
throws RepositoryError
Gets all attributes for a parameter of a method.
method
- the method. May not be null
.parameter
- the index of the parameter in the method's parameter list.
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
.
method
- the method. May not be null
.parameter
- index of the parameter in the method's parameter listattributeClass
- the type of attribute wanted. May be null
, but this will not match anything.
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.
method
- the method. May not be null
.attributeClass
- the type of attribute wanted. May be null
, but this will not match anything.
- the attribute instance, or
null
of none could be found.
getReturnAttributes
public static Collection getReturnAttributes(Method method)
throws RepositoryError
Gets all attributes for the return value of a method.
method
- the method. May not be null
.
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
.
method
- the methodattributeClass
- the type of attribute wanted. May be null
, but this will not match anything.
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)
?
clazz
- the class. May not be null
.attribute
- the attribute to compare to.
hasAttribute
private static boolean hasAttribute(Collection attrs,
Object attribute)
throws RepositoryError
Convenience function to test whether a collection of attributes contain
an attribute.
hasAttribute
public static boolean hasAttribute(Constructor constructor,
Object attribute)
throws RepositoryError
Tests if a constructor has an attribute. That is, is there any attribute
attr
such that attr.equals(attribute)
?
constructor
- the constructor. May not be null
.attribute
- the attribute to compare to.
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)
?
field
- the field. May not be null
.attribute
- the attribute to compare to.
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)
?
method
- the method. May not be null
.attribute
- the attribute to compare to.
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
?
clazz
- the class. May not be null
.attributeClass
- the type of attribute. May be null
, but this will not match anything.
hasAttributeType
private static boolean hasAttributeType(Collection attrs,
Class attributeClass)
Convenience function to test whether a collection of attributes contain
an attribute of a given class.
hasAttributeType
public static boolean hasAttributeType(Constructor constructor,
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
?
constructor
- the constructor. May not be null
.attributeClass
- the type of attribute. May be null
, but this will not match anything.
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
?
field
- the field. May not be null
.attributeClass
- the type of attribute. May be null
, but this will not match anything.
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
?
method
- the method. May not be null
.attributeClass
- the type of attribute. May be null
, but this will not match anything.
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)
?
constructor
- the constructor. May not be null
.parameter
- the index of the parameter in the constructor's parameter list.attribute
- the attribute to compare to.
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)
?
method
- the method. May not be null
.parameter
- the index of the parameter in the method's parameter list.attribute
- the attribute to compare to.
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
?
constructor
- the constructor. May not be null
.parameter
- the index of the parameter in the constructor's parameter list.attributeClass
- the type of attribute. May be null
, but this will not match anything.
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
?
method
- the method. May not be null
.parameter
- the index of the parameter in the method's parameter list.attributeClass
- the type of attribute. May be null
, but this will not match anything.
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)
?
method
- the method. May not be null
.attribute
- the attribute to compare to.
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
?
method
- the method. May not be null
.attributeClass
- the type of attribute. May be null
, but this will not match anything.
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.
repo
- The repository. The repository will be sealed before any attributes are
set. This to guarantee that the repository remains constant
during setting.