You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by le...@apache.org on 2004/05/08 22:37:23 UTC
cvs commit: jakarta-commons-sandbox/attributes/site/xdocs index.xml validator.xml
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>
* <taskdef resource="org/apache/commons/attributes/anttasks.properties"/>
*
- * <attribute-indexer jarFile="myclasses.jar">
+ * <attribute-validator jarFile="myclasses.jar">
* <classpath>
* ...
* </classpath>
- * </attribute-indexer>
+ * <validator class="my.Validator"/>
+ * <validator class="my.other.Validator"/>
+ * </attribute-validator>
* </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