leosutic 2004/03/19 16:47:21
Modified: attributes/api/src/java/org/apache/commons/attributes
Indexed.java AttributeUtil.java Attributes.java
Log:
Improved JavaDoc.
Revision Changes Path
1.6 +2 -0
jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/Indexed.java
Index: Indexed.java
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/Indexed.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- Indexed.java 19 Feb 2004 14:49:13 -0000 1.5
+++ Indexed.java 20 Mar 2004 00:47:21 -0000 1.6
@@ -23,9 +23,11 @@
* MyService and MyService2 have Service as a class attribute, the
* jar-index will be:
*
+ * <pre><code>
* AttributeType: Service
* Class: MyService
* Class: MyService2
+ * </code></pre>
*/
public class Indexed {
}
1.6 +43 -7
jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/AttributeUtil.java
Index: AttributeUtil.java
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/AttributeUtil.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- AttributeUtil.java 19 Feb 2004 14:49:13 -0000 1.5
+++ AttributeUtil.java 20 Mar 2004 00:47:21 -0000 1.6
@@ -34,16 +34,34 @@
public class AttributeUtil {
/**
- * Filters a collection of <code>Class</code> objects. The returned collection
+ * Filters a Collection of <code>Class</code> objects. The returned collection
* only contains those classes that have an attribute of the specified type.
+ * That is, for each Class clazz in the
+ * returned collection,
+ * <code>clazz != null && Attributes.hasAttributeType (clazz,
attributeClass)</code>
+ * is true.
+ *
+ * @param classes Collection of Classes to filter. May contain
<code>null</code> references,
+ * but may not itself be <code>null</code>.
+ * @param attributeClass the class to filter based on.
*/
public static Collection getClassesWithAttributeType (Collection classes, Class
attributeClass) {
+ if (classes == null) {
+ throw new NullPointerException ("classes");
+ }
+
+ if (attributeClass == null) {
+ throw new NullPointerException ("attributeClass");
+ }
+
ArrayList result = new ArrayList ();
Iterator iter = classes.iterator ();
while (iter.hasNext ()) {
Class clazz = (Class) iter.next ();
- if (Attributes.hasAttributeType (clazz, attributeClass)) {
- result.add (clazz);
+ if (clazz != null) {
+ if (Attributes.hasAttributeType (clazz, attributeClass)) {
+ result.add (clazz);
+ }
}
}
@@ -52,16 +70,34 @@
/**
* Filters a collection of objects. The returned collection
- * only contains those objects that have an attribute of the specified type.
+ * only contains those objects whose class have an attribute
+ * of the specified type. That is, for each Object o in the
+ * returned collection,
+ * <code>o != null && Attributes.hasAttributeType (o.getClass (),
attributeClass)</code>
+ * is true.
+ *
+ * @param objects Collection of objects to filter. May contain
<code>null</code> references,
+ * but may not itself be <code>null</code>.
+ * @param attributeClass the class to filter based on.
*/
public static Collection getObjectsWithAttributeType (Collection objects, Class
attributeClass) {
+ if (objects == null) {
+ throw new NullPointerException ("objects");
+ }
+
+ if (attributeClass == null) {
+ throw new NullPointerException ("attributeClass");
+ }
+
ArrayList result = new ArrayList ();
Iterator iter = objects.iterator ();
while (iter.hasNext ()) {
Object object = iter.next ();
- Class clazz = object.getClass ();
- if (Attributes.hasAttributeType (clazz, attributeClass)) {
- result.add (object);
+ if (object != null) {
+ Class clazz = object.getClass ();
+ if (Attributes.hasAttributeType (clazz, attributeClass)) {
+ result.add (object);
+ }
}
}
1.11 +139 -56
jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/Attributes.java
Index: Attributes.java
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/Attributes.java,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- Attributes.java 19 Feb 2004 14:49:12 -0000 1.10
+++ Attributes.java 20 Mar 2004 00:47:21 -0000 1.11
@@ -30,6 +30,62 @@
/**
* API for accessing attributes.
+ *
+ * <h3>General Notes on Errors</h3>
+ *
+ * All Methods in this class may throw <code>RepositoryError</code> or subclasses
thereof.
+ * This Error is thrown if an attribute repository can not be loaded for some
Exceptional
+ * reason.
+ *
+ * <h4>Rationale for Errors instead of Exceptions</h4>
+ *
+ * The methods in this class throws <code>Error</code>s instead of
<code>Exception</code>s.
+ * This rationale behind this is that:
+ *
+ * <ul>
+ * <li>The programmer should not have to wrap all accesses to
+ * the Attributes API in a try/catch clause.
+ * <li>An Exception being thrown here is caused by missing classes
+ * or other "Error-like" conditions.
+ * </ul>
+ *
+ * <h3>Performance Notes</h3>
+ * 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 <b>runs in linear
+ * time in the number of attributes associated with the program element</b>, and
you should
+ * avoid accessing attributes in your innermost loops if you can avoid it. For
+ * example, instead of:
+ *
+ * <pre><code>
+ * Class myClass = ...;
+ * for (int i = 0; i < 10000; i++) {
+ * if (Attributes.hasAttributeType (myClass, MyAttribute.class)) {
+ * doThis(myClass);
+ * } else {
+ * doThat(myClass);
+ * }
+ * }
+ * </code></pre>
+ *
+ * do:
+ *
+ * <pre><code>
+ * Class myClass = ...;
+ * boolean shouldDoThis = Attributes.hasAttributeType (myClass, MyAttribute.class);
+ * for (int i = 0; i < 10000; i++) {
+ * if (shouldDoThis) {
+ * doThis(myClass);
+ * } else {
+ * doThat(myClass);
+ * }
+ * }
+ * </code></pre>
+ *
+ * if the loop should run at maximum speed.
*/
public class Attributes {
@@ -49,6 +105,10 @@
*/
private final static Map classRepositories = new WeakHashMap ();
+ /**
+ * List used to keep track of the initialization list in getCachedRepository.
+ * Since the method is synchronized static, we only need one list.
+ */
private static List initList = new ArrayList ();
private synchronized static CachedRepository getCachedRepository (Class clazz)
throws RepositoryError, CircularDependencyError {
@@ -64,28 +124,31 @@
}
} else {
// Indicate that we're loading it.
- initList.add (clazz.getName ());
- classRepositories.put (clazz, null);
+ CachedRepository cached = null;
- Class attributeRepo;
- CachedRepository cached;
+ initList.add (clazz.getName ());
try {
- attributeRepo = Class.forName (clazz.getName () +
"$__attributeRepository", true, clazz.getClassLoader ());
- AttributeRepositoryClass repo = (AttributeRepositoryClass)
attributeRepo.newInstance ();
+ classRepositories.put (clazz, null);
+
+ Class attributeRepo = null;
+ try {
+ attributeRepo = Class.forName (clazz.getName () +
"$__attributeRepository", true, clazz.getClassLoader ());
+ AttributeRepositoryClass repo = (AttributeRepositoryClass)
attributeRepo.newInstance ();
+
+ cached = new DefaultCachedRepository (clazz, repo);
+ } catch (ClassNotFoundException cnfe) {
+ cached = CachedRepository.EMPTY;
+ } catch (InstantiationException ie) {
+ throw new RepositoryError (ie);
+ } catch (IllegalAccessException iae) {
+ throw new RepositoryError (iae);
+ }
- cached = new DefaultCachedRepository (clazz, repo);
- } catch (ClassNotFoundException cnfe) {
- cached = CachedRepository.EMPTY;
- } catch (InstantiationException ie) {
- throw new RepositoryError (ie);
- } catch (IllegalAccessException iae) {
- throw new RepositoryError (iae);
+ classRepositories.put (clazz, cached);
+ } finally {
+ initList.remove (initList.size () - 1);
}
- classRepositories.put (clazz, cached);
-
- initList.remove (initList.size () - 1);
-
return cached;
}
}
@@ -121,7 +184,7 @@
* @throws MultipleAttributesError if the collection contains more than one
* instance of the specified class.
*/
- public static Object getAttribute (Class clazz, Class attributeClass) throws
MultipleAttributesError {
+ public static Object getAttribute (Class clazz, Class attributeClass) throws
RepositoryError, MultipleAttributesError {
return getAttribute (getAttributes (clazz), attributeClass);
}
@@ -132,7 +195,7 @@
* @throws MultipleAttributesError if the collection contains more than one
* instance of the specified class.
*/
- public static Object getAttribute (Field field, Class attributeClass) throws
MultipleAttributesError {
+ public static Object getAttribute (Field field, Class attributeClass) throws
RepositoryError, MultipleAttributesError {
return getAttribute (getAttributes (field), attributeClass);
}
@@ -143,7 +206,7 @@
* @throws MultipleAttributesError if the collection contains more than one
* instance of the specified class.
*/
- public static Object getAttribute (Constructor ctor, Class attributeClass)
throws MultipleAttributesError {
+ public static Object getAttribute (Constructor ctor, Class attributeClass)
throws RepositoryError, MultipleAttributesError {
return getAttribute (getAttributes (ctor), attributeClass);
}
@@ -154,7 +217,7 @@
* @throws MultipleAttributesError if the collection contains more than one
* instance of the specified class.
*/
- public static Object getAttribute (Method method, Class attributeClass) throws
MultipleAttributesError {
+ public static Object getAttribute (Method method, Class attributeClass) throws
RepositoryError, MultipleAttributesError {
return getAttribute (getAttributes (method), attributeClass);
}
@@ -165,7 +228,7 @@
* @throws MultipleAttributesError if the collection contains more than one
* instance of the specified class.
*/
- public static Object getParameterAttribute (Method method, int parameter, Class
attributeClass) throws MultipleAttributesError {
+ public static Object getParameterAttribute (Method method, int parameter, Class
attributeClass) throws RepositoryError, MultipleAttributesError {
return getAttribute (getParameterAttributes (method, parameter),
attributeClass);
}
@@ -176,7 +239,7 @@
* @throws MultipleAttributesError if the collection contains more than one
* instance of the specified class.
*/
- public static Object getParameterAttribute (Constructor constructor, int
parameter, Class attributeClass) throws MultipleAttributesError {
+ public static Object getParameterAttribute (Constructor constructor, int
parameter, Class attributeClass) throws RepositoryError, MultipleAttributesError {
return getAttribute (getParameterAttributes (constructor, parameter),
attributeClass);
}
@@ -187,56 +250,76 @@
* @throws MultipleAttributesError if the collection contains more than one
* instance of the specified class.
*/
- public static Object getReturnAttribute (Method method, Class attributeClass)
throws MultipleAttributesError {
+ public static Object getReturnAttribute (Method method, Class attributeClass)
throws RepositoryError, MultipleAttributesError {
return getAttribute (getReturnAttributes (method), attributeClass);
}
/**
* Gets all attributes for a class.
*/
- public static Collection getAttributes (Class clazz) {
+ public static Collection getAttributes (Class clazz) throws RepositoryError {
+ if (clazz == null) {
+ throw new NullPointerException ("clazz");
+ }
+
return getCachedRepository (clazz).getAttributes ();
}
/**
* Gets all attributes for a method.
*/
- public static Collection getAttributes (Method method) {
+ public static Collection getAttributes (Method method) throws RepositoryError {
+ if (method == null) {
+ throw new NullPointerException ("method");
+ }
+
return getCachedRepository (method.getDeclaringClass()).getAttributes
(method);
}
/**
* Gets all attributes for a parameter of a method.
*/
- public static Collection getParameterAttributes (Method method, int parameter) {
+ public static Collection getParameterAttributes (Method method, int parameter)
throws RepositoryError {
return getCachedRepository
(method.getDeclaringClass()).getParameterAttributes (method, parameter);
}
/**
* Gets all attributes for a parameter of a constructor.
*/
- public static Collection getParameterAttributes (Constructor constructor, int
parameter) {
+ public static Collection getParameterAttributes (Constructor constructor, int
parameter) throws RepositoryError {
+ if (constructor == null) {
+ throw new NullPointerException ("constructor");
+ }
return getCachedRepository
(constructor.getDeclaringClass()).getParameterAttributes (constructor, parameter);
}
/**
* Gets all attributes for the return value of a method.
*/
- public static Collection getReturnAttributes (Method method) {
+ public static Collection getReturnAttributes (Method method) throws
RepositoryError {
+ if (method == null) {
+ throw new NullPointerException ("method");
+ }
return getCachedRepository (method.getDeclaringClass()).getReturnAttributes
(method);
}
/**
* Gets all attributes for a field.
*/
- public static Collection getAttributes (Field field) {
+ public static Collection getAttributes (Field field) throws RepositoryError {
+ if (field == null) {
+ throw new NullPointerException ("field");
+ }
return getCachedRepository (field.getDeclaringClass()).getAttributes
(field);
}
/**
* Gets all attributes for a constructor.
*/
- public static Collection getAttributes (Constructor cons) {
+ public static Collection getAttributes (Constructor cons) throws
RepositoryError {
+ if (cons == null) {
+ throw new NullPointerException ("cons");
+ }
return getCachedRepository (cons.getDeclaringClass()).getAttributes (cons);
}
@@ -260,7 +343,7 @@
* Get all attributes of a given type from a class. For all objects o in the
returned
* collection, <code>o.getClass() == attributeClass</code>.
*/
- public static Collection getAttributes (Class clazz, Class attributeClass) {
+ public static Collection getAttributes (Class clazz, Class attributeClass)
throws RepositoryError {
return getAttributes (getAttributes (clazz), attributeClass);
}
@@ -268,7 +351,7 @@
* Get all attributes of a given type from a field. For all objects o in the
returned
* collection, <code>o.getClass() == attributeClass</code>.
*/
- public static Collection getAttributes (Field field, Class attributeClass) {
+ public static Collection getAttributes (Field field, Class attributeClass)
throws RepositoryError {
return getAttributes (getAttributes (field), attributeClass);
}
@@ -276,7 +359,7 @@
* Get all attributes of a given type from a constructor. For all objects o in
the returned
* collection, <code>o.getClass() == attributeClass</code>.
*/
- public static Collection getAttributes (Constructor ctor, Class attributeClass)
{
+ public static Collection getAttributes (Constructor ctor, Class attributeClass)
throws RepositoryError {
return getAttributes (getAttributes (ctor), attributeClass);
}
@@ -284,15 +367,15 @@
* Get all attributes of a given type from a method. For all objects o in the
returned
* collection, <code>o.getClass() == attributeClass</code>.
*/
- public static Collection getAttributes (Method method, Class attributeClass) {
+ public static Collection getAttributes (Method method, Class attributeClass)
throws RepositoryError {
return getAttributes (getAttributes (method), attributeClass);
}
-
+
/**
* Get all attributes of a given type from a method's parameter. For all
objects o in the returned
* collection, <code>o.getClass() == attributeClass</code>.
*/
- public static Collection getParameterAttributes (Method method, int parameter,
Class attributeClass) {
+ public static Collection getParameterAttributes (Method method, int parameter,
Class attributeClass) throws RepositoryError {
return getAttributes (getParameterAttributes (method, parameter),
attributeClass);
}
@@ -300,7 +383,7 @@
* Get all attributes of a given type from a method's parameter. For all
objects o in the returned
* collection, <code>o.getClass() == attributeClass</code>.
*/
- public static Collection getParameterAttributes (Constructor constructor, int
parameter, Class attributeClass) {
+ public static Collection getParameterAttributes (Constructor constructor, int
parameter, Class attributeClass) throws RepositoryError {
return getAttributes (getParameterAttributes (constructor, parameter),
attributeClass);
}
@@ -308,7 +391,7 @@
* Get all attributes of a given type from a method's return value. For all
objects o in the returned
* collection, <code>o.getClass() == attributeClass</code>.
*/
- public static Collection getReturnAttributes (Method method, Class
attributeClass) {
+ public static Collection getReturnAttributes (Method method, Class
attributeClass) throws RepositoryError {
return getAttributes (getReturnAttributes (method), attributeClass);
}
@@ -332,15 +415,15 @@
* Tests if a class has an attribute of a given type. That is, is there any
attribute
* <code>attr</code> such that <code>attr.getClass() == attributeClass</code>?
*/
- public static boolean hasAttributeType (Class clazz, Class attributeClass) {
+ public static boolean hasAttributeType (Class clazz, Class attributeClass)
throws RepositoryError {
return hasAttributeType (getAttributes (clazz), attributeClass);
}
-
+
/**
* Tests if a field has an attribute of a given type. That is, is there any
attribute
* <code>attr</code> such that <code>attr.getClass() == attributeClass</code>?
*/
- public static boolean hasAttributeType (Field field, Class attributeClass) {
+ public static boolean hasAttributeType (Field field, Class attributeClass)
throws RepositoryError {
return hasAttributeType (getAttributes (field), attributeClass);
}
@@ -348,7 +431,7 @@
* Tests if a constructor has an attribute of a given type. That is, is there
any attribute
* <code>attr</code> such that <code>attr.getClass() == attributeClass</code>?
*/
- public static boolean hasAttributeType (Constructor ctor, Class attributeClass)
{
+ public static boolean hasAttributeType (Constructor ctor, Class attributeClass)
throws RepositoryError {
return hasAttributeType (getAttributes (ctor), attributeClass);
}
@@ -356,7 +439,7 @@
* Tests if a method has an attribute of a given type. That is, is there any
attribute
* <code>attr</code> such that <code>attr.getClass() == attributeClass</code>?
*/
- public static boolean hasAttributeType (Method method, Class attributeClass) {
+ public static boolean hasAttributeType (Method method, Class attributeClass)
throws RepositoryError {
return hasAttributeType (getAttributes (method), attributeClass);
}
@@ -364,15 +447,15 @@
* Tests if a method's parameter has an attribute of a given type. That is, is
there any attribute
* <code>attr</code> such that <code>attr.getClass() == attributeClass</code>?
*/
- public static boolean hasParameterAttributeType (Method method, int parameter,
Class attributeClass) {
+ public static boolean hasParameterAttributeType (Method method, int parameter,
Class attributeClass) throws RepositoryError {
return hasAttributeType (getParameterAttributes (method, parameter),
attributeClass);
}
-
+
/**
* Tests if a constructor's parameter has an attribute of a given type. That
is, is there any attribute
* <code>attr</code> such that <code>attr.getClass() == attributeClass</code>?
*/
- public static boolean hasParameterAttributeType (Constructor constructor, int
parameter, Class attributeClass) {
+ public static boolean hasParameterAttributeType (Constructor constructor, int
parameter, Class attributeClass) throws RepositoryError {
return hasAttributeType (getParameterAttributes (constructor, parameter),
attributeClass);
}
@@ -380,7 +463,7 @@
* Tests if a method's return value has an attribute of a given type. That is,
is there any attribute
* <code>attr</code> such that <code>attr.getClass() == attributeClass</code>?
*/
- public static boolean hasReturnAttributeType (Method method, Class
attributeClass) {
+ public static boolean hasReturnAttributeType (Method method, Class
attributeClass) throws RepositoryError {
return hasAttributeType (getReturnAttributes (method), attributeClass);
}
@@ -388,7 +471,7 @@
* Convenience function to test whether a collection of attributes contain
* an attribute.
*/
- private static boolean hasAttribute (Collection attrs, Object attribute) {
+ private static boolean hasAttribute (Collection attrs, Object attribute) throws
RepositoryError {
return attrs.contains (attribute);
}
@@ -396,7 +479,7 @@
* Tests if a class has an attribute. That is, is there any attribute
* <code>attr</code> such that <code>attr.equals(attribute)</code>?
*/
- public static boolean hasAttribute (Class clazz, Object attribute) {
+ public static boolean hasAttribute (Class clazz, Object attribute) throws
RepositoryError {
return hasAttribute (getAttributes (clazz), attribute);
}
@@ -404,7 +487,7 @@
* Tests if a field has an attribute. That is, is there any attribute
* <code>attr</code> such that <code>attr.equals(attribute)</code>?
*/
- public static boolean hasAttribute (Field field, Object attribute) {
+ public static boolean hasAttribute (Field field, Object attribute) throws
RepositoryError {
return hasAttribute (getAttributes (field), attribute);
}
@@ -412,7 +495,7 @@
* Tests if a constructor has an attribute. That is, is there any attribute
* <code>attr</code> such that <code>attr.equals(attribute)</code>?
*/
- public static boolean hasAttribute (Constructor ctor, Object attribute) {
+ public static boolean hasAttribute (Constructor ctor, Object attribute) throws
RepositoryError {
return hasAttribute (getAttributes (ctor), attribute);
}
@@ -420,7 +503,7 @@
* Tests if a method has an attribute. That is, is there any attribute
* <code>attr</code> such that <code>attr.equals(attribute)</code>?
*/
- public static boolean hasAttribute (Method method, Object attribute) {
+ public static boolean hasAttribute (Method method, Object attribute) throws
RepositoryError {
return hasAttribute (getAttributes (method), attribute);
}
@@ -428,7 +511,7 @@
* Tests if a method's parameter has an attribute. That is, is there any
attribute
* <code>attr</code> such that <code>attr.equals(attribute)</code>?
*/
- public static boolean hasParameterAttribute (Method method, int parameter,
Object attribute) {
+ public static boolean hasParameterAttribute (Method method, int parameter,
Object attribute) throws RepositoryError {
return hasAttribute (getParameterAttributes (method, parameter), attribute);
}
@@ -436,7 +519,7 @@
* Tests if a constructor's parameter has an attribute. That is, is there any
attribute
* <code>attr</code> such that <code>attr.equals(attribute)</code>?
*/
- public static boolean hasParameterAttribute (Constructor constructor, int
parameter, Object attribute) {
+ public static boolean hasParameterAttribute (Constructor constructor, int
parameter, Object attribute) throws RepositoryError {
return hasAttribute (getParameterAttributes (constructor, parameter),
attribute);
}
@@ -444,7 +527,7 @@
* Tests if a method's return value has an attribute. That is, is there any
attribute
* <code>attr</code> such that <code>attr.equals(attribute)</code>?
*/
- public static boolean hasReturnAttribute (Method method, Object attribute) {
+ public static boolean hasReturnAttribute (Method method, Object attribute)
throws RepositoryError {
return hasAttribute (getReturnAttributes (method), attribute);
}
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
