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/site/xdocs index.xml validator.xml
Date Sat, 08 May 2004 20:37:23 GMT
leosutic    2004/05/08 13:37:23

  Modified:    attributes maven.xml project.xml
               attributes/api project.xml
               attributes/compiler project.xml
               attributes/compiler/src/java/org/apache/commons/attributes/validation
                        AttributeValidator.java AttributeValidatorTask.java
                        ValidationException.java
               attributes/site/xdocs index.xml validator.xml
  Log:
  Improved documentation of the attribute validation package.
  
  Revision  Changes    Path
  1.14      +2 -1      jakarta-commons-sandbox/attributes/maven.xml
  
  Index: maven.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/attributes/maven.xml,v
  retrieving revision 1.13
  retrieving revision 1.14
  diff -u -r1.13 -r1.14
  --- maven.xml	6 May 2004 04:01:52 -0000	1.13
  +++ maven.xml	8 May 2004 20:37:22 -0000	1.14
  @@ -174,13 +174,14 @@
               noindex="false" author="true" use="true"
               windowtitle="${title}" 
               bottom="${copyright}"
  -            additionalparam="-breakiterator -J-Xmx128m "
  +            additionalparam="-J-Xmx128m "
               packagenames="*,org.*"
               overview="${basedir}/../api/src/java/overview.html">
               <j:forEach var="packageGroup" items="${pom.packageGroups}">
                   <group title="${packageGroup.title}" packages="${packageGroup.packages}"/>
               </j:forEach>
               <sourcepath path="${basedir}/../api/src/java"/>
  +            <sourcepath path="${basedir}/../compiler/src/java"/>
               <classpath>
                   <path refid="maven.dependency.classpath"/>
               </classpath>
  
  
  
  1.16      +11 -0     jakarta-commons-sandbox/attributes/project.xml
  
  Index: project.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/attributes/project.xml,v
  retrieving revision 1.15
  retrieving revision 1.16
  diff -u -r1.15 -r1.16
  --- project.xml	5 May 2004 21:51:58 -0000	1.15
  +++ project.xml	8 May 2004 20:37:22 -0000	1.16
  @@ -165,4 +165,15 @@
           <jars></jars>
       </build>
       
  +    <packageGroups>
  +        <packageGroup>
  +            <title>Runtime API</title>
  +            <packages>org.apache.commons.attributes</packages>
  +        </packageGroup>
  +        <packageGroup>
  +            <title>Compiler and Tools</title>
  +            <packages>org.apache.commons.attributes.compiler,org.apache.commons.attributes.javadoc,org.apache.commons.attributes.validation</packages>
  +        </packageGroup>
  +    </packageGroups>
  +    
   </project>
  
  
  
  1.6       +0 -7      jakarta-commons-sandbox/attributes/api/project.xml
  
  Index: project.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/attributes/api/project.xml,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- project.xml	21 Mar 2004 00:03:55 -0000	1.5
  +++ project.xml	8 May 2004 20:37:22 -0000	1.6
  @@ -51,11 +51,4 @@
           </dependency>
       </dependencies>
       
  -    <packageGroups>
  -        <packageGroup>
  -            <title>Application Program Interface (API)</title>
  -            <packages>org.apache.commons.attributes</packages>
  -        </packageGroup>
  -    </packageGroups>
  -    
   </project>
  
  
  
  1.8       +0 -7      jakarta-commons-sandbox/attributes/compiler/project.xml
  
  Index: project.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/attributes/compiler/project.xml,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- project.xml	5 May 2004 12:21:16 -0000	1.7
  +++ project.xml	8 May 2004 20:37:22 -0000	1.8
  @@ -60,11 +60,4 @@
           </dependency>
       </dependencies>
       
  -    <packageGroups>
  -        <packageGroup>
  -            <title>Compiler</title>
  -            <packages>org.apache.commons.attributes.compiler</packages>
  -        </packageGroup>
  -    </packageGroups>
  -    
   </project>
  
  
  
  1.2       +12 -0     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.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- AttributeValidator.java	5 May 2004 14:45:29 -0000	1.1
  +++ AttributeValidator.java	8 May 2004 20:37:22 -0000	1.2
  @@ -17,6 +17,18 @@
   
   import java.util.Set;
   
  +/**
  + * Validates that a set of classes have the correct attributes
  + * attached to them.
  + */
   public interface AttributeValidator {
  +    
  +    /**
  +     * Validates a set of classes.
  +     *
  +     * @param classes the classes to validate.
  +     * @throws ValidationException if one or more classes have
  +     *         an invalid set of attributes.
  +     */
       public void validate (Set classes) throws ValidationException;
   }
  
  
  
  1.2       +7 -8      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.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- AttributeValidatorTask.java	5 May 2004 14:45:29 -0000	1.1
  +++ AttributeValidatorTask.java	8 May 2004 20:37:22 -0000	1.2
  @@ -46,21 +46,21 @@
   import org.apache.tools.ant.types.Path;
   
   /**
  - * Ant task to compile attribute indexes. Usage:
  + * Ant task that validates attributes. Usage:
    *
    * <pre><code>
    *     &lt;taskdef resource="org/apache/commons/attributes/anttasks.properties"/&gt;
    *     
  - *     &lt;attribute-indexer jarFile="myclasses.jar"&gt;
  + *     &lt;attribute-validator jarFile="myclasses.jar"&gt;
    *         &lt;classpath&gt;
    *             ...
    *         &lt;/classpath&gt;
  - *     &lt;/attribute-indexer&gt;
  + *         &lt;validator class="my.Validator"/&gt;
  + *         &lt;validator class="my.other.Validator"/&gt;
  + *     &lt;/attribute-validator&gt;
    * </code></pre>
    *
  - * The task will inspect the classes in the given jar and add a <tt>META-INF/attrs.index</tt>
  - * file to it, which contains the index information. The classpath element is required
and
  - * must contain all dependencies for the attributes used.
  + * The task will run the validator(s) with the classes the given jar file.
    */
   public class AttributeValidatorTask extends Task {
       
  @@ -158,7 +158,6 @@
                   jar.close ();
               }
               
  -            
               AntClassLoader cl = new AntClassLoader (this.getClass ().getClassLoader (),
project, classPath, true);   
               try {
                   cl.addPathElement (jarFile.getPath ()); 
  @@ -181,7 +180,7 @@
                       try {
                           attrValidator.validate (classesToValidate);
                       } catch (ValidationException ve) {
  -                        throw new BuildException (ve.getMessage ());
  +                        throw new BuildException (ve.getInvalidClass () + " failed to validate:
" + ve.getMessage ());
                       }
                   }
               } finally {
  
  
  
  1.2       +24 -1     jakarta-commons-sandbox/attributes/compiler/src/java/org/apache/commons/attributes/validation/ValidationException.java
  
  Index: ValidationException.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/attributes/compiler/src/java/org/apache/commons/attributes/validation/ValidationException.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- ValidationException.java	5 May 2004 14:45:29 -0000	1.1
  +++ ValidationException.java	8 May 2004 20:37:22 -0000	1.2
  @@ -15,8 +15,31 @@
    */
   package org.apache.commons.attributes.validation;
   
  +/**
  + * Thrown by {@link AttributeValidator}s when an invalid set of
  + * attributes are detected.
  + */
   public class ValidationException extends Exception {
  -    public ValidationException (String message) {
  +    
  +    private final Class invalidClass;
  +    
  +    /**
  +     * Creates a new ValidationException.
  +     *
  +     * @param invalidClass the class whose attributes are
  +     *                     invalid.
  +     * @param message a message describing why the attributes are invalid.
  +     */
  +    public ValidationException (Class invalidClass, String message) {
           super (message);
  +        this.invalidClass = invalidClass;
  +    }
  +    
  +    /**
  +     * Returns the class that triggered the ValidationExeption to
  +     * be thrown.
  +     */
  +    public Class getInvalidClass () {
  +        return invalidClass;
       }
   }
  
  
  
  1.12      +1 -1      jakarta-commons-sandbox/attributes/site/xdocs/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/attributes/site/xdocs/index.xml,v
  retrieving revision 1.11
  retrieving revision 1.12
  diff -u -r1.11 -r1.12
  --- index.xml	5 May 2004 12:23:23 -0000	1.11
  +++ index.xml	8 May 2004 20:37:22 -0000	1.12
  @@ -30,7 +30,7 @@
                   Commons Attributes enables Java programmers to use C#/.Net-style
                   attributes in their code.
               
  -                Please see the Javadoc overview for a thorough explanation of the features
  +                Please see the tutorial and reference thorough explanation of the features
                   and how the project integrates into the development process.
               </p>
           </section>
  
  
  
  1.2       +149 -0    jakarta-commons-sandbox/attributes/site/xdocs/validator.xml
  
  Index: validator.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/attributes/site/xdocs/validator.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- validator.xml	5 May 2004 21:27:00 -0000	1.1
  +++ validator.xml	8 May 2004 20:37:23 -0000	1.2
  @@ -26,14 +26,163 @@
       <body>
           <section name="Why?">
               
  +            <p>
  +                In many cases an attribute can only be applied to certain elements,
  +                and its parameters must satisfy some set of constraints. For example,
  +                suppose we have an attribute that declares transaction metadata:
  +            </p>
  +            
  +            <source><![CDATA[/**
  + * @@TransactionDeclaration (TransactionDeclaration.EXPLICIT)
  + */]]></source>
  +            
  +            <p>
  +                Now, the rule is that if a class has a <tt>TransactionDeclaration.EXPLICIT</tt>
  +                setting, then <b>all</b> methods must have a <tt>@@TransactionLevel</tt>
attribute.
  +                For example, this class is valid:
  +            </p>
  +            
  +            <source><![CDATA[/**
  + * @@TransactionDeclaration(TransactionDeclaration.EXPLICIT)
  + */
  +class ValidClass {
  +
  +    /**
  +     * @@TransactionLevel(TransactionLevel.SERIALIZABLE)
  +     */
  +    void methodOne() { ... }
  +
  +    /**
  +     * @@TransactionLevel(TransactionLevel.READ_UNCOMMITTED)
  +     */
  +    void methodTwo() { ... }
  +
  +}]]></source>
  +            
  +            <p>While this one is not, since <tt>methodTwo</tt> does not
define a <tt>@@TransactionLevel</tt>.</p>
  +            
  +            <source><![CDATA[/**
  + * @@TransactionDeclaration(TransactionDeclaration.EXPLICIT)
  + */
  +class ValidClass {
  +
  +    /**
  +     * @@TransactionLevel(TransactionLevel.SERIALIZABLE)
  +     */
  +    void methodOne() { ... }
  +
  +    void methodTwo() { ... }
  +
  +}]]></source>
  +            
  +            <p>
  +                The attribute-validator task enables you to check the consistency of 
  +                attributes at compile-time.
  +            </p>
  +            
           </section>
           
           <section name="The attribute-validator Task">
  +            <p>
  +                The attribute-validator task is run like this from your Ant file:
  +            </p>
  +            
  +            <source><![CDATA[<attribute-validator jarFile="myclasses.jar">
  +    <classpath>
  +        ...
  +    </classpath>
  +    <validator class="my.Validator"/>
  +    <validator class="my.other.Validator"/>
  +</attribute-validator>]]></source>
  +            
  +            <table>
  +                <tr>
  +                    <th>
  +                        Parameter
  +                    </th>
  +                    <th>
  +                        Required
  +                    </th>
  +                    <th>
  +                        Description
  +                    </th>
  +                </tr>
  +                <tr>
  +                    <td>
  +                        jarFile
  +                    </td>
  +                    <td>
  +                        yes
  +                    </td>
  +                    <td>
  +                        The jar file whose classes should be validated.
  +                    </td>
  +                </tr>
  +            </table>
  +            
  +            <table>
  +                <tr>
  +                    <th>
  +                        Element
  +                    </th>
  +                    <th>
  +                        Required
  +                    </th>
  +                    <th>
  +                        Description
  +                    </th>
  +                </tr>
  +                <tr>
  +                    <td>
  +                        classpath
  +                    </td>
  +                    <td>
  +                        yes
  +                    </td>
  +                    <td>
  +                        The classpath to use when loading classes from the jar file.
  +                    </td>
  +                </tr>
  +                <tr>
  +                    <td>
  +                        validator
  +                    </td>
  +                    <td>
  +                        yes
  +                    </td>
  +                    <td>
  +                        One or more validators, which are classes implementing the
  +                        <a href="api/org/apache/commons/attributes/validation/AttributeValidator.html">AttributeValidator</a>
  +                        interface.
  +                    </td>
  +                </tr>
  +            </table>
               
           </section>
           
           <section name="Writing Your Own Validation Rules">
  +            <p>
  +                Writing a validation rule simply means implementing the 
  +                <a href="api/org/apache/commons/attributes/validation/AttributeValidator.html">AttributeValidator</a>
  +                interface in a class. For example, this AttributeValidator will check that
there
  +                are no more than three class attributes given to each class.
  +            </p>
               
  +            <source><![CDATA[public class MyValidator 
  +    implements AttributeValidator {
  +
  +    public void validate (Set classes) throws ValidationException {
  +        Iterator iter = classes.iterator ();
  +        while (iter.hasNext ()) {
  +            Class clazz = (Class) iter.next ();
  +            if (Attributes.getAttributes (clazz).size () > 3) {
  +                throw new ValidationException (clazz, 
  +                    "Classes must have at most three attributes!");
  +            }
  +        }
  +    }
  +
  +}]]></source>
           </section>
       </body>
       
  
  
  

---------------------------------------------------------------------
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