avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From leosu...@apache.org
Subject cvs commit: avalon-sandbox/attributes/compiler/src/java/org/apache/avalon/attributes/compiler AttributeIndexer.java AttributeCompiler.java
Date Fri, 15 Aug 2003 18:43:25 GMT
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|----&gt; Attribute Compiler ----&gt;|Generated Java Files|   
  ++------------+                              +--------------------+
  +      |                                                 |
  +      |                                                 |
  +      |               +-------------+                   |
  +      +--------------&gt;|Java Compiler|&lt;------------------+
  +                      +-------------+
  +                             |
  +                             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>&lt;project name="avalon-attributes-demo" default="build"
basedir="."&gt;
  +    
  +    &lt;path id="build.classpath"&gt;
  +        &lt;pathelement path="avalon-attributes-api-SNAPSHOT.jar"/&gt;
  +        &lt;pathelement path="avalon-attributes-compiler-SNAPSHOT.jar"/&gt;
  +    &lt;/path&gt;
  +    
  +    &lt;taskdef name="attribute-compiler" 
  +        classname="org.apache.avalon.attributes.compiler.AttributeCompiler"&gt;
  +        &lt;classpath&gt;
  +            &lt;path refid="build.classpath"/&gt;
  +        &lt;/classpath&gt;
  +    &lt;/taskdef&gt;
  +    
  +    &lt;target name="build"&gt;
  +        &lt;attribute-compiler destDir="."&gt;
  +            &lt;fileset dir="." includes="*.java"/&gt;
  +        &lt;/attribute-compiler&gt;    
  +        
  +        &lt;javac srcdir="." 
  +            destdir="."
  +            target="1.3"&gt;
  +            &lt;classpath&gt;
  +                &lt;path refid="build.classpath"/&gt;
  +            &lt;/classpath&gt;
  +        &lt;/javac&gt;
  +    &lt;/target&gt;
  +    
  +    &lt;target name="run"&gt;
  +        &lt;java fork="yes" classname="Main"&gt;
  +            &lt;classpath&gt;
  +                &lt;path refid="build.classpath"/&gt;
  +                &lt;pathelement path="."/&gt;
  +            &lt;/classpath&gt;
  +        &lt;/java&gt;
  +    &lt;/target&gt;
  +&lt;/project&gt;</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&gt;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&gt;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>
  + *     &lt;taskdef resource="org/apache/avalon/attributes/anttasks.properties"/&gt;
  + *     
  + *     &lt;attribute-indexer destFile="META-INF/attrs.index"&gt;
  + *         &lt;fileset dir="classes/" includes="*.class"/&gt;
  + *     &lt;/attribute-indexer&gt;
  + * </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>&lt;fileset/&gt;</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>
  + *     &lt;taskdef resource="org/apache/avalon/attributes/anttasks.properties"/&gt;
  + *     
  + *     &lt;attribute-compiler destDir="temp/"&gt;
  + *         &lt;fileset dir="src/" includes="*.java"/&gt;
  + *     &lt;/attribute-compiler&gt;
  + * </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: cvs-unsubscribe@avalon.apache.org
For additional commands, e-mail: cvs-help@avalon.apache.org


Mime
View raw message