commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From leosu...@apache.org
Subject cvs commit: jakarta-commons-sandbox/attributes/api/src/java overview.html
Date Thu, 18 Mar 2004 23:15:04 GMT
leosutic    2004/03/18 15:15:04

  Modified:    attributes/api/src/java overview.html
  Log:
  Moved a lot of this to the website.
  
  Revision  Changes    Path
  1.7       +2 -300    jakarta-commons-sandbox/attributes/api/src/java/overview.html
  
  Index: overview.html
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/attributes/api/src/java/overview.html,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- overview.html	3 Mar 2004 21:53:17 -0000	1.6
  +++ overview.html	18 Mar 2004 23:15:03 -0000	1.7
  @@ -19,305 +19,7 @@
       <body>
           <p>The Jakarta Commons Attributes projects enables developers to use C#-like
attributes in their programs.</p>
           
  -        <h2>Tutorial</h2>
  -        
  -        <ul>
  -            <li><p><a href="#what_does_it_do">What does it do for me?</a></p></li>
  -            <li><p><a href="#how_do_i_use_it_with_maven">How do I use
it with Maven?</a></p></li>
  -            <li><p><a href="#how_do_i_use_it_with_ant">How do I use it
with Ant?</a></p></li>
  -            <li><p><a href=""></a></p></li>
  -            <li><p><a href=""></a></p></li>
  -            <li><p><a href=""></a></p></li>
  -        </ul>
  -        
  -        <a name="what_does_it_do"/>
  -        <h3>What does it do for me?</h3>
  -        
  -        <p>The Jakarta Commons Attributes project allows you to add value 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>
  -        
  -    <a name="how_do_i_use_it_with_maven"/>
  -        <h3>How do I use it with Maven?</h3>
  -        
  -        <p>Two steps: First, install the plugin. Your sources will be automatically
precompiled. 
  -        Second, add the client api as a dependency: </p>
  -        
  -        <blockquote><pre>&lt;dependency&gt;
  -    &lt;groupId&gt;commons-attributes&lt;/groupId&gt;
  -    &lt;artifactId&gt;commons-attributes-api&lt;/artifactId&gt;
  -    &lt;version&gt;SNAPSHOT&lt;/version&gt;
  -&lt;/dependency&gt;</pre></blockquote>
  -        
  -        <a name="how_do_i_use_it_with_ant"/>
  -        <h3>How do I use it with Ant?</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. First, install the attribute
compiler as
  -    described <a href="http://jakarta.apache.org/commons/sandbox/attributes/">here</a>.
Then create a new 
  -    folder and place the following files in it:</p>
  -        
  -        <h4>build.xml</h4>
  -        
  -        <blockquote><pre>&lt;project name="commons-attributes-demo" default="build"
basedir="."&gt;
  -    
  -    &lt;path id="build.classpath"&gt;
  -        &lt;pathelement path="commons-attributes-api-SNAPSHOT.jar"/&gt;
  -    &lt;/path&gt;
  -    
  -    &lt;taskdef name="attribute-compiler" 
  -        classname="org.apache.commons.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.commons.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 client api <tt>.jar</tt> file (<tt>commons-attributes-api-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>
  -        
  -    <h3>How do I add attributes to my classes?</h3>
  -    
  -    <p>Attributes are added in Javadoc comments for classes, methods and fields.
Each attribute
  -    expression is on the form:</p>
  -    
  -    <blockquote><pre>
  -        @@[<i>optional target expression</i>] <i>AttributeClass</i>(<i>constructor
args</i> [ <i>optional named args</i> ])
  -    </pre></blockquote>
  -    
  -        <h3>How do I add attributes to parameters and return values?</h3>
  -        
  -        <p>Use the following syntax:</p>
  -        <blockquote><pre>public class MyClass {
  -
  -    /**
  -     * @@.myParameter MyOtherAttribute()
  -     * @@.return MyAttribute()
  -     */
  -    public Integer myMethod (int myParameter) {};
  -
  -}</pre></blockquote>        
  -        
  -        <p>You will then be able to retrieve MyAttribute via <code>Attributes.getReturnAttribute(
method )</code>
  -        and MyOtherAttribute via <code>Attributes.getParameterAttribute( method,
0 )</code></p>
  -        
  -        <h3>What happens if I add the same attribute twice?</h3>
  -        
  -        <p>Let's define the question a bit stricter. Suppose you have an attribute
(MyAttribute), and you have a class MyClass:</p>
  -        
  -        <blockquote><pre>/**
  - * @@MyAttribute()
  - * @@MyAttribute()
  - */
  -public class MyClass {}</pre></blockquote>
  -        
  -        <p>The question is now, will the collection returned by Attributes.getAttributes
(MyClass.class) have one or 
  -        two elements? The answer is that it depends on the way MyAttribute handles equality.
The attributes associated
  -        with a class, method or field always for a Set, meaning that there are no duplicates.
So if MyAttribute is 
  -        implemented this way:</p>
  -        
  -        <blockquote><pre>public class MyAttribute {}</pre></blockquote>
  -        
  -        <p>Then you will get two elements, since each instance of MyAttribute is
different from every other instance. 
  -        However, if MyAttribute is implemented like this:</p>
  -        
  -        <blockquote><pre>public class MyAttribute {
  -    public int hashCode () { return 0; }
  -    public boolean equals (Object o) { return o instanceof MyAttribute; }
  -}</pre></blockquote>
  -        
  -        <p>That is, every instance of MyAttribute is equal to any other instance
of the class, then you will only get
  -        one element in the collection.</p>
  -        
  -        <p>The above also holds true if the attribute has been inherited.</p>
  -        
  -        
  -        <h3>What are the requirements for an attribute class?</h3>
  -        
  -        <p>It must have a public constructor. That's all.</p>
  -      
  -        
  -        <h3>I tried adding attributes to an anonymous class and it didn't work.</h3>
  -        
  -        <p>That's not supported (yet). It is also very hard to implement since the
class name is decided by the Java compiler.</p>
  -        
  -        <h3>How do I add attributes to classes that are generated at runtime (BCEL,
dynamic proxies)?</h3>
  -        
  -        <p>Not supported yet, but probably we'll supply a method like <code>Attributes.registerAttributes
(Class clazz, AttributePackage package)</code> that you'll be able to call.</p>
  -        
  -        
  -        <h3>I want to add a constant value as an attribute.</h3>
  -        
  -        <p>So you have this</p>
  -        
  -        <blockquote><pre>public class Values {
  -    public static final Integer ONE = new Integer (1);
  -}</pre></blockquote>
  -        
  -        <p>and now you'd like to add ONE as an attribute like this:</p>
  -        
  -        <blockquote><pre>/**
  - * @@Values.ONE
  - */
  -public class MyClass { ... }</pre></blockquote>
  -        
  -        <p>how can this be done?</p>
  -        
  -        <p>The best that can be offered is:</p>
  -        
  -        <blockquote><pre>/**
  - * @@Integer(Values.ONE)
  - */
  -public class MyClass { ... }</pre></blockquote>
  -        
  -        <p>I'm afraid. The expression follwing the @@ must fit the template "new
(expression)" optionally suffixed by "()". This makes the compiler much simpler, and the loss
of functionality was considered worth it. You can also define a separate ONE class:</p>
  -        
  -<blockquote><pre>public class One {}</pre></blockquote>
  -        
  -        <p>and use it.</p>
  -        
  +        <p>Please see the project website at <a href="http://jakarta.apache.org/commons/sandbox/attributes/">http://jakarta.apache.org/commons/sandbox/attributes/</a>
  +        for a tutorial and instructions for use.</p>
       </body>
   </html>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message