commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From leosu...@apache.org
Subject cvs commit: jakarta-commons-sandbox/attributes/compiler/src/java/org/apache/commons/attributes/validation AttributeValidator.java AttributeValidatorTask.java
Date Tue, 08 Jun 2004 20:29:01 GMT
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 {@link 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 ({@link 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 ({@link 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 {@link Sealable} interface. Subclasses should call
  + * {@link #checkSealed()} before setting any bean properties.
    */
   public class DefaultSealable implements Sealable {
       
       /**
  -     * Boolean flag indicating whether the seal() method
  +     * Boolean flag indicating whether the {@link 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 {@link #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.
  +     * {@link #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 {@link 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 {@link 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 {@link 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 {@link 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 {@link #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 {@link 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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message