leosutic 2004/06/08 13:29:01
Modified: attributes/api/src/java/org/apache/commons/attributes
AttributeIndex.java DefaultSealable.java
Indexed.java Inheritable.java
InvalidAttributeTargetError.java
MultipleAttributesError.java Sealable.java
Target.java
attributes/compiler/src/java/org/apache/commons/attributes/validation
AttributeValidator.java AttributeValidatorTask.java
Log:
Improved Javadocs.
Revision Changes Path
1.8 +38 -7
jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/AttributeIndex.java
Index: AttributeIndex.java
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/AttributeIndex.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- AttributeIndex.java 21 Mar 2004 00:04:15 -0000 1.7
+++ AttributeIndex.java 8 Jun 2004 20:29:00 -0000 1.8
@@ -34,20 +34,25 @@
/**
* An index providing a list of elements with given attributes. This
- * requires that the attribute is <code>Indexed</code> and that the
+ * requires that the attribute is [EMAIL PROTECTED] Indexed} and that the
* attribute indexer tool has been run on the jar file containing the
* classes.
*/
public class AttributeIndex {
/**
- * A method parameter.
+ * Reference to a method parameter. A method parameter
+ * is defined by the Method object it is defined in, and the index
+ * of the parameter in the method's parameter list.
*/
public static class MethodParameter {
private final Method method;
private final int index;
+ /**
+ * Constructs a new MethodParameter.
+ */
public MethodParameter (Method method, int index) {
this.method = method;
this.index = index;
@@ -67,29 +72,45 @@
return index;
}
+ /**
+ * Compares two <code>MethodParameter</code>s for equality.
+ * They must point to the same method and have the same index.
+ */
public boolean equals (Object o) {
- return o instanceof MethodParameter &&
+ return o != null && o instanceof MethodParameter &&
method.equals (((MethodParameter) o).method) &&
index == ((MethodParameter) o).index;
}
+ /**
+ * Computes the hashCode.
+ */
public int hashCode () {
return method.hashCode () + index;
}
+ /**
+ * Converts this method parameter into a human-readable string.
+ */
public String toString () {
return method.toString () + ":" + index;
}
}
/**
- * A constructor parameter.
+ * A constructor parameter. A method parameter
+ * is defined by the Method object it is defined in, and the index
+ * of the parameter in the method's parameter list.
*/
public static class ConstructorParameter {
private final Constructor ctor;
private final int index;
+
+ /**
+ * Constructs a new ConstructorParameter.
+ */
public ConstructorParameter (Constructor ctor, int index) {
this.ctor = ctor;
this.index = index;
@@ -109,16 +130,26 @@
return index;
}
+ /**
+ * Compares two <code>ConstructorParameter</code>s for equality.
+ * They must point to the same constructor and have the same index.
+ */
public boolean equals (Object o) {
- return o instanceof ConstructorParameter &&
+ return o != null && o instanceof ConstructorParameter &&
ctor.equals (((ConstructorParameter) o).ctor) &&
index == ((ConstructorParameter) o).index;
}
+ /**
+ * Computes the hashCode.
+ */
public int hashCode () {
return ctor.hashCode () + index;
}
+ /**
+ * Converts this constructor parameter into a human-readable string.
+ */
public String toString () {
return ctor.toString () + ":" + index;
}
@@ -400,7 +431,7 @@
/**
* Gets a Collection of the <code>ConstructorParameter</code>s that have an
attribute of the specified class.
- * The Collection contains the methods (AttributeIndex.ConstructorParameter).
+ * The Collection contains the methods ([EMAIL PROTECTED]
AttributeIndex.ConstructorParameter}).
*/
public Collection getConstructorParameters (Class attributeClass) {
if (index.containsKey (attributeClass.getName ())) {
@@ -412,7 +443,7 @@
/**
* Gets a Collection of the <code>MethodParameter</code>s that have an
attribute of the specified class.
- * The Collection contains the methods (AttributeIndex.MethodParameter).
+ * The Collection contains the methods ([EMAIL PROTECTED]
AttributeIndex.MethodParameter}).
*/
public Collection getMethodParameters (Class attributeClass) {
if (index.containsKey (attributeClass.getName ())) {
1.4 +8 -5
jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/DefaultSealable.java
Index: DefaultSealable.java
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/DefaultSealable.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- DefaultSealable.java 19 Feb 2004 14:49:13 -0000 1.3
+++ DefaultSealable.java 8 Jun 2004 20:29:00 -0000 1.4
@@ -16,13 +16,13 @@
package org.apache.commons.attributes;
/**
- * Implementation of the Sealable interface. Subclasses should call
- * checkSealed() before setting any bean properties.
+ * Implementation of the [EMAIL PROTECTED] Sealable} interface. Subclasses should
call
+ * [EMAIL PROTECTED] #checkSealed()} before setting any bean properties.
*/
public class DefaultSealable implements Sealable {
/**
- * Boolean flag indicating whether the seal() method
+ * Boolean flag indicating whether the [EMAIL PROTECTED] seal()} method
* has been called.
*/
private boolean sealed = false;
@@ -31,8 +31,10 @@
}
/**
- * Checks if the <code>seal()</code> method has been called and throws a
+ * Checks if the [EMAIL PROTECTED] #seal()} method has been called and throws a
* <code>IllegalStateException</code> if it has.
+ *
+ * @throws IllegalStateException if this attribute has been sealed.
*/
protected void checkSealed () throws IllegalStateException {
if (sealed) {
@@ -42,7 +44,8 @@
/**
* Seals this attribute. Any future calls to the
- * checkSealed method will result in an exception being thrown.
+ * [EMAIL PROTECTED] #checkSealed()} method will result in an
+ * <code>IllegalStateException</code> being thrown.
*/
public void seal () {
this.sealed = true;
1.9 +3 -3
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.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- Indexed.java 5 May 2004 14:45:29 -0000 1.8
+++ Indexed.java 8 Jun 2004 20:29:00 -0000 1.9
@@ -17,14 +17,14 @@
/**
* This attribute is used to mark attributes as being indexed.
- * Elements with indexed attributes can be found via an AttributeIndex,
+ * Elements with indexed attributes can be found via an [EMAIL PROTECTED]
AttributeIndex},
* but incur a slight processing and memory penalty. You must also
* run the attribute-indexer tool on the Jar-file containing the classes
* you wish to find via the index.
*
* <p><b>Note:</b> Indexed attributes that are inherited will not be found
- * via an AttributeIndex. You will only find the class/method/field where
- * the attribute is first declared via the index.
+ * via an [EMAIL PROTECTED] AttributeIndex}. You will only find the
class/method/field where
+ * the attribute is declared via the index.
*/
public class Indexed {
}
1.7 +1 -2
jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/Inheritable.java
Index: Inheritable.java
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/Inheritable.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- Inheritable.java 19 Feb 2004 14:49:13 -0000 1.6
+++ Inheritable.java 8 Jun 2004 20:29:00 -0000 1.7
@@ -18,8 +18,7 @@
/**
* This attribute is used to mark attributes as being inheritable.
* Inheritable attributes are inherited down the class and interface
- * hierarchy. See Dependency in the unit tests for an example of an
- * inheritable attribute.
+ * hierarchy.
*/
public class Inheritable {
}
1.4 +20 -2
jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/InvalidAttributeTargetError.java
Index: InvalidAttributeTargetError.java
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/InvalidAttributeTargetError.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- InvalidAttributeTargetError.java 9 May 2004 18:24:57 -0000 1.3
+++ InvalidAttributeTargetError.java 8 Jun 2004 20:29:00 -0000 1.4
@@ -19,8 +19,26 @@
import java.util.List;
/**
- * Thrown when one of the Attributes.getAttribute methods find more
- * than one instance of the specified attribute class.
+ * Thrown when an attribute has a [EMAIL PROTECTED] Target} declaration that forbids
+ * it being applied to the program element it has been applied to.
+ *
+ * <p>For example:
+ *
+ * <pre><code>
+ * / **
+ * * This attribute can only be applied to Classes.
+ * * @@Target(Target.CLASS)
+ * * /
+ * public class MyAttribute {}
+ *
+ * public class MyClass {
+ * / **
+ * * Error: Can't apply MyAttribute to a field!
+ * * @@MyAttribute()
+ * * /
+ * private String myField;
+ * }
+ * </code></pre>
*/
public class InvalidAttributeTargetError extends Error {
1.4 +1 -1
jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/MultipleAttributesError.java
Index: MultipleAttributesError.java
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/MultipleAttributesError.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- MultipleAttributesError.java 19 Feb 2004 14:49:13 -0000 1.3
+++ MultipleAttributesError.java 8 Jun 2004 20:29:00 -0000 1.4
@@ -16,7 +16,7 @@
package org.apache.commons.attributes;
/**
- * Thrown when one of the Attributes.getAttribute methods find more
+ * Thrown when one of the [EMAIL PROTECTED] Attributes}.getAttribute methods find
more
* than one instance of the specified attribute class.
*/
public class MultipleAttributesError extends Error {
1.4 +3 -1
jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/Sealable.java
Index: Sealable.java
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/Sealable.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Sealable.java 19 Feb 2004 14:49:13 -0000 1.3
+++ Sealable.java 8 Jun 2004 20:29:00 -0000 1.4
@@ -27,7 +27,9 @@
* This alone poses a security risk, as a client can call setters on an attribute
as well,
* and thus make class attributes mutable. In order to notify the attribute class
that construction
* and initialization is completed, the attribute runtime system will test if it
implements Sealable,
- * and of so, invoke seal() on the attribute instance.
+ * and of so, invoke [EMAIL PROTECTED] #seal()} on the attribute instance.
+ *
+ * @see DefaultSealable
*/
public interface Sealable {
/**
1.2 +11 -1
jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/Target.java
Index: Target.java
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes/Target.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Target.java 9 May 2004 13:57:10 -0000 1.1
+++ Target.java 8 Jun 2004 20:29:00 -0000 1.2
@@ -1,10 +1,12 @@
package org.apache.commons.attributes;
/**
- * Attribute idicating what elements an attribute may be applied to.
+ * Attribute indicating what elements an attribute may be applied to.
* This is checked at runtime. If the attribute is absent, it defaults
* to Target.ALL.
*
+ * <p>This attribute is intended to be used with attribute classes:
+ *
* <pre><code>
* / **
* * MyAttribute can only be applied to classes and fields, not methods.
@@ -63,10 +65,18 @@
private final int flags;
+ /**
+ * Creates a new target attribute.
+ *
+ * @param flags a bitwise or of flags indicating the allowed targets.
+ */
public Target (int flags) {
this.flags = flags;
}
+ /**
+ * Returns an int that is the bitwise or of the allowed target flags.
+ */
public int getFlags () {
return flags;
}
1.3 +2 -1
jakarta-commons-sandbox/attributes/compiler/src/java/org/apache/commons/attributes/validation/AttributeValidator.java
Index: AttributeValidator.java
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/attributes/compiler/src/java/org/apache/commons/attributes/validation/AttributeValidator.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- AttributeValidator.java 8 May 2004 20:37:22 -0000 1.2
+++ AttributeValidator.java 8 Jun 2004 20:29:01 -0000 1.3
@@ -19,7 +19,8 @@
/**
* Validates that a set of classes have the correct attributes
- * attached to them.
+ * attached to them. This interface must be implemented by the
+ * validation rules given to the [EMAIL PROTECTED] AttributeValidatorTask}.
*/
public interface AttributeValidator {
1.3 +0 -1
jakarta-commons-sandbox/attributes/compiler/src/java/org/apache/commons/attributes/validation/AttributeValidatorTask.java
Index: AttributeValidatorTask.java
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/attributes/compiler/src/java/org/apache/commons/attributes/validation/AttributeValidatorTask.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- AttributeValidatorTask.java 8 May 2004 20:37:22 -0000 1.2
+++ AttributeValidatorTask.java 8 Jun 2004 20:29:01 -0000 1.3
@@ -174,7 +174,6 @@
Iterator iter = validators.iterator ();
while (iter.hasNext ()) {
Validator validator = (Validator) iter.next ();
- System.out.println ("Validating with " + validator.getClassName
());
Class validatorClass = cl.loadClass (validator.getClassName ());
AttributeValidator attrValidator = (AttributeValidator)
validatorClass.newInstance ();
try {
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
