You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by rd...@apache.org on 2002/06/12 23:40:06 UTC
cvs commit: jakarta-commons/betwixt/xdocs faq.xml
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: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>