You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by le...@apache.org on 2004/03/19 00:16:30 UTC
cvs commit: jakarta-commons-sandbox/attributes/site/xdocs ant_demo.xml index.xml maven_demo.xml tutorial.xml walkthrough.xml
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