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 tutorial.xml index.xml navigation.xml
Date Wed, 03 Mar 2004 22:32:19 GMT
leosutic    2004/03/03 14:32:19

  Modified:    attributes project.xml
               attributes/site/xdocs index.xml navigation.xml
  Added:       attributes/site/xdocs tutorial.xml
  Log:
  Improved documentation.
  
  Revision  Changes    Path
  1.12      +6 -47     jakarta-commons-sandbox/attributes/project.xml
  
  Index: project.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/attributes/project.xml,v
  retrieving revision 1.11
  retrieving revision 1.12
  diff -u -r1.11 -r1.12
  --- project.xml	21 Feb 2004 16:13:41 -0000	1.11
  +++ project.xml	3 Mar 2004 22:32:19 -0000	1.12
  @@ -17,58 +17,17 @@
   =
   -->
   <project>
  -  <extend>../sandbox-build/project.xml</extend>
  -  <name>Attributes</name>
  -  <id>commons-attributes</id>
  -  
  -  <logo><!--/images/logo.png--></logo>
  -  
  -  <currentVersion>2.0alpha</currentVersion>
  -  <inceptionYear>2003</inceptionYear>
  -  <shortDescription>Commons Attributes</shortDescription>
  -  <description>A package for handling runtime information about types (including
Java classes)</description>
  -  
  -
  -<!-- REMOVED TO MAKE STANDARD BUILD
  -    <pomVersion>3</pomVersion>
  -    <groupId>commons-attributes</groupId>
  -    <name>Jakarta Commons Attributes</name>
  +    <extend>../sandbox-build/project.xml</extend>
  +    <name>Attributes</name>
  +    <id>commons-attributes</id>
  +    
       <logo>/attributes-logo.gif</logo>
       
       <currentVersion>2.0alpha</currentVersion>
  -    
  -    <organization>
  -        <name>Apache Software Foundation</name>
  -        <url>http://jakarta.apache.org/</url>
  -        <logo>http://jakarta.apache.org/images/jakarta-logo-blue.gif</logo>
  -    </organization>
  -    
       <inceptionYear>2003</inceptionYear>
  +    <shortDescription>Commons Attributes</shortDescription>
  +    <description>A package for handling runtime information about types (including
Java classes)</description>
       
  -    <package></package>
  -    <gumpRepositoryId>jakarta-commons-sandbox</gumpRepositoryId>
  -    
  -    <url>http://jakarta.apache.org/commons/sandbox/attributes/index.html</url>
  -    <issueTrackingUrl>http://nagoya.apache.org/</issueTrackingUrl>
  -
  -    <siteAddress>jakarta.apache.org</siteAddress>
  -    <siteDirectory>/www/jakarta.apache.org/commons/sandbox/attributes</siteDirectory>
  -    <distributionDirectory>/www/jakarta.apache.org/builds/jakarta-commons-sandbox/attributes/</distributionDirectory>
  -    
  -    <repository>
  -        <connection>scm:cvs:pserver:anoncvs@cvs.apache.org:/home/cvspublic:jakarta-commons-sandbox/attributes</connection>
  -        <url>http://cvs.apache.org/viewcvs/jakarta-commons-sandbox/attributes/</url>
  -    </repository>
  -    
  -    <mailingLists>
  -        <mailingList>
  -            <name>Jakarta Commons Developer List</name>
  -            <subscribe>commons-dev-subscribe@jakarta.apache.org</subscribe>
  -            <unsubscribe>commons-dev-unsubscribe@jakarta.apache.org</unsubscribe>
  -            <archive>http://nagoya.apache.org/eyebrowse/SummarizeList?listName=commons-dev@jakarta.apache.org</archive>
  -        </mailingList>
  -    </mailingLists>
  --->
       <developers>
           <developer>
               <name>Leo Sutic</name>
  
  
  
  1.9       +33 -8     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.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- index.xml	19 Feb 2004 14:49:14 -0000	1.8
  +++ index.xml	3 Mar 2004 22:32:19 -0000	1.9
  @@ -20,7 +20,7 @@
   
       <properties>
           <author email="leosutic@apache.org">Leo Sutic</author>
  -        <title>Jakarta Commons Attributes</title>
  +        <title>Overview</title>
       </properties>
   
       <body>
  @@ -35,11 +35,35 @@
               </p>
           </section>
           
  -        <section name="Download and Install">
  -            <p>
  -                You can grab the snapshot jars here:
  -            </p>
  +        <section name="Download and Installation">
  +            
  +            <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>
               
  +            <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>
  @@ -52,9 +76,9 @@
                   </li>
               </ul>
               
  -            <p>Drop the client API and the ant task jars into your ${maven repository}/commons-attributes/jars/
directory, and the
  -                maven plugin in your ${maven home}/plugins/ directory. You can now use
attributes in your Java code, provided that
  -                you declare a dependency on the client API:</p>
  +            <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>
  @@ -65,6 +89,7 @@
               
               <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">
  
  
  
  1.3       +14 -17    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.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- navigation.xml	19 Feb 2004 14:49:14 -0000	1.2
  +++ navigation.xml	3 Mar 2004 22:32:19 -0000	1.3
  @@ -17,21 +17,18 @@
   =
   -->
   <project>
  -
  - <title>Jakarta Commons Attributes</title>
  -
  - <body>
  -
  -    <links>
  -      <item name="Home" href="http://jakarta.apache.org/"/>
  -      <item name="Jakarta Commons" href="http://jakarta.apache.org/commons/"/>
  -    </links>
  -
  -    <menu name="About Commons Attributes">
  -      <item name="Overview" href="/index.html"/>
  -      <item name="API" href="/api/index.html"/>
  -    </menu>
  -
  - </body>
  -
  +    <title>Jakarta Commons Attributes</title>
  +    
  +    <body>
  +        <links>
  +            <item name="Home" href="http://jakarta.apache.org/"/>
  +            <item name="Jakarta Commons" href="http://jakarta.apache.org/commons/"/>
  +        </links>
  +        
  +        <menu name="About Commons Attributes">
  +            <item name="Overview" href="/index.html"/>
  +            <item name="API" href="/api/index.html"/>
  +            <item name="Tutorial" href="/tutorial.html"/>
  +        </menu>
  +    </body>
   </project>
  
  
  
  1.1                  jakarta-commons-sandbox/attributes/site/xdocs/tutorial.xml
  
  Index: tutorial.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</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">
              
              <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>
              
              <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>
                  <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>Maven plugin: <a href="http://cvs.apache.org/~leosutic/commons-attributes-plugin-2.0alpha.jar">commons-attributes-plugin-2.0alpha.jar</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>
  
  
  

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