commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rdon...@apache.org
Subject cvs commit: jakarta-commons/betwixt/xdocs faq.xml
Date Wed, 12 Jun 2002 21:40:06 GMT
rdonkin     2002/06/12 14:40:06

  Modified:    betwixt/src/java/org/apache/commons/betwixt XMLBeanInfo.java
               betwixt/src/java/org/apache/commons/betwixt/io
                        BeanWriter.java CyclicReferenceException.java
                        IDGenerator.java package.html
               betwixt/src/java/org/apache/commons/betwixt/io/id
                        AbstractIDGenerator.java RandomIDGenerator.java
                        SequentialIDGenerator.java package.html
               betwixt/xdocs faq.xml
  Log:
  Improved documentation related to ID generation.
  
  Revision  Changes    Path
  1.2       +43 -5     jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/XMLBeanInfo.java
  
  Index: XMLBeanInfo.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/XMLBeanInfo.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- XMLBeanInfo.java	10 Jun 2002 17:53:34 -0000	1.1
  +++ XMLBeanInfo.java	12 Jun 2002 21:40:06 -0000	1.2
  @@ -67,6 +67,14 @@
     * which can be customized through some mechansim, either via Java code 
     * or XSLT for example.</p>
     *
  +  * <h4><code>ID</code> and <code>IDREF</code> Attribute
