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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]