leosutic 2003/08/15 11:43:25
Modified: attributes/site project.xml
attributes/api/src/java overview.html
attributes/unittest/src/test/org/apache/avalon/attributes/test
AttributesTestCase.java
attributes/api/src/java/org/apache/avalon/attributes
Attributes.java
attributes/compiler/src/java/org/apache/avalon/attributes/compiler
AttributeIndexer.java AttributeCompiler.java
Log:
Added some documentation.
Revision Changes Path
1.3 +1 -1 avalon-sandbox/attributes/site/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/avalon-sandbox/attributes/site/project.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- project.xml 10 Aug 2003 22:21:59 -0000 1.2
+++ project.xml 15 Aug 2003 18:43:25 -0000 1.3
@@ -2,7 +2,7 @@
<project>
<extend>${basedir}/../project.xml</extend>
- <package>org.apache.avalon.meta</package>
+ <package>org.apache.avalon.attributes</package>
<dependencies>
1.2 +176 -2 avalon-sandbox/attributes/api/src/java/overview.html
Index: overview.html
===================================================================
RCS file: /home/cvs/avalon-sandbox/attributes/api/src/java/overview.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- overview.html 10 Aug 2003 22:25:03 -0000 1.1
+++ overview.html 15 Aug 2003 18:43:25 -0000 1.2
@@ -1,6 +1,180 @@
<html>
<body>
- <p>The Avalon Attributes projects provides a Java preprocessor
- and an API that enables developers to use C#-like attributes in their
programs.
+ <p>The Avalon Attributes projects enables developers to use C#-like
attributes in their programs.</p>
+
+ <h3>What does it do for me?</h3>
+
+ <p>The Avalon Attributes project allows you to add objects, called
attributes, to your
+ classes, methods and fields:</p>
+
+ <blockquote><pre>public class MyAttribute {}
+
+/**
+ * @@MyAttribute
+ */
+public class MyClass { }</pre></blockquote>
+
+ <p>These attributes can then be retrieved at runtime:</p>
+
+ <blockquote><pre>Collection attrs = Attributes.getAttributes( MyClass.class
);
+
+// Get the first object of the collection
+MyAttribute myAttr = (MyAttribute) attrs.iterator().next();
+</pre></blockquote>
+
+ <p>Attributes can in turn contain values:</p>
+
+ <blockquote><pre>public class Dependency {
+
+ private final String name;
+ private final Class dependencyClass;
+
+ public Dependency( String name, Class dependencyClass ) {
+ this.name = name;
+ this.dependencyClass = dependencyClass;
+ }
+
+ public Class getDependencyClass() {
+ return this.dependencyClass;
+ }
+
+ public String getName() {
+ return this.name;
+ }
+}</pre></blockquote>
+
+ <p>This attribute can then be used like this:</p>
+
+ <blockquote><pre>/**
+ * @@Dependency( "dependency-name", SomeClass.class )
+ */
+public class MyClass { }</pre></blockquote>
+
+ <h3>How do I use it?</h3>
+
+ <p>The Attributes project provides a precompiler that you must run before
you compile your Java
+ classes with Javac (or some other Java compiler). The process goes like
this:</p>
+
+<blockquote><pre>
++------------+ +--------------------+
+|Java Sources|----> Attribute Compiler ---->|Generated Java Files|
++------------+ +--------------------+
+ | |
+ | |
+ | +-------------+ |
+ +-------------->|Java Compiler|<------------------+
+ +-------------+
+ |
+ v
+ +-----------------+
+ |Java .class files|
+ +-----------------+
+</pre></blockquote>
+
+ <p>Let's illustrate the above with a short tutorial. Create a new folder
and place in it the following files:</p>
+
+ <h4>build.xml</h4>
+
+ <blockquote><pre><project name="avalon-attributes-demo" default="build"
basedir=".">
+
+ <path id="build.classpath">
+ <pathelement path="avalon-attributes-api-SNAPSHOT.jar"/>
+ <pathelement path="avalon-attributes-compiler-SNAPSHOT.jar"/>
+ </path>
+
+ <taskdef name="attribute-compiler"
+ classname="org.apache.avalon.attributes.compiler.AttributeCompiler">
+ <classpath>
+ <path refid="build.classpath"/>
+ </classpath>
+ </taskdef>
+
+ <target name="build">
+ <attribute-compiler destDir=".">
+ <fileset dir="." includes="*.java"/>
+ </attribute-compiler>
+
+ <javac srcdir="."
+ destdir="."
+ target="1.3">
+ <classpath>
+ <path refid="build.classpath"/>
+ </classpath>
+ </javac>
+ </target>
+
+ <target name="run">
+ <java fork="yes" classname="Main">
+ <classpath>
+ <path refid="build.classpath"/>
+ <pathelement path="."/>
+ </classpath>
+ </java>
+ </target>
+</project></pre></blockquote>
+
+ <h4>MyAttribute.java</h4>
+
+ <blockquote><pre>public class MyAttribute {
+
+ public final String value;
+
+ public MyAttribute( String value ) {
+ this.value = value;
+ }
+
+ public String getValue () {
+ return value;
+ }
+
+ public String toString () {
+ return "[MyAttribute: " + value + "]";
+ }
+
+}</pre></blockquote>
+
+
+ <h4>Main.java</h4>
+
+ <blockquote><pre>import java.util.Collection;
+import org.apache.avalon.attributes.Attributes;
+
+/**
+ * @@MyAttribute( "A value" )
+ */
+public class Main {
+
+ public static void main (String[] args) {
+ Collection attributes = Attributes.getAttributes ( Main.class );
+ System.out.println ("The class Main has the following attributes:");
+ System.out.println (attributes);
+ }
+
+}</pre></blockquote>
+
+ <p>Place the two <tt>.jar</tt> files that the Attribute project consists of
(<tt>avalon-attributes-api-SNAPSHOT.jar</tt>
+ <tt>avalon-attributes-compiler-SNAPSHOT.jar</tt>) in the directory. Then
compile everything with:</p>
+
+ <blockquote><pre>C:\tutorial>ant
+Buildfile: build.xml
+
+build:
+ [javac] Compiling 3 source files to C:\tutorial
+
+BUILD SUCCESSFUL
+Total time: 8 seconds</pre></blockquote>
+
+ <p>and run the small demo with:</p>
+
+ <blockquote><pre>C:\tutorial>ant run
+Buildfile: build.xml
+
+run:
+ [java] The class Main has the following attributes:
+ [java] [[MyAttribute: A value]]
+
+BUILD SUCCESSFUL
+Total time: 3 seconds</pre></blockquote>
+
</body>
</html>
1.2 +2 -2
avalon-sandbox/attributes/unittest/src/test/org/apache/avalon/attributes/test/AttributesTestCase.java
Index: AttributesTestCase.java
===================================================================
RCS file:
/home/cvs/avalon-sandbox/attributes/unittest/src/test/org/apache/avalon/attributes/test/AttributesTestCase.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- AttributesTestCase.java 14 Aug 2003 22:09:27 -0000 1.1
+++ AttributesTestCase.java 15 Aug 2003 18:43:25 -0000 1.2
@@ -139,8 +139,8 @@
* won't mess up the attribute cache.
*/
public void testClassLoaderKeying () throws Exception {
- URLClassLoader cl1 = new URLClassLoader (new URL[]{new File
("api/target/cl1/").toURL ()}, getClass().getClassLoader ());
- URLClassLoader cl2 = new URLClassLoader (new URL[]{new File
("api/target/cl2/").toURL ()}, getClass().getClassLoader ());
+ URLClassLoader cl1 = new URLClassLoader (new URL[]{new File
("unittest/target/cl1/").toURL ()}, getClass().getClassLoader ());
+ URLClassLoader cl2 = new URLClassLoader (new URL[]{new File
("unittest/target/cl2/").toURL ()}, getClass().getClassLoader ());
Class cl1Class = cl1.loadClass ("TestClass");
Class cl2Class = cl2.loadClass ("TestClass");
1.8 +26 -1
avalon-sandbox/attributes/api/src/java/org/apache/avalon/attributes/Attributes.java
Index: Attributes.java
===================================================================
RCS file:
/home/cvs/avalon-sandbox/attributes/api/src/java/org/apache/avalon/attributes/Attributes.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- Attributes.java 14 Aug 2003 22:10:14 -0000 1.7
+++ Attributes.java 15 Aug 2003 18:43:25 -0000 1.8
@@ -151,6 +151,10 @@
return getAttributes (getAttributes (method), attributeClass);
}
+ /**
+ * Filters a collection of <code>Class</code> objects. The returned collection
+ * only contains those classes that have an attribute of the specified type.
+ */
public static Collection getClassesWithAttributeType (Collection classes, Class
attributeClass) {
ArrayList result = new ArrayList ();
Iterator iter = classes.iterator ();
@@ -165,6 +169,23 @@
}
/**
+ * Filters a collection objects. The returned collection
+ * only contains those objects that have an attribute of the specified type.
+ */
+ public static Collection getObjectsWithAttributeType (Collection objects, Class
attributeClass) {
+ ArrayList result = new ArrayList ();
+ Iterator iter = objects.iterator ();
+ while (iter.hasNext ()) {
+ Class clazz = (Class) iter.next ().getClass ();
+ if (hasAttributeType (clazz, attributeClass)) {
+ result.add (clazz);
+ }
+ }
+
+ return result;
+ }
+
+ /**
* Convenience function to test whether a collection of attributes contain
* an attribute of a given class.
*/
@@ -252,7 +273,11 @@
return hasAttribute (getAttributes (method), attribute);
}
-
+ /**
+ * Constructs an <code>AttributeIndex</code> for the given
<code>ClassLoader</code>.
+ * An AttributeIndex allows oyu to quickly find all classes that have a given
+ * attribute.
+ */
public static AttributeIndex getAttributeIndex (ClassLoader cl) throws
Exception {
return new AttributeIndex (cl);
}
1.2 +18 -1
avalon-sandbox/attributes/compiler/src/java/org/apache/avalon/attributes/compiler/AttributeIndexer.java
Index: AttributeIndexer.java
===================================================================
RCS file:
/home/cvs/avalon-sandbox/attributes/compiler/src/java/org/apache/avalon/attributes/compiler/AttributeIndexer.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- AttributeIndexer.java 14 Aug 2003 22:11:16 -0000 1.1
+++ AttributeIndexer.java 15 Aug 2003 18:43:25 -0000 1.2
@@ -15,7 +15,24 @@
import java.util.*;
/**
- * Ant task to compile attributes.
+ * Ant task to compile attribute indexes. Usage:
+ *
+ * <pre><code>
+ * <taskdef resource="org/apache/avalon/attributes/anttasks.properties"/>
+ *
+ * <attribute-indexer destFile="META-INF/attrs.index">
+ * <fileset dir="classes/" includes="*.class"/>
+ * </attribute-indexer>
+ * </code></pre>
+ *
+ * The task should be run after compiling the Java sources (including those
generated
+ * by the <tt>attribute-compiler</tt> task), and the nested
<tt><fileset/></tt> elements
+ * should include the resulting class files.
+ *
+ * <p>Note: This task isn't that tested, and is pre-alpha. Amog other things, you
have to name the
+ * destination file <tt>attrs.index</tt> and it has to be reachable via
+ * <tt>ClassLoader.getResource("META-INF/attrs.index")</tt>. I'd like to change
this into something
+ * that has a lot less unstated assumptions and requirements.
*/
public class AttributeIndexer extends Task {
1.4 +13 -1
avalon-sandbox/attributes/compiler/src/java/org/apache/avalon/attributes/compiler/AttributeCompiler.java
Index: AttributeCompiler.java
===================================================================
RCS file:
/home/cvs/avalon-sandbox/attributes/compiler/src/java/org/apache/avalon/attributes/compiler/AttributeCompiler.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- AttributeCompiler.java 14 Aug 2003 22:11:16 -0000 1.3
+++ AttributeCompiler.java 15 Aug 2003 18:43:25 -0000 1.4
@@ -9,7 +9,19 @@
import java.util.*;
/**
- * Ant task to compile attributes.
+ * Ant task to compile attributes. Usage:
+ *
+ * <pre><code>
+ * <taskdef resource="org/apache/avalon/attributes/anttasks.properties"/>
+ *
+ * <attribute-compiler destDir="temp/">
+ * <fileset dir="src/" includes="*.java"/>
+ * </attribute-compiler>
+ * </code></pre>
+ *
+ * The task should be run before compiling the Java sources, and will produce some
+ * additional Java source files in the destination directory that should be compiled
+ * along with the input source files. (See the overview for a diagram.)
*/
public class AttributeCompiler extends XJavadocTask {
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