Names</h4>
  +  * <p>These special attributes are defined in the xml specification.
  +  * They are used by Betwixt to write bean graphs with cyclic references.
  +  * In most cases, these will take the values 'id' and 'idref' respectively 
  +  * but these names can be varied in the DTD.
  +  * Therefore, these names are specified by this class but default to the
  +  * usual values.</p>
  +  *
     * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
     * @version $Revision$
     */
  @@ -143,22 +151,52 @@
           return null;
       }
       
  -    /** Get name of <code>ID</code> attribute */
  +    /** 
  +      * <p>Get name of <code>ID</code> attribute.
  +      * This is used to write (for example) automatic <code>ID</code>
  +      * attribute values.</p>
  +      * 
  +      * <p>The default name is 'id'.</p>
  +      *
  +      * @return name for the special <code>ID</code> attribute
  +      */
       public String getIDAttributeName() {
           return idAttributeName;
       }
  -    /** Set name of <code>ID</code> attribute */
  +    /** 
  +      * Set name of <code>ID</code> attribute 
  +      * This is used to write (for example) automatic <code>ID</code>
  +      * attribute values.</p>
  +      * 
  +      * <p>The default name is 'id'.</p>
  +      *
  +      * @param idAttributeName the attribute name for the special <code>ID</code>
attribute
  +      */
       public void setIDAttributeName(String idAttributeName) {
           this.idAttributeName = idAttributeName;
       }
       
  -    /** Get <code>IDREF</code> attribute name */
  +    /** 
  +      * <p>Get <code>IDREF</code> attribute name 
  +      * This is used (for example) to deal with cyclic references.
  +      *
  +      * <p>The default name is 'idref'.</p>
  +      *
  +      * @return name for the special <code>IDREF</code> attribute
  +      */
       public String getIDREFAttributeName() {
           return idrefAttributeName;
       }
       
  -    /** Set <code>IDREF</code> attribute name */
  -    public void setIDREFAttributeName() {
  +    /** 
  +      * Set <code>IDREF</code> attribute name 
  +      * This is used (for example) to deal with cyclic references.
  +      *
  +      * <p>The default name is 'idref'.</p>
  +      *
  +      * @param idrefAttributeName the attribute name for the special <code>IDREF</code>
attribute
  +      */
  +    public void setIDREFAttributeName(String idrefAttributeName) {
           this.idrefAttributeName = idrefAttributeName;
       }
   }
  
  
  
  1.3       +14 -4     jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/BeanWriter.java
  
  Index: BeanWriter.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/BeanWriter.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- BeanWriter.java	11 Jun 2002 16:05:21 -0000	1.2
  +++ BeanWriter.java	12 Jun 2002 21:40:06 -0000	1.3
  @@ -82,8 +82,9 @@
   import org.apache.commons.betwixt.io.id.SequentialIDGenerator;
   
   
  -/** <p><code>BeanWriter</code> output beans as XML.</p>
  -  * The output for each bean is an xml fragment
  +/** <p><code>BeanWriter</code> outputs beans as XML to an io stream.</p>
  +  *
  +  * <p>The output for each bean is an xml fragment
     * (rather than a well-formed xml-document).
     * This allows bean representations to be appended to a document 
     * by writing each in turn to the stream.
  @@ -348,12 +349,21 @@
           this.indent = indent;
       }
       
  -    /** Get IDGenerator used to generate ID attribute values */
  +    /** 
  +      * Get <code>IDGenerator</code> implementation used to generate <code>ID</code>
attribute values .
  +      *
  +      * @return implementation used for <code>ID</code> attribute generation
  +      */
       public IDGenerator getIdGenerator() {
           return idGenerator;
       }
       
  -    /** Set IDGenerator used to generate ID attribute values */
  +    /** 
  +      * Set <code>IDGenerator</code> implementation used to generate <code>ID</code>
attribute values.
  +      * This property can be used to customize the algorithm used for generation.
  +      *
  +      * @param idGenerator use this implementation for <code>ID</code> attribute
generation
  +      */
       public void setIdGenerator(IDGenerator idGenerator) {
           this.idGenerator = idGenerator;
       }
  
  
  
  1.2       +11 -0     jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/CyclicReferenceException.java
  
  Index: CyclicReferenceException.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/CyclicReferenceException.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- CyclicReferenceException.java	10 Jun 2002 17:53:32 -0000	1.1
  +++ CyclicReferenceException.java	12 Jun 2002 21:40:06 -0000	1.2
  @@ -64,6 +64,17 @@
   /**
     * <p>Thrown when bean evaluation finds a cycle reference.</p>
     *
  +  * <p>There are two possible behaviours that <code>Betwixt</code> adopts
when 
  +  * a cycle in the object graph is encountered.
  +  *
  +  * <p>If <code>ID</code> attributes are being generated, 
  +  * then the recursion will stop and the <code>IDREF</code> attribute will
be
  +  * written. 
  +  * In this case, <em>no exception will be thrown</em>.</p>
  +  *
  +  * <p>If <code>ID</code> are <strong>not</strong> being
generated, 
  +  * then this exception will be thrown.</p>
  +  *
     * @author <a href="mailto:rdonkin@apache.org">Robert Burrell Donkin</a>
     * @version $Revision$
     */
  
  
  
  1.2       +11 -4     jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/IDGenerator.java
  
  Index: IDGenerator.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/IDGenerator.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- IDGenerator.java	10 Jun 2002 17:53:32 -0000	1.1
  +++ IDGenerator.java	12 Jun 2002 21:40:06 -0000	1.2
  @@ -62,20 +62,27 @@
   package org.apache.commons.betwixt.io;
   
   
  -/** <p>Interface allowing pluggable <code>ID</code> generators.</p>
  +/** <p>Interface allowing pluggable <code>ID</code> attribute value generators.</p>
     *
     * <p> <code>IDGenerator</code>'s are used to generate <code>ID</code>
     * attribute values by <code>BeanWriter</code>. 
  -  * Generators have been created that supply random and sequantial values.</p>
  +  * A user can specify the generation mechanism by passing an implementation to 
  +  * {@link BeanWriter#setIdGenerator}.</p>
  +  *
  +  * <p>Standard implementations are included with that supply random and sequantial
values.</p>
     *
     * @author <a href="mailto:rdonkin@apache.org">Robert Burrell Donkin</a>
     * @version $Revision$
     */
   public interface IDGenerator {
       
  -    /** Get the last id produced */
  +    /** 
  +      * Get the last <code>ID</code> value generated.
  +      */
       public int getLastId();
       
  -    /** Generate id */
  +    /** 
  +      * Generate a new  <code>ID</code> attribute value.
  +      */
       public int nextId();
   }
  
  
  
  1.2       +4 -4      jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/package.html
  
  Index: package.html
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/package.html,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- package.html	10 Jun 2002 17:53:32 -0000	1.1
  +++ package.html	12 Jun 2002 21:40:06 -0000	1.2
  @@ -3,10 +3,10 @@
   </head>
   <body>
   
  -  <p>This package is home to writers which render objects into xml using 
  -  the <code>betwixt</code> introspection system.
  -  At the moment, the xml can only be written to output streams.
  -  </p>
  +  <p>Package contains classes dealing directly with the reading and writing of beans.</p>
     
  +  <p>These classes use the <code>Betwixt</code> introspection system
