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/site/xdocs ant_demo.xml index.xml maven_demo.xml tutorial.xml walkthrough.xml
Date Thu, 18 Mar 2004 23:16:30 GMT
leosutic    2004/03/18 15:16:30

  Modified:    attributes/site maven.xml
               attributes/site/xdocs ant_demo.xml index.xml maven_demo.xml
                        tutorial.xml walkthrough.xml
  Added:       attributes/site/etc/ant_demo AttributeDemo.java build.xml
  Log:
  Wrote a tutorial that will hopefully make this project a bit more
  comprehensible...
  
  Revision  Changes    Path
  1.3       +22 -13    jakarta-commons-sandbox/attributes/site/maven.xml
  
  Index: maven.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/attributes/site/maven.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- maven.xml	19 Feb 2004 14:49:13 -0000	1.2
  +++ maven.xml	18 Mar 2004 23:16:30 -0000	1.3
  @@ -16,17 +16,26 @@
   =
   -->
   <project default="site" xmlns:maven="jelly:maven" xmlns:j="jelly:core" xmlns:util="jelly:util">
  -
  -  <property file="${basedir}/build.properties"/>
  -  <property file="${basedir}/project.properties"/>
  -
  -  <property name="maven.license.licenseFile" 
  -    value="${basedir}/../LICENSE.txt"/>
  -  <property name="maven.javadoc.stylesheet" 
  -    value="${basedir}/etc/stylesheet.css"/>
  -
  -  <preGoal name="site">
  -    <attainGoal name="license"/>
  -  </preGoal>
  -
  +    
  +    <property file="${basedir}/build.properties"/>
  +    <property file="${basedir}/project.properties"/>
  +    
  +    <property name="maven.license.licenseFile" 
  +        value="${basedir}/../LICENSE.txt"/>
  +    <property name="maven.javadoc.stylesheet" 
  +        value="${basedir}/etc/stylesheet.css"/>
  +    
  +    <preGoal name="site">
  +        <attainGoal name="license"/>
  +    </preGoal>
  +    
  +    <preGoal name="xdoc:copy-user-resources">
  +        <copy todir="${basedir}/target/docs" filtering="no">
  +            <fileset dir="${basedir}/etc/">
  +                <include name="ant_demo/**"/>
  +                <include name="maven_demo/**"/>
  +                <exclude name="**/CVS/*"/>
  +            </fileset>
  +        </copy>
  +    </preGoal>
   </project>
  
  
  
  1.1                  jakarta-commons-sandbox/attributes/site/etc/ant_demo/AttributeDemo.java
  
  Index: AttributeDemo.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.
  *
  */
  import org.apache.commons.attributes.Attributes;
  
  class MyAttribute {
      private final String ctorArg;
      private String namedArg = null;
      
      public MyAttribute (String ctorArg) {
          this.ctorArg = ctorArg;
      }
      
      public void setNamedArgument (String namedArg) {
          this.namedArg = namedArg;
      }
      
      public String toString () {
          return "[MyAttribute  constructor argument: \"" + 
              ctorArg + "\" named argument: \"" + namedArg + "\"]";
      }
  }
  
  /**
   * @@MyAttribute ("This string is passed to the constructor.", 
   *                namedArgument="This argument will be passed to the setNamedArgument method")
   */
  public class AttributeDemo {
      public static void main (String args[]) {
          System.out.println (Attributes.getAttributes (AttributeDemo.class));
      }
  }
  
  
  1.1                  jakarta-commons-sandbox/attributes/site/etc/ant_demo/build.xml
  
  Index: build.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  
  <!--
  =
  = 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.
  =
  -->
  <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,*$*"/>
          </delete>
      </target>
      
      <target name="compile-attributes" description="o Run the commons-attributes precompiler">
          <attribute-compiler destdir=".">
              <fileset dir="." includes="*.java"/>
          </attribute-compiler>
      </target>
      
      <target name="compile" depends="compile-attributes" description="o Compile the code">
          <javac 
              srcdir="." 
              destdir="${basedir}" 
              deprecation="true" 
              debug="true" 
              classpath="${ant.home}/lib/commons-attributes-api-SNAPSHOT.jar;."
              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"/>
      </target>
              
  </project>
  
  
  
  1.2       +223 -0    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.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- ant_demo.xml	4 Mar 2004 00:39:17 -0000	1.1
  +++ ant_demo.xml	18 Mar 2004 23:16:30 -0000	1.2
  @@ -34,6 +34,229 @@
                   the all features work.
               </p>
           </section>
  +        
  +        <section name="Download and Installation">
  +            
  +            <p>
  +                Download the following files and put them in your <code>$ANT_HOME/lib</code>
