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/04 01:39:17 UTC
cvs commit: jakarta-commons-sandbox/attributes/site/xdocs ant_demo.xml maven_demo.xml walkthrough.xml navigation.xml tutorial.xml
leosutic 2004/03/03 16:39:17
Modified: attributes/site/xdocs navigation.xml tutorial.xml
Added: attributes/site/xdocs ant_demo.xml maven_demo.xml
walkthrough.xml
Log:
Improved documentation.
Revision Changes Path
1.4 +5 -1 jakarta-commons-sandbox/attributes/site/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/attributes/site/xdocs/navigation.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- navigation.xml 3 Mar 2004 22:32:19 -0000 1.3
+++ navigation.xml 4 Mar 2004 00:39:17 -0000 1.4
@@ -28,7 +28,11 @@
<menu name="About Commons Attributes">
<item name="Overview" href="/index.html"/>
<item name="API" href="/api/index.html"/>
- <item name="Tutorial" href="/tutorial.html"/>
+ <item name="Tutorial" href="/tutorial.html">
+ <item name="Ant Demo" href="/ant_demo.html"/>
+ <item name="Maven Demo" href="/maven_demo.html"/>
+ <item name="Walkthrough" href="/walkthrough.html"/>
+ </item>
</menu>
</body>
</project>
1.2 +16 -191 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- tutorial.xml 3 Mar 2004 22:32:19 -0000 1.1
+++ tutorial.xml 4 Mar 2004 00:39:17 -0000 1.2
@@ -17,212 +17,37 @@
=
-->
<document>
-
+
<properties>
<author email="leosutic@apache.org">Leo Sutic</author>
<title>Tutorial</title>
</properties>
-
+
<body>
-
-
-
- <section name="Tutorial">
- <p>
- Commons Attributes enables Java programmers to use C#/.Net-style
- attributes in their code.
-
- Please see the Javadoc overview for a thorough explanation of the features
- and how the project integrates into the development process.
- </p>
- </section>
-
- <section name="Download and Installation">
+ <section name="About this Tutorial">
- <subsection name="Ant Users">
- <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>
- </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>
- </subsection>
+ <p>This tutorial will walk you through Commons Attributes. The tutorial is split into
+ two parts: First, a quick demo of the package, and second, a walkthrough of all features.</p>
- <subsection name="Maven Users">
-
- <p>
- Download the following files:
- </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>
- </li>
+ <p>
+ <a href="ant_demo.html">Ant demo</a>
+ </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>
+ <p>
+ <a href="maven_demo.html">Maven demo</a>
+ </p>
</li>
<li>
- <p>Maven plugin: <a href="http://cvs.apache.org/~leosutic/commons-attributes-plugin-2.0alpha.jar">commons-attributes-plugin-2.0alpha.jar</a></p>
+ <p>
+ <a href="walkthrough.html">Walkthrough</a>
+ </p>
</li>
</ul>
-
- <p>Drop the <code>-api</code> and <code>-compiler</code> jars into your <code>${maven repository}/commons-attributes/jars/</code>
- directory, and the Maven <code>-plugin</code> in your <code>${maven home}/plugins/</code> directory.
- You can now use attributes in your Java code, provided that you declare a dependency on the client API:</p>
-
- <source><![CDATA[<dependency>
- <groupId>commons-attributes</groupId>
- <artifactId>commons-attributes-api</artifactId>
- <version>SNAPSHOT</version>
-</dependency>]]></source>
-
-
- <p>The attribute compiler will act as a precompiler to the java:compile goal, so you do not need to do
- anything else.</p>
- </subsection>
- </section>
-
- <section name="A Quick Sample">
-
- <p>
- Commons Attributes enables you to add attributes to your code:
- </p>
-
- <source><![CDATA[
-/**
- * Make this attribute inheritable...
- *
- * @@Inheritable()
- */
-public class MyAttribute {
- private final float value;
-
- public MyAttribute( float value ) {
- this.value = value;
- }
-
- public float getValue() {
- return value;
- }
-}
-
-/**
- * Add a Myattribute with value 0.8.
- *
- * @@MyAttribute( 0.8 )
- */
-public class MyClass {
- public static void main( String[] args ) {
- System.out.println( "MyClass has the following attributes:" +
- Attributes.getAttributes( MyClass.class ) );
- }
-}]]></source>
-
- <p>
- As the example shows, the attributes are type-safe and provides for validation
- of values.
- </p>
-
</section>
- <section name="Features">
-
- <table>
- <tr>
- <td>Can add attributes to classes</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>Can add attributes to nested classes</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>Can add attributes to methods and constructors</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>Can add attributes to return values of methods</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>Can add attributes to method parameters</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>Can add attributes to fields</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>Type safe attributes</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>Attribute inheritance</td>
- <td>Yes, add the @@Inheritable() attribue to any attribute you wish to be inheritable.</td>
- </tr>
- <tr>
- <td>Inheritance without access to superclass source code</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>Named parameters in attribute declaration</td>
- <td>Yes, corresponds to setter methods. A Sealable interface enables the instance to
- become read-only when all relevant setters have been called.</td>
- </tr>
- <tr>
- <td>Ability to quickly find all classes with a specific attribute</td>
- <td>Yes, via attribute indexes.</td>
- </tr>
- <tr>
- <td>Ant task</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>Maven plugin</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>Object attributes don't have to be serializable</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>Multiple attributes with same tag on an element</td>
- <td>Yes, this is controlled by the attribute itself</td>
- </tr>
- <tr>
- <td>Incremental compilation</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>Attribute storage</td>
- <td>Generated classes</td>
- </tr>
- <tr>
- <td>Runtime code size</td>
- <td>21kB</td>
- </tr>
- <tr>
- <td>Unit test coverage</td>
- <td>Excellent</td>
- </tr>
- </table>
-
- </section>
-
-
-
</body>
-
+
</document>
1.1 jakarta-commons-sandbox/attributes/site/xdocs/ant_demo.xml
Index: ant_demo.xml
===================================================================
<?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="leosutic@apache.org">Leo Sutic</author>
<title>Tutorial - Ant Demo</title>
</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>
</body>
</document>
1.1 jakarta-commons-sandbox/attributes/site/xdocs/maven_demo.xml
Index: maven_demo.xml
===================================================================
<?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="leosutic@apache.org">Leo Sutic</author>
<title>Tutorial - Maven Demo</title>
</properties>
<body>
<section name="About This Demo">
<p>
This is a quick demo that shows how to use attributes together with
Maven. 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>
</body>
</document>
1.1 jakarta-commons-sandbox/attributes/site/xdocs/walkthrough.xml
Index: walkthrough.xml
===================================================================
<?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="leosutic@apache.org">Leo Sutic</author>
<title>Tutorial - Walkthrough</title>
</properties>
<body>
<section name="What are Attributes?">
<p>Attributes are value objects that can be added to language elements such as
classes, methods and fields.</p>
<subsection name="Value Objects">
<p>What is a value object? Simply stated, a value object is an object that is
read-only, constant and can be replaced with another object of the same value
without it making any difference. For example, instances of the class
<code>java.lang.Integer</code> are value objects. You can replace any instance
of that class with any other instance, provided that they are equal. An
<code>java.io.Socket</code> is not a value object, as you can't replace an
instance of a socket with another - it corresponds to a real resource, in
this case a connection.</p>
<p>You should therefore not allow your attribute classes to be mutable, and not
use Sockets or similar classes as attributes.</p>
</subsection>
</section>
<section name="How Are They Added?">
<p>Let's look at the way attributes are added to the code. The general form of the
attribute expression is (optional parts are in [brackets]):</p>
<source><![CDATA[@@[target] ClassName ([constructor args] [named args])]]></source>
<subsection name="target">
<p>This name indicates what sub-element the attribute is to be applied to.
Classes and fields have no sub-elements, but methods do. The sub-elements
of a method are (1) the arguments and (2) the return value. In order to
apply an element to a method argument, you let the target be <code>.argument name</code>.
For example:</p>
<source><![CDATA[/**
* @@.arg1 MyAttribute()
*/
public Object myMethod (int arg1) { ... }]]></source>
<p>Will attach MyAttribute to the first argument of the method - not to
the method itself. The attribute can be retrieved via
<code>Attributes.getParameterAttributes(Method,int)</code>.</p>
<p>Adding an attribute to the return value is done by the reserved target
name <code>.return</code>:</p>
<source><![CDATA[/**
* @@.return MyAttribute()
*/
public Object myMethod (int arg1) { ... }]]></source>
<p>The attribute can then be retrieved via <code>Attributes.getReturnAttributes(Method)</code>.</p>
</subsection>
<subsection name="ClassName">
<p>This is the name of the attribute class. You can use a qualified or
unqualified name here - but if you use the unqualified name you must
import the class (unless it is in the same package as the class you
are adding attributes to).</p>
</subsection>
<subsection name="constructor args">
<p>
This is simply a list of arguments to pass to the constructor when
instantiating the attribute class. For example, given an attribute:</p>
<source><![CDATA[class MyAttribute {
private final String name;
public MyAttribute(String name) { this.name = name };
public String getName() { return name; }
}]]></source>
<p>You would specify the name by including it as a constructor argument:</p>
<source><![CDATA[/**
* @@MyAttribute("this is a name")
*/]]></source>
</subsection>
<subsection name="named arguments">
<p>Commons Attributes provides a simple way of having named arguments.
This is done by having setter metods in the attribute class. Adding a
field and two methods to the attribute class above we get:</p>
<source><![CDATA[class MyAttribute {
private final String name;
private boolean optional = false;
public MyAttribute(String name) { this.name = name };
public String getName() { return name; }
public boolean isOptional { return optional; }
public void setOptional (boolean optional) { this.optional = optional; }
}]]></source>
<p>We can now set the <code>optional</code> field by using a named parameter:</p>
<source><![CDATA[/**
* @@MyAttribute("this is a name", optional=true)
*/]]></source>
<p>The attribute compiler will pass any parameter up to the first one that is
on the form <code><i>name</i> = <i>expression</i></code> to the constructor.
For the remaining parameters, it will invoke a method named
<code>setName(expression)</code> on the attribute instance.
So for our example above, the following code will be generated:</p>
<source><![CDATA[MyAttribute attr = new MyAttribute("this is a name");
attr.setOptional(true);]]></source>
<p>Named parameters are always optional.</p>
</subsection>
</section>
<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>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org