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 maven_demo.xml walkthrough.xml navigation.xml tutorial.xml
Date Thu, 04 Mar 2004 00:39:17 GMT
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


Mime
View raw message