directory:
  +            </p>
  +            
  +            <ul>
  +                <li>
  +                    <p>Client API: <a href="http://cvs.apache.org/~leosutic/commons-attributes-api-SNAPSHOT.jar">commons-attributes-api-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>Ant task: <a href="http://cvs.apache.org/~leosutic/commons-attributes-compiler-SNAPSHOT.jar">commons-attributes-compiler-SNAPSHOT.jar</a></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>
  +                </li>
  +                <li>
  +                    <p>Xjavadoc 1.0: <a href="http://www.ibiblio.org/maven/xjavadoc/jars/xjavadoc-1.0.jar">xjavadoc-1.0.jar</a></p>
  +                </li>
  +            </ul>
  +            
  +        </section>
  +        
  +        <section name="Getting the Demo Files">
  +            <p>
  +                Download these files and put them in a directory of your choice:
  +            </p>
  +            
  +            <ul>
  +                <li>
  +                    <p>Ant build file: <a href="ant_demo/build.xml">build.xml</a></p>
  +                </li>
  +                <li>
  +                    <p>Java source file: <a href="ant_demo/AttributeDemo.java">AttributeDemo.java</a></p>
  +                </li>
  +            </ul>
  +        </section>
  +        
  +        <section name="Running the Demo">
  +            
  +            <p>
  +                The buildfile is already set up, so you should only have to do the following:
  +            </p>
  +            
  +            <source><![CDATA[# cd directory-where-i-put-demo-files
  +# ant
  +Buildfile: build.xml
  +
  +compile-attributes:
  +[attribute-compiler] Generated attribute information for 1 classes.
  +
  +compile:
  +    [javac] Compiling 2 source files to /home/leosutic/demo
  +
  +run:
  +     [java] [[MyAttribute  constructor argument: "This string is passed to the c
  +onstructor." named argument: "This argument will be passed to the setNamedArgume
  +nt method"]]
  +
  +BUILD SUCCESSFUL
  +Total time: 7 seconds]]></source>
  +         
  +        </section>
  +        
  +        <section name="Demo Walkthrough">
  +            
  +            <p>The demo consists of two files. We will first look at the Java source
file, and
  +                then the build.xml file.</p>
  +            
  +            <subsection name="Java Sources">
  +                
  +                <source><![CDATA[class MyAttribute {
  +    private final String ctorArg;
  +    private String namedArg = null;
  +    
  +    public MyAttribute (String ctorArg) {
  +        this.ctorArg = ctorArg;
  +    }
  +    
  +    public void setNamedArgument (String namedArg) {
  +        this.namedArg = namedArg;
  +    }
  +    
  +    public String toString () {
  +        return "[MyAttribute  constructor argument: \"" + 
  +            ctorArg + "\" named argument: \"" + namedArg + "\"]";
  +    }
  +}]]></source>
  +                
  +                <p>This is simply the definition of an attribute class. It takes
one constructor
  +                    argument, and has one named argument.</p>
  +                
  +                <source><![CDATA[/**
  + * @@MyAttribute ("This string is passed to the constructor.", 
  + *                namedArgument="This argument will be passed to the setNamedArgument method")
  + */
  +public class AttributeDemo {]]></source>
  +                
  +                <p>
  +                    OK, now it is getting interesting! This is where we add one instance
of 
  +                    the MyAttribute class to the AttributeDemo class. The two @-signs indicate
that
  +                    this is an attribute, and will cause the attribute compiler to pick
up the
  +                    attribute. The first string will be passed to the constructor. The
second parameter,
  +                    however, is on the form <code>name = expression</code>,
and will result in the
  +                    <code>setNamedArgument</code> method being called.
  +                </p>
  +                
  +<source><![CDATA[public class AttributeDemo {
  +    public static void main (String args[]) {
  +        System.out.println (Attributes.getAttributes (AttributeDemo.class));
  +    }
  +}]]></source>
  +                
  +                <p>
  +                    This is where we access the attributes. The <code>Attributes.getAttributes</code>
  +                    method returns a Collection of all attributes attached to the <code>AttributeDemo</code>
  +                    class.
  +                </p>
  +                
  +            </subsection>
  +            
  +            <subsection name="build.xml">
  +                
  +                <p>
  +                    The build.xml file is pretty much what you'd expect - a target to compile
the
  +                    Java sources, and a target to run the demo. But in addition you'll
find a target
  +                    to preprocess the Java sources.
  +                </p>
  +                
  +                <p>
  +                    The attribute compiler works by first generating a bunch of extra Java
sources
  +                    (one extra file per class with attributes). These extra java sources
are then
  +                    compiled along with the original Java sources. Here's some art to illustrate
  +                    the process:
  +                </p>
  +                
  +                <source><![CDATA[+------------+                              +--------------------+
  +|Java Sources|----> Attribute Compiler ---->|Generated Java Files|   
  ++------------+                              +--------------------+
  +      |                                                 |
  +      |                                                 |
  +      |               +-------------+                   |
  +      +-------------->|Java Compiler|<------------------+
  +                      +-------------+
  +                             |
  +                             v
  +                    +-----------------+
  +                    |Java .class files|
  +                    +-----------------+]]></source>
  +                
  +                <p>
  +                    We must therefore invoke the Attribute Compiler before compiling the
sources.
  +                </p>
  +                
  +                <source><![CDATA[<project default="run" name="commons-attributes
ant demo" basedir=".">
  +    
  +    <taskdef resource="org/apache/commons/attributes/anttasks.properties"/>]]></source>
  +                
  +                <p>
  +                    Nothing special here. We define the Ant tasks provided by the
  +                    commons-attributes compiler.
  +                </p>
  +                
  +                <source><![CDATA[    <target name="clean" description="o Clean
up the generated files">
  +        <delete>
  +            <fileset dir="${basedir}" includes="*.class,*$*"/>
  +        </delete>
  +    </target>]]></source>
  +    
  +                <p>
  +                    Again nothing special. Just a convenience target to clean up all
  +                    generated files. But after that comes:
  +                </p>
  +                
  +                <source><![CDATA[    <target name="compile-attributes" description="o
Run the commons-attributes precompiler">
  +        <attribute-compiler destdir=".">
  +            <fileset dir="." includes="*.java"/>
  +        </attribute-compiler>
  +    </target>]]></source>
  +                
  +                <p>
  +                    This is where we do all the preprocessing. The Attribute Compiler generates
a set of Java
  +                    sources with attribute information in them. This is where we tell the
compiler to generate
  +                    <i>attribute repositories</i> (autogenerated .java files)
for all existing .java files.
  +                    When those files are generated, we go on to compile everything:
  +                </p>
  +                
  +                <source><![CDATA[    <target name="compile" depends="compile-attributes"
description="o Compile the code">
  +        <javac 
  +            srcdir="." 
  +            destdir="${basedir}" 
  +            deprecation="true" 
  +            debug="true" 
  +            classpath="${ant.home}/lib/commons-attributes-api-SNAPSHOT.jar;."
  +            optimize="false">
  +        </javac>
  +    </target>]]></source>
  +                
  +                <p>
  +                    Since we use attributes, we have to include the commons-attributes-api-SNAPSHOT.jar
file in the classpath.
  +                </p>
  +                
  +                <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"/>
  +    </target>]]></source>
  +                
  +                <p>
  +                    Finally, run the demo.
  +                </p>
  +                
  +                <source><![CDATA[</project>
  +]]></source>
  +                
  +            </subsection>
  +            
  +        </section>
  +        
       </body>
       
   </document>
  
  
  
  1.10      +1 -1      jakarta-commons-sandbox/attributes/site/xdocs/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/attributes/site/xdocs/index.xml,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- index.xml	3 Mar 2004 22:32:19 -0000	1.9
  +++ index.xml	18 Mar 2004 23:16:30 -0000	1.10
  @@ -209,7 +209,7 @@
                   </tr>
                   <tr>
                       <td>Runtime code size</td>
  -                    <td>21kB</td>
  +                    <td>25kB</td>
                   </tr>
                   <tr>
                       <td>Unit test coverage</td>
  
  
  
  1.2       +7 -0      jakarta-commons-sandbox/attributes/site/xdocs/maven_demo.xml
  
  Index: maven_demo.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/attributes/site/xdocs/maven_demo.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- maven_demo.xml	4 Mar 2004 00:39:17 -0000	1.1
  +++ maven_demo.xml	18 Mar 2004 23:16:30 -0000	1.2
  @@ -33,6 +33,13 @@
                   In the walkthrough we'll focus more on just what happens, and how
                   the all features work.
               </p>
  +            
  +        </section>
  +        
  +        <section name="Under Construction">
  +            <p>
  +                Working on it... /LS
  +            </p>
           </section>
       </body>
       
  
  
  
  1.3       +1 -1      jakarta-commons-sandbox/attributes/site/xdocs/tutorial.xml
  
  Index: tutorial.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/attributes/site/xdocs/tutorial.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- tutorial.xml	4 Mar 2004 00:39:17 -0000	1.2
  +++ tutorial.xml	18 Mar 2004 23:16:30 -0000	1.3
  @@ -42,7 +42,7 @@
                   </li>
                   <li>
                       <p>
  -                        <a href="walkthrough.html">Walkthrough</a>
  +                        <a href="walkthrough.html">Complete Walkthrough of all Features</a>
                       </p>
                   </li>
               </ul>
  
  
  
  1.2       +114 -1    jakarta-commons-sandbox/attributes/site/xdocs/walkthrough.xml
  
  Index: walkthrough.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/attributes/site/xdocs/walkthrough.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- walkthrough.xml	4 Mar 2004 00:39:17 -0000	1.1
  +++ walkthrough.xml	18 Mar 2004 23:16:30 -0000	1.2
  @@ -150,8 +150,121 @@
           
           <section name="How are they Retrieved?">
               
  -            <p>You retrieve attributes by using the methods in the org.apache.commons.attributes.Attributes
class. See the Javadoc for a description of methods in this class.</p>
  +            <p>You retrieve attributes by using the methods in the org.apache.commons.attributes.Attributes

  +                class. See the <a href="api/index.html">JavaDoc</a> for a description
of methods in this class.</p>
               
  +        </section>
  +        
  +        <section name="How are Attributes Stored?">
  +            
  +            <source><![CDATA[+------------+                              +--------------------+
  +|Java Sources|----> Attribute Compiler ---->|Generated Java Files|   
  ++------------+                              +--------------------+
  +      |                                                 |
  +      |                                                 |
  +      |               +-------------+                   |
  +      +-------------->|Java Compiler|<------------------+
  +                      +-------------+
  +                             |
  +                             v
  +                    +-----------------+
  +                    |Java .class files|
  +                    +-----------------+]]></source>
  +            
  +            <p>
  +                
  +            </p>
  +            
  +        </section>
  +        
  +        <section name="Do I Have to Use the Attribute Compiler?">
  +            
  +            <p>
  +                No, you don't. You can add attributes to a class by programmatically
  +                creating an attribute repository in the class's static initializer.
  +                
  +                See the Javadoc for 
  +                <a href="api/org/apache/commons/attributes/RuntimeAttributeRepository.html">RuntimeAttributeRepository</a>
  +                for an example. <i>It's not pretty, but it works.</i>
  +            </p>
  +            
  +        </section>
  +        
  +        <section name="Gotchas and Other Questions">
  +            <subsection name="What happens if I add the same attribute twice?">
  +                
  +                <p>Let's define the question via a use case. Suppose you have an
attribute (MyAttribute), and you have a class MyClass:</p>
  +                
  +                <source><![CDATA[/**
  + * @@MyAttribute()
  + * @@MyAttribute()
  + */
  +public class MyClass {}]]></source>
  +                
  +                <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>
  +                
  +                <source><![CDATA[public class MyAttribute {}]]></source>
  +                
  +                <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>
  +                
  +                <source><![CDATA[public class MyAttribute {
  +    public int hashCode () { return 0; }
  +    public boolean equals (Object o) { return o instanceof MyAttribute; }
  +}]]></source>
  +                
  +                <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>
  +                
  +            </subsection>
  +            
  +            <subsection name="What are the requirements for an attribute class?">
  +                
  +                <p>It must have a public constructor. That's all.</p>
  +                
  +            </subsection>
  +            
  +            <subsection name="I tried adding attributes to an anonymous class and it
didn't work.">
  +                
  +                <p>That's not supported (yet). It is also very hard to implement
since the class name is decided by the Java compiler.</p>
  +                
  +            </subsection>
  +            
  +            <subsection name="I want to add a constant value as an attribute.">
  +                
  +                <p>So you have this</p>
  +                
  +                <source><![CDATA[public class Values {
  +    public static final Integer ONE = new Integer (1);
  +}]]></source>
  +                
  +                <p>and now you'd like to add ONE as an attribute like this:</p>
  +                
  +                <source><![CDATA[/**
  + * @@Values.ONE
  + */
  +public class MyClass { ... }</pre></blockquote>
  +        
  +        <p>how can this be done?</p>
  +        
  +        <p>The best that can be offered is:</p>
  +        
  +        <source><![CDATA[/**
  + * @@Integer(Values.ONE)
  + */
  +public class MyClass { ... }]]></source>
  +                
  +                <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>
  +                
  +                <source><![CDATA[public class One {}]]></source>
  +                
  +                <p>and use it.</p>
  +            </subsection>
           </section>
       </body>
       
  
  
  

---------------------------------------------------------------------
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