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/05 16:45:29 UTC
cvs commit: jakarta-commons-sandbox/attributes/api/src/java/org/apache/commons/attributes Indexed.java
leosutic 2004/05/05 07:45:29
Modified: attributes/site/xdocs ant_demo.xml navigation.xml
reference.xml
attributes/site/etc/ant_demo build.xml
attributes/compiler/src/java/org/apache/commons/attributes/compiler
AttributeIndexer.java
attributes/compiler/src/java/org/apache/commons/attributes
anttasks.properties
attributes/api/src/java/org/apache/commons/attributes
Indexed.java
Added: attributes/compiler/src/java/org/apache/commons/attributes/validation
AttributeValidator.java AttributeValidatorTask.java
ValidationException.java
Log:
Added support for compile-time validation of attributes and speeded
up indexing by eliminating extra classloading.
Revision Changes Path
1.4 +58 -3 jakarta-commons-sandbox/attributes/site/xdocs/ant_demo.xml
Index: ant_demo.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/attributes/site/xdocs/ant_demo.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ant_demo.xml 5 May 2004 12:23:40 -0000 1.3
+++ ant_demo.xml 5 May 2004 14:45:29 -0000 1.4
@@ -50,6 +50,9 @@
</li>
<li>
<p>Ant task: <a href="http://cvs.apache.org/~leosutic/commons-attributes-compiler-SNAPSHOT.jar">commons-attributes-compiler-SNAPSHOT.jar</a></p>
+ <p>
+ <i>It is important that you do not rename this file - it is referred to by name in the example build.xml.</i>
+ </p>
</li>
<li>
<p>Commons Collections 2.1: <a href="http://www.ibiblio.org/maven/commons-collections/jars/commons-collections-2.1.jar">commons-collections-2.1.jar</a></p>
@@ -100,6 +103,39 @@
BUILD SUCCESSFUL
Total time: 7 seconds]]></source>
+ <p>
+ If you have JDK 1.4 or later, you can also generate Javadocs for the demo
+ with attribute information in the docs:
+ </p>
+
+ <source><![CDATA[# ant javadoc
+Buildfile: build.xml
+
+javadoc:
+ [javadoc] Generating Javadoc
+ [javadoc] Javadoc execution
+ [javadoc] Loading source file /home/leosutic/demo/AttributeDemo.java...
+ [javadoc] Constructing Javadoc information...
+ [javadoc] /home/leosutic/demo/AttributeDemo.java:18:
+ package org.apache.commons.attributes does not exist
+ [javadoc] import org.apache.commons.attributes.Attributes;
+ [javadoc] ^
+ [javadoc] Registered Taglet org.apache.commons.attributes.javadoc.CATaglet ...
+
+ [javadoc] Standard Doclet version 1.4.0
+
+ [javadoc] Building tree for all the packages and classes...
+ [javadoc] Building index for all the packages and classes...
+ [javadoc] Building index for all classes...
+ [javadoc] Generating /home/leosutic/demo/javadoc/stylesheet.css...
+ [javadoc] 1 warning
+
+BUILD SUCCESSFUL
+Total time: 7 seconds]]></source>
+
+ <p>
+ Look in the javadoc/ subdirectory for the results.
+ </p>
</section>
<section name="Demo Walkthrough">
@@ -242,12 +278,31 @@
<source><![CDATA[ <target name="run" description="o Compile and run the demo" depends="compile">
<java
- classpath="${ant.home}/lib/commons-attributes-api-SNAPSHOT.jar;."
- classname="AttributeDemo"/>
+ classpath="${ant.home}/lib/commons-attributes-api-SNAPSHOT.jar;."
+ classname="AttributeDemo"/>
+ </target>]]></source>
+
+ <p>
+ This target simply runs the compiled demo class. JDK 1.4 users can in addition to this generate
+ Javadocs:
+ </p>
+
+ <source><![CDATA[ <target name="javadoc" description="o Create Javadocs for the demo">
+ <mkdir dir="${basedir}/javadoc/"/>
+ <javadoc
+ destdir="${basedir}/javadoc/"
+ additionalparam="-J-Dorg.apache.commons.attributes.javadoc.CATaglet.sources=${basedir}">
+ <taglet
+ name="org.apache.commons.attributes.javadoc.CATaglet"
+ path="${ant.home}/lib/commons-attributes-compiler-SNAPSHOT.jar"
+ />
+ <fileset dir="${basedir}/" includes="**/*.java" />
+ </javadoc>
</target>]]></source>
<p>
- Finally, run the demo.
+ See <a href="documenting.html">Documenting</a> for a walkthrough of the Javadoc
+ Taglet.
</p>
<source><![CDATA[</project>
1.8 +1 -1 jakarta-commons-sandbox/attributes/site/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/attributes/site/xdocs/navigation.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- navigation.xml 5 May 2004 12:23:23 -0000 1.7
+++ navigation.xml 5 May 2004 14:45:29 -0000 1.8
@@ -38,7 +38,7 @@
<item name="Compiling" href="/compiler.html"/>
<item name="Indexing" href="/indexer.html"/>
<item name="Validating" href="/validator.html"/>
- <item name="Documenting" href="/taglet.html"/>
+ <item name="Documenting" href="/documenting.html"/>
</item>
<item name="Changelog" href="/changelog.html"/>
1.4 +6 -0 jakarta-commons-sandbox/attributes/site/xdocs/reference.xml
Index: reference.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/attributes/site/xdocs/reference.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- reference.xml 5 May 2004 12:23:23 -0000 1.3
+++ reference.xml 5 May 2004 14:45:29 -0000 1.4
@@ -40,6 +40,12 @@
How to use the attribute indexer tool.
</p>
+ <p><a href="documenting.html">Documenting</a>:
+ Commons-Attributes includes a Taglet for the Javadoc tool, which
+ will include any attributes in the javadoc for the class. Note:
+ Taglets are only supported in Javadoc 1.4 and later.
+ </p>
+
</section>
</body>
1.2 +18 -5 jakarta-commons-sandbox/attributes/site/etc/ant_demo/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/attributes/site/etc/ant_demo/build.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- build.xml 18 Mar 2004 23:16:30 -0000 1.1
+++ build.xml 5 May 2004 14:45:29 -0000 1.2
@@ -20,7 +20,7 @@
<project default="run" name="commons-attributes ant demo" basedir=".">
<taskdef resource="org/apache/commons/attributes/anttasks.properties"/>
-
+
<target name="clean" description="o Clean up the generated files">
<delete>
<fileset dir="${basedir}" includes="*.class,*$*"/>
@@ -43,11 +43,24 @@
optimize="false">
</javac>
</target>
-
+
<target name="run" description="o Compile and run the demo" depends="compile">
<java
- classpath="${ant.home}/lib/commons-attributes-api-SNAPSHOT.jar;."
- classname="AttributeDemo"/>
+ classpath="${ant.home}/lib/commons-attributes-api-SNAPSHOT.jar;."
+ classname="AttributeDemo"/>
+ </target>
+
+ <target name="javadoc" description="o Create Javadocs for the demo (Requires Javadoc 1.4+)">
+ <mkdir dir="${basedir}/javadoc/"/>
+ <javadoc
+ destdir="${basedir}/javadoc/"
+ additionalparam="-J-Dorg.apache.commons.attributes.javadoc.CATaglet.sources=${basedir}">
+ <taglet
+ name="org.apache.commons.attributes.javadoc.CATaglet"
+ path="${ant.home}/lib/commons-attributes-compiler-SNAPSHOT.jar"
+ />
+ <fileset dir="${basedir}/" includes="**/*.java" />
+ </javadoc>
</target>
-
+
</project>
1.1 jakarta-commons-sandbox/attributes/compiler/src/java/org/apache/commons/attributes/validation/AttributeValidator.java
Index: AttributeValidator.java
===================================================================
/*
* Copyright 2003-2004 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.attributes.validation;
import java.util.Set;
public interface AttributeValidator {
public void validate (Set classes) throws ValidationException;
}
1.1 jakarta-commons-sandbox/attributes/compiler/src/java/org/apache/commons/attributes/validation/AttributeValidatorTask.java
Index: AttributeValidatorTask.java
===================================================================
/*
* Copyright 2003-2004 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.attributes.validation;
import java.io.BufferedInputStream;
import java.io.BufferedOutputStream;
import java.io.File;
import java.io.FileOutputStream;
import java.io.InputStream;
import java.io.PrintWriter;
import java.io.PrintStream;
import java.net.URL;
import java.net.URLClassLoader;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import java.util.jar.JarFile;
import java.util.jar.JarEntry;
import java.util.jar.JarOutputStream;
import org.apache.commons.attributes.AttributeRepositoryClass;
import org.apache.commons.attributes.Attributes;
import org.apache.commons.attributes.AttributeUtil;
import org.apache.commons.attributes.Indexed;
import org.apache.tools.ant.AntClassLoader;
import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.Task;
import org.apache.tools.ant.types.FileSet;
import org.apache.tools.ant.types.Path;
/**
* Ant task to compile attribute indexes. Usage:
*
* <pre><code>
* <taskdef resource="org/apache/commons/attributes/anttasks.properties"/>
*
* <attribute-indexer jarFile="myclasses.jar">
* <classpath>
* ...
* </classpath>
* </attribute-indexer>
* </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.
*/
public class AttributeValidatorTask extends Task {
private File jarFile;
private List classes = new ArrayList ();
private List validators = new ArrayList ();
private Path classPath;
private File baseName;
private boolean inMaven = false;
public static class Validator {
private String className;
public void setClass (String className) {
this.className = className;
}
public String getClassName () {
return className;
}
}
public void setJarfile (File jarFile) {
this.jarFile = jarFile;
}
public void setBaseName (File baseName) {
inMaven = true;
this.baseName = baseName;
}
public Path createClasspath () {
this.classPath = new Path(project);
return classPath;
}
public Validator createValidator () {
Validator validator = new Validator ();
validators.add (validator);
return validator;
}
private static final String SUFFIX = "$__attributeRepository.class";
protected void findJarFile () throws BuildException {
File[] allFiles = baseName.getParentFile ().listFiles ();
if (allFiles == null) {
throw new BuildException ("Unable to find any file with base name " + baseName.getName ()
+ " in " + baseName.getParentFile ().getPath ());
}
long newestDate = 0;
for (int i = 0; i < allFiles.length; i++) {
String name = allFiles[i].getName ();
if (name.startsWith (baseName.getName ()) && name.endsWith (".jar") &&
allFiles[i].lastModified () > newestDate) {
jarFile = allFiles[i];
newestDate = allFiles[i].lastModified ();
}
}
if (jarFile == null) {
throw new BuildException ("Unable to find any file with base name " + baseName.getName ()
+ " in " + baseName.getParentFile ().getPath ());
}
}
public void execute () throws BuildException {
if (inMaven) {
findJarFile ();
}
if (!jarFile.exists ()) {
log ("Can't find " + jarFile.getPath ());
return;
}
try {
log ("Validating attributes in " + jarFile.getPath ());
JarFile jar = new JarFile (jarFile);
try {
Enumeration enum = jar.entries ();
while (enum.hasMoreElements ()) {
JarEntry entry = (JarEntry) enum.nextElement ();
if (!entry.isDirectory ()) {
String className = entry.getName ();
if (className.endsWith (SUFFIX)) {
className = className.replace ('/', '.').replace ('\\', '.').substring (0, className.length () - SUFFIX.length ());
classes.add (className);
}
}
}
} finally {
jar.close ();
}
AntClassLoader cl = new AntClassLoader (this.getClass ().getClassLoader (), project, classPath, true);
try {
cl.addPathElement (jarFile.getPath ());
HashSet classesToValidate = new HashSet ();
Iterator attrs = classes.iterator ();
while (attrs.hasNext ()) {
String className = (String) attrs.next ();
Class clazz = cl.loadClass (className);
classesToValidate.add (clazz);
}
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 {
attrValidator.validate (classesToValidate);
} catch (ValidationException ve) {
throw new BuildException (ve.getMessage ());
}
}
} finally {
cl.cleanup ();
}
} catch (BuildException be) {
throw be;
} catch (Exception e) {
e.printStackTrace ();
throw new BuildException (e.toString ());
}
}
}
1.1 jakarta-commons-sandbox/attributes/compiler/src/java/org/apache/commons/attributes/validation/ValidationException.java
Index: ValidationException.java
===================================================================
/*
* Copyright 2003-2004 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.attributes.validation;
public class ValidationException extends Exception {
public ValidationException (String message) {
super (message);
}
}
1.9 +2 -2 jakarta-commons-sandbox/attributes/compiler/src/java/org/apache/commons/attributes/compiler/AttributeIndexer.java
Index: AttributeIndexer.java
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/attributes/compiler/src/java/org/apache/commons/attributes/compiler/AttributeIndexer.java,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- AttributeIndexer.java 21 Mar 2004 00:04:15 -0000 1.8
+++ AttributeIndexer.java 5 May 2004 14:45:29 -0000 1.9
@@ -155,8 +155,8 @@
JarEntry entry = (JarEntry) enum.nextElement ();
if (!entry.isDirectory ()) {
String className = entry.getName ();
- if (className.endsWith (".class") && !className.endsWith (SUFFIX)) {
- className = className.replace ('/', '.').replace ('\\', '.').substring (0, className.length () - 6);
+ if (className.endsWith (SUFFIX)) {
+ className = className.replace ('/', '.').replace ('\\', '.').substring (0, className.length () - SUFFIX.length ());
classes.add (className);
}
}
1.3 +2 -1 jakarta-commons-sandbox/attributes/compiler/src/java/org/apache/commons/attributes/anttasks.properties
Index: anttasks.properties
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/attributes/compiler/src/java/org/apache/commons/attributes/anttasks.properties,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- anttasks.properties 19 Feb 2004 14:49:13 -0000 1.2
+++ anttasks.properties 5 May 2004 14:45:29 -0000 1.3
@@ -14,4 +14,5 @@
# limitations under the License.
#
attribute-compiler=org.apache.commons.attributes.compiler.AttributeCompiler
-attribute-indexer=org.apache.commons.attributes.compiler.AttributeIndexer
\ No newline at end of file
+attribute-indexer=org.apache.commons.attributes.compiler.AttributeIndexer
+attribute-validator=org.apache.commons.attributes.validation.AttributeValidatorTask
\ No newline at end of file
1.8 +4 -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.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- Indexed.java 21 Mar 2004 00:04:15 -0000 1.7
+++ Indexed.java 5 May 2004 14:45:29 -0000 1.8
@@ -21,6 +21,10 @@
* 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.
*/
public class Indexed {
}
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org