to determine how a
  +  bean should be mapped to xml. 
  +  The xml->object reader uses <code>Digester</code> to implement the mapping.</p>
   </body>
   </html>
  
  
  
  1.2       +21 -7     jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/id/AbstractIDGenerator.java
  
  Index: AbstractIDGenerator.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/id/AbstractIDGenerator.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- AbstractIDGenerator.java	10 Jun 2002 17:53:34 -0000	1.1
  +++ AbstractIDGenerator.java	12 Jun 2002 21:40:06 -0000	1.2
  @@ -63,29 +63,43 @@
   
   import org.apache.commons.betwixt.io.IDGenerator;
   
  -/** <p> Abstract superclass for id generator implementations.
  -  * Provides utility methods that store the last id generated.
  -  * Sub class should override {@link #nextIdImpl}.</p>
  +/** <p>Abstract superclass for {@link IDGenerator} implementations.</p>
  +  *
  +  * <p>It implements the entire <code>IDGenerator</code> interface.
  +  * When <code>nextId</code> is called, 
  +  * this class sets the <code>LastId</code> property (as well
  +  * as returning the value).
  +  * Subclasses should override {@link #nextIdImpl}.</p>
     *
     * @author <a href="mailto:rdonkin@apache.org">Robert Burrell Donkin</a>
     * @version $Revision$
     */
   public abstract class AbstractIDGenerator implements IDGenerator {
       
  -    /** Last id returned */
  +    /** Last <code>ID</code> returned */
       private int lastId = 0;
       
  -    /** Get last if implementation */
  +    /** Get last <code>ID</code> returned. */
       public final int getLastId() {
           return lastId;
       }
       
  -    /** Generate next id */
  +    /** 
  +      * <p>Generate next <code>ID</code>.</p>
  +      *
  +      * <p>This method obtains the next <code>ID</code> from subclass
  +      * and then uses this to set the <code>LastId</code> property.</p>
  +      */
       public final int nextId() {
           lastId = nextIdImpl();
           return lastId;
       }
       
  -    /** Subclasses overried this method */
  +    /** 
  +      * Subclasses should <strong>provide an implementation</strong> for this
method.
  +      * This implementation needs only provide the next <code>ID</code>
  +      * value (according to it's algorithm).
  +      * Setting the <code>LastId</code> property can be left to this class.
  +      */
       protected abstract int nextIdImpl();
   }
  
  
  
  1.2       +30 -7     jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/id/RandomIDGenerator.java
  
  Index: RandomIDGenerator.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/id/RandomIDGenerator.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- RandomIDGenerator.java	10 Jun 2002 17:53:34 -0000	1.1
  +++ RandomIDGenerator.java	12 Jun 2002 21:40:06 -0000	1.2
  @@ -63,9 +63,20 @@
   
   import java.util.Random;
   
  -/** <p>Generates random ids.
  -  * This class can generate positive-only ids (the default)
  +/** <p>Generates <code>ID</code>'s at random.
  +  * The random number source is <code>java.util.Random</code>.</p>
  +  *
  +  * <p>Random <code>ID</code>'s are very useful if you're inserting 
  +  * elements created by <code>Betwixt</code> into a stream with existing
  +  * elements.
  +  * Using random <code>ID</code>'s should reduce the danger of collision
  +  * with existing element <code>ID</code>'s.</p>
  +  * 
  +  * <p>This class can generate positive-only ids (the default)
     * or it can generate a mix of negative and postive ones.
  +  * This behaviour can be set by {@link #setPositiveIds} 
  +  * or by using the {@link #RandomIDGenerator(boolean onlyPositiveIds)} 
  +  * constructor.</p>
     *
     * @author <a href="mailto:rdonkin@apache.org">Robert Burrell Donkin</a>
     * @version $Revision$
  @@ -77,15 +88,27 @@
       /** Should only positive id's be generated? */
       private boolean onlyPositiveIds = true;
           
  -    /** Base constructor */
  +    /** 
  +      * Constructor sets the <code>PositiveIds</code> property to <code>true</code>.
  +      */
       public RandomIDGenerator() {} 
       
  -    /** Construct sets PositiveIds property */
  +    /** 
  +      * Constructor sets <code>PositiveIds</code> property.
  +      *
  +      * @param onlyPositiveIds set <code>PositiveIds</code> property to this
value
  +      */
       public RandomIDGenerator(boolean onlyPositiveIds) {
           setPositiveIds(onlyPositiveIds);
       }
       
  -    /** Next id implementation */
  +    /** 
  +      * <p>Provide a random <code>ID</code><p>
  +      * 
  +      * <p>If the <code>PositiveIds</code> property is true, 
  +      * then this method will recursively call itself if the random
  +      * <code>ID</code> is less than zero.</p>
  +      */
       public int nextIdImpl() {
           int next = random.nextInt();
           if (onlyPositiveIds && next<0) {
  @@ -95,12 +118,12 @@
           return next;
       }
       
  -    /** Get whether only positive id's should be generated */
  +    /** Get whether only positive <code>ID</code>'s should be generated */
       public boolean getPositiveIds() {
           return onlyPositiveIds;
       }
       
  -    /** Set whether only positive id's should be generated */
  +    /** Set whether only positive <code>ID</code>'s should be generated */
       public void setPositiveIds(boolean onlyPositiveIds) {
           this.onlyPositiveIds = onlyPositiveIds;
       }
  
  
  
  1.2       +29 -6     jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/id/SequentialIDGenerator.java
  
  Index: SequentialIDGenerator.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/id/SequentialIDGenerator.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- SequentialIDGenerator.java	10 Jun 2002 17:53:34 -0000	1.1
  +++ SequentialIDGenerator.java	12 Jun 2002 21:40:06 -0000	1.2
  @@ -62,30 +62,53 @@
   package org.apache.commons.betwixt.io.id;
   
   
  -/** <p>This simply uses a counting mechanism to assign id's</p>
  +/** <p>Generates <code>ID</code>'s in numeric sequence.
  +  * A simple counter is used.
  +  * Every time that {@link #nextIdImpl} is called, 
  +  * this counter is incremented.</p>
  +  *
  +  * <p>By default, the counter starts at zero.
  +  * A user can set the initial value by using the 
  +  * {@link #SequentialIDGenerator(int start)} constructor.</p>
     *
     * @author <a href="mailto:rdonkin@apache.org">Robert Burrell Donkin</a>
     * @version $Revision$
     */
   public final class SequentialIDGenerator extends AbstractIDGenerator {
       
  -    /** Counter used to assign id's */
  +    /** Counter used to assign <code>ID</code>'s */
       private int counter = 0;
           
  -    /** Base constructor */
  +    /** 
  +      * Base constructor.
  +      * Counter starts at zero.
  +      */
       public SequentialIDGenerator() {} 
       
  -    /** Set the start value for the sequence */
  +    /** 
  +     * Constructor sets the start value for the counter.
  +     * 
  +     * <p><strong>Note</strong> since the counter increments
  +     * before returning the next value, 
  +     * first <code>ID</code> generated will be <em>one more</em>
  +     * than the given <code>start</code> parameter.</p>
  +     * 
  +     * @param start start the counting at this value
  +     */
       public SequentialIDGenerator(int start) {
           this.counter = start;
       }
       
  -    /** Next id implementation */
  +    /** 
  +      * Increment counter and then return value.
  +      */
       public int nextIdImpl() {
           return ++counter;
       }
       
  -    /** Get the current counter value */
  +    /** 
  +      * Get the current counter value 
  +      */
       public int getCount() {
           return counter;
       }
  
  
  
  1.2       +14 -3     jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/id/package.html
  
  Index: package.html
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/id/package.html,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- package.html	10 Jun 2002 17:53:34 -0000	1.1
  +++ package.html	12 Jun 2002 21:40:06 -0000	1.2
  @@ -3,8 +3,19 @@
   </head>
   <body>
   
  -  <p>This package is home to <code>IDGenerator</code> implementations.
  -  </p>
  -  
  +    <p>This package is home to <code>IDGenerator</code> implementations.
  +    </p>
  +    
  +    <p><code>Betwixt</code> can generate <code>ID</code>
and <code>IDREF</code>
  +    attributes for the elements it creates.
  +    By setting the IDGenerator property on the bean writer, a user can customize
  +    the algorithm used to generate these id's.
  +    </p>
  +    <p>
  +    This package contains the standard implementations of <code>IDGenerator</code>

  +    that ship with <code>Betwixt</code>.
  +    Users who want to create their own implementations can use these classes 
  +    as examples.
  +    </p>
   </body>
   </html>
  
  
  
  1.2       +85 -0     jakarta-commons/betwixt/xdocs/faq.xml
  
  Index: faq.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/xdocs/faq.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- faq.xml	10 Jun 2002 17:53:32 -0000	1.1
  +++ faq.xml	12 Jun 2002 21:40:06 -0000	1.2
  @@ -35,6 +35,29 @@
           </a>
         </li>
       </ol>
  +    <p><strong>Writing Beans</strong></p>
  +    <ol>
  +      <li>
  +        <a href="#output-options">
  +          In what forms can Betwixt output the xml?
  +        </a>
  +      </li>
  +      <li>
  +        <a href="#pretty-print">
  +          Can <code>BeanWriter</code> produce xml that's easy (for a human
;) to read?
  +        </a>
  +      </li>
  +      <li>
  +        <a href="#cycles">
  +          How does Betwixt cope with beans which have cyclic reference graphs?
  +        </a>
  +      </li>
  +      <li>
  +        <a href="#stop-generating-ids">
  +          How can I stop Betwixt generating <code>ID</code> attribute values
for my beans?
  +        </a>
  +      </li>
  +    </ol>
       <p><strong>Building Betwixt</strong></p>
       <ol>
         <li>
  @@ -97,7 +120,69 @@
   			to your own look and feel. Long term bean serialization doesn't generate nice looking
XML.
           </dd>
         </dl>
  +    </section>
  +    <section name="Writing Beans">     
  +      <dl>
  +        <dt>
  +          <a name="output-options">
  +          	In what forms can Betwixt output the xml?
  +          </a>
  +        </dt>
  +        <dd>
  +            At the moment,  <code>BeanWriter</code> is the only way to output
the xml.
  +            This writes the xml (as characters) to standard java io streams. 
  +            Work will begin on a SAX-based writer (which will generate SAX events)
  +            very soon.
  +        </dd>
  +      </dl>
  +      <dl>
  +        <dt>
  +          <a name="pretty-print">
  +          	Can <code>BeanWriter</code> produce xml that's easy (for a human
;) to read?
  +          </a>
  +        </dt>
  +        <dd>
  +            Yes! Call
  +<pre>
  +beanWriter.enablePrettyPrint();
  +</pre>
  +            (For those who are extra picky, how this is done can also be adjusted.
  +            See java docs for details.)
  +        </dd>
  +      </dl>      
  +      
  +      <dl>
  +        <dt>
  +          <a name="cycles">
  +          	How does Betwixt cope with beans which have cyclic reference graphs?
  +          </a>
  +        </dt>
  +        <dd>
  +            The default behaviour is to use the <code>ID</code>-<code>IDREF</code>
mechanism
  +            (described in the xml specification). Betwixt will automatically assign <code>ID</code>
  +            values to beans as it write out the graph. If it comes to a bean that it's
written
  +            before, it will write an <code>IDREF</code> value matching the
original.
  +        </dd>
  +      </dl>  
         
  +      <dl>
  +        <dt>
  +          <a name="stop-generating-ids">
  +          	How can I stop Betwixt generating <code>ID</code> attribute values
for my beans?
  +          </a>
  +        </dt>
  +        <dd>
  +            This is controlled by a property on <code>BeanWriter</code>. Call
  +<pre>
  +beanWriter.setWriteIDs(false);
  +</pre>
  +            and then Betwixt will no longer automatically add <code>ID</code>
attributes.
  +            Once this property is set (to false), BeanWroter will throw a 
  +            <code>CyclicReferenceException</code> when any cyclic references
which are 
  +            encountered in the bean graph.
  +        </dd>
  +      </dl>   
  +          
       </section>
       <section name="Building Betwixt">
         <dl>
  
  
  

--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message