Commons Attributes example source code file (ant_demo.xml)
The Commons Attributes ant_demo.xml source code
<?xml version="1.0"?>
<!--
=
= 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.
=
-->
<document>
<properties>
<author email="commons-dev@jakarta.apache.org">Jakarta Commons Development Team
<title>Tutorial - Ant Demo
</properties>
<body>
<section name="About This Demo">
<p>
This is a quick demo that shows how to use attributes together with
Ant. Don't worry about 90% here seemingly being pure unexplainable
magic - the purpose of this part of the tutorial is to show you
what steps you must do to make the Commons Attributes package work.
In the walkthrough we'll focus more on just what happens, and how
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 directory:
</p>
<ul>
<li>
<p>Client API: commons-attributes-api-2.2.jar
<p>
<i>It is important that you do not rename this file - it is referred to by name in the example build.xml.
</p>
</li>
<li>
<p>Ant task: commons-attributes-compiler-2.2.jar
<p>
<i>It is important that you do not rename this file - it is referred to by name in the example build.xml.
</p>
</li>
<li>
<p>qDox 1.5: qdox-1.5.jar
</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: build.xml
</li>
<li>
<p>Java source file: AttributeDemo.java
</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>
<p>
If you have JDK 1.4 or later, you can also generate Javadocs for the demo
with attribute information in the docs:
</p>
<source>
<p>
Look in the javadoc/ subdirectory for the results.
</p>
</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>
<p>This is simply the definition of an attribute class. It takes one constructor
argument, and has one named argument.</p>
<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, and will result in the
<code>setNamedArgument method being called.
</p>
<source>
<p>
This is where we access the attributes. The <code>Attributes.getAttributes
method returns a Collection of all attributes attached to the <code>AttributeDemo
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>|Generated Java Files|
+------------+ +--------------------+
| |
| |
| +-------------+ |
+-------------->|Java Compiler|<------------------+
+-------------+
|
v
+-----------------+
|Java .class files|
+-----------------+]]></source>
<p>
We must therefore invoke the Attribute Compiler before compiling the sources.
</p>
<source>
<taskdef resource="org/apache/commons/attributes/anttasks.properties"/>]]>
<p>
Nothing special here. We define the Ant tasks provided by the
commons-attributes compiler.
</p>
<source>
<delete>
<fileset dir="${basedir}" includes="*.class,*$*"/>
</delete>
</target>]]>
<p>
Again nothing special. Just a convenience target to clean up all
generated files. But after that comes:
</p>
<source>
<attribute-compiler destdir=".">
<fileset dir="." includes="*.java"/>
</attribute-compiler>
</target>]]>
<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 (autogenerated .java files) for all existing .java files.
When those files are generated, we go on to compile everything:
</p>
<source>
<javac
srcdir="."
destdir="${basedir}"
deprecation="true"
debug="true"
classpath="${ant.home}/lib/commons-attributes-api-2.2.jar;."
optimize="false">
</javac>
</target>]]>
<p>
Since we use attributes, we have to include the commons-attributes-api-2.2.jar file in the classpath.
</p>
<source>
<java
classpath="${ant.home}/lib/commons-attributes-api-2.2.jar;."
classname="AttributeDemo"/>
</target>]]>
<p>
This target simply runs the compiled demo class. JDK 1.4 users can in addition to this generate
Javadocs:
</p>
<source>
<mkdir dir="${basedir}/javadoc/"/>
<javadoc
destdir="${basedir}/javadoc/"
additionalparam="-J-Dorg.apache.commons.attributes.javadoc.CATaglet.sources=${basedir}">
<taglet
name="org.apache.commons.attributes.javadoc.CATaglet"
path="${ant.home}/lib/commons-attributes-compiler-2.2.jar"
/>
<fileset dir="${basedir}/" includes="**/*.java" />
</javadoc>
</target>]]>
<p>
See <a href="documenting.html">Documenting for a walkthrough of the Javadoc
Taglet.
</p>
<source>
]]></source>
</subsection>
</section>
</body>
</document>
Other Commons Attributes examples (source code examples)Here is a short list of links related to this Commons Attributes ant_demo.xml source code file: |
The search page
Other Commons Attributes source code examples at this package level
Click here to learn more about this project
