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 2003/01/07 23:32:58 UTC
cvs commit: jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io BeanWriter.java IDGenerator.java
rdonkin 2003/01/07 14:32:58
Modified: betwixt/src/java/org/apache/commons/betwixt
AttributeDescriptor.java XMLBeanInfo.java
betwixt/src/java/org/apache/commons/betwixt/digester
AddDefaultsRule.java AttributeRule.java
ElementRule.java HideRule.java InfoRule.java
RuleSupport.java XMLBeanInfoDigester.java
XMLIntrospectorHelper.java
betwixt/src/java/org/apache/commons/betwixt/io
BeanWriter.java IDGenerator.java
Log:
Improved java docs
Revision Changes Path
1.3 +18 -4 jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/AttributeDescriptor.java
Index: AttributeDescriptor.java
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/AttributeDescriptor.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- AttributeDescriptor.java 5 Jan 2003 17:18:32 -0000 1.2
+++ AttributeDescriptor.java 7 Jan 2003 22:32:57 -0000 1.3
@@ -73,17 +73,31 @@
public AttributeDescriptor() {
}
- /** Creates a AttributeDescriptor with no namespace URI or prefix */
+ /**
+ * Creates a AttributeDescriptor with no namespace URI or prefix
+ *
+ * @param localName the local name for the attribute, excluding any namespace prefix
+ */
public AttributeDescriptor(String localName) {
super( localName );
}
- /** Creates a AttributeDescriptor with namespace URI and qualified name */
- public AttributeDescriptor(String localName,String qualifiedName,String uri) {
+ /**
+ * Creates a AttributeDescriptor with namespace URI and qualified name
+ *
+ * @param localName the local name for the attribute, excluding any namespace prefix
+ * @param qualifiedName the fully quanified name, including the namespace prefix
+ * @param uri the namespace for the attribute - or "" for no namespace
+ */
+ public AttributeDescriptor(String localName, String qualifiedName, String uri) {
super(localName, qualifiedName, uri);
}
- /** Return something useful for logging */
+ /**
+ * Return something useful for logging
+ *
+ * @return something useful for logging
+ */
public String toString() {
return "AttributeDescriptor[qname=" + getQualifiedName()
+ ",class=" + getPropertyType() + "]";
1.5 +30 -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.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- XMLBeanInfo.java 26 Sep 2002 19:29:33 -0000 1.4
+++ XMLBeanInfo.java 7 Jan 2003 22:32:57 -0000 1.5
@@ -93,17 +93,28 @@
/** Cached <code>ID</code> attribute descriptor */
private AttributeDescriptor idAttributeDescriptor;
- /** Base constructor */
+ /**
+ * Base constructor
+ * @param beanClass for this Class
+ */
public XMLBeanInfo( Class beanClass ) {
this.beanClass = beanClass;
}
- /** Get descriptor for bean represention */
+ /**
+ * Gets descriptor for bean represention
+ *
+ * @return ElementDescriptor describing root element
+ */
public ElementDescriptor getElementDescriptor() {
return elementDescriptor;
}
- /** Set descriptor for bean represention */
+ /**
+ * Sets descriptor for bean represention
+ *
+ * @param elementDescriptor descriptor for bean
+ */
public void setElementDescriptor(ElementDescriptor elementDescriptor) {
this.elementDescriptor = elementDescriptor;
}
@@ -117,12 +128,20 @@
return beanClass;
}
- /** Sets the beans class that this XML info refers to */
+ /**
+ * Sets the beans class that this XML info refers to
+ *
+ * @param beanClass the class that this refers to
+ */
public void setBeanClass(Class beanClass) {
this.beanClass = beanClass;
}
- /** Search attributes for one matching <code>ID</code> attribute name */
+ /**
+ * Search attributes for one matching <code>ID</code> attribute name
+ *
+ * @return the xml ID attribute
+ */
public AttributeDescriptor getIDAttribute() {
//
// XXX for some reason caching isn't working at the moment
@@ -170,6 +189,7 @@
public String getIDAttributeName() {
return idAttributeName;
}
+
/**
* Set name of <code>ID</code> attribute
* This is used to write (for example) automatic <code>ID</code>
@@ -207,6 +227,11 @@
this.idrefAttributeName = idrefAttributeName;
}
+ /**
+ * Gets log-friendly string representation.
+ *
+ * @return something useful for logging
+ */
public String toString() {
return
"XMLBeanInfo [class=" + getBeanClass()
1.6 +19 -2 jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/AddDefaultsRule.java
Index: AddDefaultsRule.java
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/AddDefaultsRule.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- AddDefaultsRule.java 6 Jan 2003 22:50:44 -0000 1.5
+++ AddDefaultsRule.java 7 Jan 2003 22:32:57 -0000 1.6
@@ -86,7 +86,7 @@
/** Logger */
private static final Log log = LogFactory.getLog( AddDefaultsRule.class );
-
+ /** Base constructor */
public AddDefaultsRule() {
}
@@ -97,6 +97,7 @@
* Process the beginning of this element.
*
* @param attributes The attribute list of this element
+ * @throws Exception generally this will indicate an unrecoverable error
*/
public void begin(Attributes attributes) throws Exception {
Class beanClass = getBeanClass();
@@ -137,6 +138,15 @@
// Implementation methods
//-------------------------------------------------------------------------
+
+ /**
+ * Add a desciptor to the top object on the Digester stack.
+ *
+ * @param nodeDescriptor add this <code>NodeDescriptor</code>. Must not be null.
+ * @throws SAXException if the parent for the addDefaults element is not a <element>
+ * or if the top object on the stack is not a <code>XMLBeanInfo</code> or a
+ * <code>ElementDescriptor</code>
+ */
protected void addDescriptor( NodeDescriptor nodeDescriptor ) throws SAXException {
Object top = digester.peek();
if ( top instanceof XMLBeanInfo ) {
@@ -169,7 +179,14 @@
"Invalid use of <addDefaults>. It should be nested inside <element> element" );
}
}
-
+
+ /**
+ * Gets an <code>ElementDescriptor</code> for the top on digester's stack.
+ *
+ * @return the top object or the element description if the top object
+ * is an <code>ElementDescriptor</code> or a <code>XMLBeanInfo</code> class (respectively)
+ * Otherwise null.
+ */
protected ElementDescriptor getRootElementDescriptor() {
Object top = digester.peek();
if ( top instanceof XMLBeanInfo ) {
1.5 +17 -5 jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/AttributeRule.java
Index: AttributeRule.java
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/AttributeRule.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- AttributeRule.java 6 Jan 2003 22:50:44 -0000 1.4
+++ AttributeRule.java 7 Jan 2003 22:32:57 -0000 1.5
@@ -78,11 +78,12 @@
/** Logger */
private static final Log log = LogFactory.getLog( AttributeRule.class );
-
+ /** This loads all classes created by name. Defaults to this class's classloader */
private ClassLoader classLoader;
-
+ /** The <code>Class</code> whose .betwixt file is being digested */
private Class beanClass;
+ /** Base constructor */
public AttributeRule() {
this.classLoader = getClass().getClassLoader();
}
@@ -94,8 +95,9 @@
* Process the beginning of this element.
*
* @param attributes The attribute list of this element
+ * @throws SAXException if the attribute tag is not inside an element tag
*/
- public void begin(Attributes attributes) throws Exception {
+ public void begin(Attributes attributes) throws SAXException {
AttributeDescriptor descriptor = new AttributeDescriptor();
String name = attributes.getValue( "name" );
@@ -134,13 +136,19 @@
/**
* Process the end of this element.
*/
- public void end() throws Exception {
+ public void end() {
Object top = digester.pop();
}
// Implementation methods
//-------------------------------------------------------------------------
+ /**
+ * Loads a class (using the appropriate classloader)
+ *
+ * @param name the name of the class to load
+ * @return the class instance loaded by the appropriate classloader
+ */
protected Class loadClass( String name ) {
// XXX: should use a ClassLoader to handle complex class loading situations
if ( name != null ) {
@@ -152,7 +160,11 @@
return null;
}
- /** Set the Expression and Updater from a bean property name */
+ /**
+ * Set the Expression and Updater from a bean property name
+ * @param attributeDescriptor configure this <code>AttributeDescriptor</code>
+ * from the property with a matching name in the bean class
+ */
protected void configureDescriptor(AttributeDescriptor attributeDescriptor) {
Class beanClass = getBeanClass();
if ( beanClass != null ) {
1.6 +24 -6 jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/ElementRule.java
Index: ElementRule.java
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/ElementRule.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- ElementRule.java 6 Jan 2003 22:50:44 -0000 1.5
+++ ElementRule.java 7 Jan 2003 22:32:57 -0000 1.6
@@ -80,11 +80,11 @@
/** Logger */
private static final Log log = LogFactory.getLog( ElementRule.class );
-
+ /** Classloader used to load classes by name */
private ClassLoader classLoader;
-
+ /** Class for which the .bewixt file is being digested */
private Class beanClass;
-
+ /** Base constructor */
public ElementRule() {
this.classLoader = getClass().getClassLoader();
}
@@ -96,8 +96,9 @@
* Process the beginning of this element.
*
* @param attributes The attribute list of this element
+ * @throws SAXException when this tag's parent is not either an info or element tag
*/
- public void begin(Attributes attributes) throws Exception {
+ public void begin(Attributes attributes) throws SAXException {
String name = attributes.getValue( "name" );
ElementDescriptor descriptor = new ElementDescriptor();
@@ -157,13 +158,22 @@
/**
* Process the end of this element.
*/
- public void end() throws Exception {
+ public void end() {
Object top = digester.pop();
}
// Implementation methods
//-------------------------------------------------------------------------
+
+ /**
+ * Gets the type of a property
+ *
+ * @param propertyClassName class name for property type (may be null)
+ * @param beanClass class that has property
+ * @param propertyName the name of the property whose type is to be determined
+ * @return property type
+ */
protected Class getPropertyType( String propertyClassName,
Class beanClass, String propertyName ) {
// XXX: should use a ClassLoader to handle
@@ -196,7 +206,11 @@
return null;
}
- /** Set the Expression and Updater from a bean property name */
+ /**
+ * Set the Expression and Updater from a bean property name
+ *
+ * @param elementDescriptor configure this <code>ElementDescriptor</code>
+ */
protected void configureDescriptor(ElementDescriptor elementDescriptor) {
Class beanClass = getBeanClass();
if ( beanClass != null ) {
@@ -215,6 +229,10 @@
* Returns the property descriptor for the class and property name.
* Note that some caching could be used to improve performance of
* this method. Or this method could be added to PropertyUtils.
+ *
+ * @param beanClass descriptor for property in this class
+ * @param propertyName descriptor for property with this name
+ * @return property descriptor for the named property in the given class
*/
protected PropertyDescriptor getPropertyDescriptor( Class beanClass,
String propertyName ) {
1.4 +4 -3 jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/HideRule.java
Index: HideRule.java
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/HideRule.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- HideRule.java 5 Jan 2003 17:18:32 -0000 1.3
+++ HideRule.java 7 Jan 2003 22:32:57 -0000 1.4
@@ -78,7 +78,7 @@
/** Logger */
private static final Log log = LogFactory.getLog( HideRule.class );
-
+ /** Base constructor */
public HideRule() {
}
@@ -89,8 +89,9 @@
* Process the beginning of this element.
*
* @param attributes The attribute list of this element
+ * @throws SAXException when the mandatory 'property' attribute is missing
*/
- public void begin(Attributes attributes) throws Exception {
+ public void begin(Attributes attributes) throws SAXException {
String name = attributes.getValue( "property" );
if ( name == null || name.length() == 0 ) {
throw new SAXException(
@@ -104,6 +105,6 @@
/**
* Process the end of this element.
*/
- public void end() throws Exception {
+ public void end() {
}
}
1.5 +7 -6 jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/InfoRule.java
Index: InfoRule.java
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/InfoRule.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- InfoRule.java 6 Jan 2003 22:50:44 -0000 1.4
+++ InfoRule.java 7 Jan 2003 22:32:57 -0000 1.5
@@ -65,6 +65,7 @@
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.xml.sax.Attributes;
+import org.xml.sax.SAXException;
/** <p><code>InfoRule</code> the digester Rule for parsing the info element.</p>
*
@@ -75,10 +76,10 @@
/** Logger */
private static final Log log = LogFactory.getLog( InfoRule.class );
-
+ /** <code>XMLBeanInfo</code> being created */
private XMLBeanInfo xmlBeanInfo;
-
+ /** Base constructor */
public InfoRule() {
}
@@ -89,8 +90,9 @@
* Process the beginning of this element.
*
* @param attributes The attribute list of this element
+ * @throws SAXException if the primitiveTypes attribute contains an invalid value
*/
- public void begin(Attributes attributes) throws Exception {
+ public void begin(Attributes attributes) throws SAXException {
Class beanClass = getBeanClass();
xmlBeanInfo = new XMLBeanInfo( beanClass );
@@ -104,8 +106,7 @@
getXMLInfoDigester().setAttributesForPrimitives( true );
} else {
- // XXX Should this be a checked exception?
- throw new Exception(
+ throw new SAXException(
"Invalid value inside element <info> for attribute 'primitiveTypes'."
+ " Value should be 'element' or 'attribute'" );
}
@@ -118,7 +119,7 @@
/**
* Process the end of this element.
*/
- public void end() throws Exception {
+ public void end() {
Object top = getDigester().pop();
}
}
1.3 +21 -1 jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/RuleSupport.java
Index: RuleSupport.java
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/RuleSupport.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- RuleSupport.java 30 Dec 2002 18:18:37 -0000 1.2
+++ RuleSupport.java 7 Jan 2003 22:32:57 -0000 1.3
@@ -78,7 +78,7 @@
/** Logger */
private static final Log log = LogFactory.getLog( RuleSupport.class );
-
+ /** Base constructor */
public RuleSupport() {
}
@@ -86,18 +86,38 @@
// Implementation methods
//-------------------------------------------------------------------------
+ /**
+ * Gets <code>XMLBeanInfoDigester</code> using this rule.
+ *
+ * @return <code>XMLBeanInfoDigester</code> for this rule
+ */
protected XMLBeanInfoDigester getXMLInfoDigester() {
return (XMLBeanInfoDigester) getDigester();
}
+ /**
+ * Gets <code>XMLIntrospector</code> to be used for introspection
+ *
+ * @return <code>XMLIntrospector</code> to use
+ */
protected XMLIntrospector getXMLIntrospector() {
return getXMLInfoDigester().getXMLIntrospector();
}
+ /**
+ * Gets the class of the bean whose .betwixt file is being digested
+ *
+ * @return the <code>Class</code> of the bean being processed
+ */
protected Class getBeanClass() {
return getXMLInfoDigester().getBeanClass();
}
+ /**
+ * Gets the property names already processed
+ *
+ * @return the set of property names that have been processed so far
+ */
protected Set getProcessedPropertyNameSet() {
return getXMLInfoDigester().getProcessedPropertyNameSet();
}
1.3 +38 -7 jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/XMLBeanInfoDigester.java
Index: XMLBeanInfoDigester.java
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/XMLBeanInfoDigester.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- XMLBeanInfoDigester.java 30 Dec 2002 18:18:37 -0000 1.2
+++ XMLBeanInfoDigester.java 7 Jan 2003 22:32:57 -0000 1.3
@@ -107,6 +107,8 @@
* JAXP1.1 (such as WebLogic 6.0). Thanks for the request to change go to
* James House (james@interobjective.com). This may help in places where
* you are able to load JAXP 1.1 classes yourself.
+ *
+ * @param parser the <code>SAXParser</code> to be used to parse the xml
*/
public XMLBeanInfoDigester(SAXParser parser) {
super(parser);
@@ -118,34 +120,54 @@
* JAXP1.1 (such as WebLogic 6.0). Note that if you use this option you
* have to configure namespace and validation support yourself, as these
* properties only affect the SAXParser and emtpy constructor.
+ *
+ * @param reader the <code>XMLReader</code> to be used to parse the xml
*/
public XMLBeanInfoDigester(XMLReader reader) {
super(reader);
}
- /** @return the beans class for this XML descriptor */
+ /**
+ * Gets the class of the bean whose .betwixt file is being processed
+ *
+ * @return the beans class for this XML descriptor
+ */
public Class getBeanClass() {
return beanClass;
}
- /** Sets the beans class for this XML descriptor */
+ /**
+ * Sets the beans class for this XML descriptor
+ *
+ * @param beanClass the <code>Class</code> of the bean being processed
+ */
public void setBeanClass(Class beanClass) {
this.beanClass = beanClass;
}
- /** @return the set of property names that have been processed so far */
+ /**
+ * Gets the property names already processed
+ *
+ * @return the set of property names that have been processed so far
+ */
public Set getProcessedPropertyNameSet() {
return processedPropertyNameSet;
}
- /** Should attributes (or elements) be used for primitive types.
+ /**
+ * Should attributes (or elements) be used for primitive types?
+ * @return true if primitive properties should be written as attributes in the xml
*/
public boolean isAttributesForPrimitives() {
return attributesForPrimitives;
}
- /** Set whether attributes (or elements) should be used for primitive types. */
+ /**
+ * Set whether attributes (or elements) should be used for primitive types.
+ * @param attributesForPrimitives pass true if primitive properties should be
+ * written as attributes
+ */
public void setAttributesForPrimitives(boolean attributesForPrimitives) {
this.attributesForPrimitives = attributesForPrimitives;
if ( introspector != null ) {
@@ -153,18 +175,27 @@
}
}
- /** @return the introspector that is using me */
+ /**
+ * Gets the XMLIntrospector that's using this digester.
+ *
+ * @return the introspector that is using me
+ */
public XMLIntrospector getXMLIntrospector() {
return introspector;
}
- /** Sets the introspector that is using me */
+ /**
+ * Sets the introspector that is using me
+ * @param introspector the <code>XMLIntrospector</code> that using this for .betwixt
+ * digestion
+ */
public void setXMLIntrospector(XMLIntrospector introspector) {
this.introspector = introspector;
}
// Implementation methods
//-------------------------------------------------------------------------
+ /** Reset configure for new digestion */
protected void configure() {
if (! configured) {
configured = true;
1.15 +55 -7 jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/XMLIntrospectorHelper.java
Index: XMLIntrospectorHelper.java
===================================================================
RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/XMLIntrospectorHelper.java,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- XMLIntrospectorHelper.java 6 Jan 2003 22:50:44 -0000 1.14
+++ XMLIntrospectorHelper.java 7 Jan 2003 22:32:57 -0000 1.15
@@ -96,14 +96,18 @@
}
/**
- * <p> Get the current logging implementation. </p>
+ * <p>Gets the current logging implementation.</p>
+ *
+ * @return current log
*/
public static Log getLog() {
return log;
}
/**
- * <p> Set the current logging implementation. </p>
+ * <p>Sets the current logging implementation.</p>
+ *
+ * @param aLog use this <code>Log</code>
*/
public static void setLog(Log aLog) {
log = aLog;
@@ -114,6 +118,12 @@
* Process a property.
* Go through and work out whether it's a loop property, a primitive or a standard.
* The class property is ignored.
+ *
+ * @param propertyDescriptor create a <code>NodeDescriptor</code> for this property
+ * @param useAttributesForPrimitives write primitives as attributes (rather than elements)
+ * @param introspector use this <code>XMLIntrospector</code>
+ * @return a correctly configured <code>NodeDescriptor</code> for the property
+ * @throws IntrospectionException when bean introspection fails
*/
public static NodeDescriptor createDescriptor(
PropertyDescriptor propertyDescriptor,
@@ -222,7 +232,12 @@
return nodeDescriptor;
}
-
+ /**
+ * Configure an <code>ElementDescriptor</code> from a <code>PropertyDescriptor</code>
+ *
+ * @param elementDescriptor configure this <code>ElementDescriptor</code>
+ * @param propertyDescriptor configure from this <code>PropertyDescriptor</code>
+ */
public static void configureProperty(
ElementDescriptor elementDescriptor,
PropertyDescriptor propertyDescriptor ) {
@@ -276,7 +291,12 @@
}
}
-
+ /**
+ * Configure an <code>AttributeDescriptor</code> from a <code>PropertyDescriptor</code>
+ *
+ * @param attributeDescriptor configure this <code>AttributeDescriptor</code>
+ * @param propertyDescriptor configure from this <code>PropertyDescriptor</code>
+ */
public static void configureProperty(
AttributeDescriptor attributeDescriptor,
PropertyDescriptor propertyDescriptor ) {
@@ -334,6 +354,10 @@
* and find the first ElementDescriptor that matches the property starting with
* the string. This should work for most use cases.
* e.g. addChild() would match the children property.
+ *
+ * @param introspector use this <code>XMLIntrospector</code> for introspection
+ * @param rootDescriptor add defaults to this descriptor
+ * @param beanClass the <code>Class</code> to which descriptor corresponds
*/
public static void defaultAddMethods(
XMLIntrospector introspector,
@@ -365,7 +389,7 @@
introspector,
rootDescriptor,
propertyName );
-
+
if ( log.isDebugEnabled() ) {
log.debug( "!! " + propertyName + " -> " + descriptor );
log.debug( "!! " + name + " -> " + descriptor.getPropertyName() );
@@ -405,7 +429,12 @@
}
}
- /** Returns true if the type is a loop type */
+ /**
+ * Is this a loop type class?
+ *
+ * @param type is this <code>Class</code> a loop type?
+ * @return true if the type is a loop type
+ */
public static boolean isLoopType(Class type) {
return type.isArray()
|| Map.class.isAssignableFrom( type )
@@ -415,7 +444,12 @@
}
- /** Returns true for primitive types */
+ /**
+ * Is this a primitive type?
+ *
+ * @param type is this <code>Class<code> a primitive type?
+ * @return true for primitive types
+ */
public static boolean isPrimitiveType(Class type) {
if ( type == null ) {
return false;
@@ -445,6 +479,12 @@
* typically matches a collection or array. The property name is used
* to match. e.g. if an addChild() method is detected the
* descriptor for the 'children' getter property should be returned.
+ *
+ * @param introspector use this <code>XMLIntrospector</code>
+ * @param rootDescriptor the <code>ElementDescriptor</code> whose child element will be
+ * searched for a match
+ * @param propertyName the name of the 'adder' method to match
+ * @return <code>ElementDescriptor</code> for the matching getter
*/
protected static ElementDescriptor findGetCollectionDescriptor(
XMLIntrospector introspector,
@@ -477,6 +517,10 @@
/**
* Creates a map where the keys are the property names and the values are the ElementDescriptors
+ *
+ * @param rootDescriptor the values of the maps are the children of this
+ * <code>ElementDescriptor</code> index by their property names
+ * @param map the map to which the elements will be added
*/
protected static void makeElementDescriptorMap( ElementDescriptor rootDescriptor, Map map ) {
ElementDescriptor[] children = rootDescriptor.getElementDescriptors();
@@ -495,6 +539,10 @@
/**
* Traverse the tree of element descriptors and find the oldValue and swap it with the newValue.
* This would be much easier to do if ElementDescriptor supported a parent relationship.
+ *
+ * @param rootDescriptor traverse child graph for this <code>ElementDescriptor</code>
+ * @param oldValue replace this <code>ElementDescriptor</code>
+ * @param newValue replace with this <code>ElementDescriptor</code>
*/
protected static void swapDescriptor(
ElementDescriptor rootDescriptor,
1.13 +77 -9 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.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- BeanWriter.java 6 Jan 2003 22:50:44 -0000 1.12
+++ BeanWriter.java 7 Jan 2003 22:32:57 -0000 1.13
@@ -178,6 +178,8 @@
*
* @param xmlDeclaration is the XML declaration string typically of
* the form "<xml version='1.0' encoding='UTF-8' ?>
+ *
+ * @throws IOException when declaration cannot be written
*/
public void writeXmlDeclaration(String xmlDeclaration) throws IOException {
writer.write( xmlDeclaration );
@@ -186,6 +188,8 @@
/**
* Allows output to be flushed on the underlying output stream
+ *
+ * @throws IOException when the flush cannot be completed
*/
public void flush() throws IOException {
writer.flush();
@@ -193,11 +197,21 @@
/**
* Closes the underlying output stream
+ *
+ * @throws IOException when writer cannot be closed
*/
public void close() throws IOException {
writer.close();
}
+ /**
+ * Write the given object to the stream (and then flush).
+ *
+ * @param bean write this <code>Object</code> to the stream
+ * @throws IOException if an IO problem causes failure
+ * @throws SAXException if a SAX problem causes failure
+ * @throws IntrospectionException if bean cannot be introspected
+ */
public void write(Object bean) throws IOException, SAXException, IntrospectionException {
super.write(bean);
@@ -218,7 +232,11 @@
indent = " ";
}
- /** Returns the string used for end of lines */
+ /**
+ * Gets the string used to mark end of lines.
+ *
+ * @return the string used for end of lines
+ */
public String getEndOfLine() {
return endOfLine;
}
@@ -226,6 +244,8 @@
/**
* Sets the string used for end of lines
* Produces a warning the specified value contains an invalid whitespace character
+ *
+ * @param endOfLine the <code>String</code to use
*/
public void setEndOfLine(String endOfLine) {
this.endOfLine = endOfLine;
@@ -238,12 +258,19 @@
}
- /** Returns the string used for indentation */
+ /**
+ * Gets the indent string
+ *
+ * @return the string used for indentation
+ */
public String getIndent() {
return indent;
}
- /** Sets the string used for end of lines */
+ /**
+ * Sets the string used for pretty print indents
+ * @param indent use this <code>string</code> for indents
+ */
public void setIndent(String indent) {
this.indent = indent;
}
@@ -270,7 +297,12 @@
// Expression methods
//-------------------------------------------------------------------------
- /** Express an element tag start using given qualified name */
+ /**
+ * Express an element tag start using given qualified name
+ *
+ * @param qualifiedName the fully qualified name of the element to write
+ * @throws IOException when stream write fails
+ */
protected void expressElementStart(String qualifiedName) throws IOException {
if ( qualifiedName == null ) {
// XXX this indicates a programming error
@@ -284,11 +316,21 @@
writer.write( qualifiedName );
}
+ /**
+ * Write a tag close to the stream
+ *
+ * @throws IOException when stream write fails
+ */
protected void expressTagClose() throws IOException {
writer.write( '>' );
}
- /** Express an element end tag using given qualifiedName */
+ /**
+ * Write an element end tag to the stream
+ *
+ * @param qualifiedName the name of the element
+ * @throws IOException when stream write fails
+ */
protected void expressElementEnd(String qualifiedName) throws IOException {
if (qualifiedName == null) {
// XXX this indicates a programming error
@@ -301,12 +343,21 @@
writer.write( '>' );
}
- /** Express an empty element end */
+ /**
+ * Write an empty element end to the stream
+ *
+ * @throws IOException when stream write fails
+ */
protected void expressElementEnd() throws IOException {
writer.write( "/>" );
}
- /** Express body text */
+ /**
+ * Write element body text
+ *
+ * @param text write out this body text
+ * @throws IOException when the stream write fails
+ */
protected void expressBodyText(String text) throws IOException {
if ( text == null ) {
// XXX This is probably a programming error
@@ -317,7 +368,13 @@
}
}
- /** Express an attribute */
+ /**
+ * Writes an attribute to the stream.
+ *
+ * @param qualifiedName fully qualified attribute name
+ * @param value attribute value
+ * @throws IOException when the stream write fails
+ */
protected void expressAttribute(
String qualifiedName,
String value)
@@ -348,6 +405,8 @@
/** Writes out an empty line.
* Uses current <code>endOfLine</code>.
+ *
+ * @throws IOException when stream write fails
*/
protected void writePrintln() throws IOException {
if ( endOfLine != null ) {
@@ -355,7 +414,10 @@
}
}
- /** Writes out <code>indent</code>'s to the current <code>indentLevel</code>
+ /**
+ * Writes out <code>indent</code>'s to the current <code>indentLevel</code>
+ *
+ * @throws IOException when stream write fails
*/
protected void writeIndent() throws IOException {
if ( indent != null ) {
@@ -368,6 +430,9 @@
/**
* <p>Escape the <code>toString</code> of the given object.
* For use as body text.</p>
+ *
+ * @param value escape <code>value.toString()</code>
+ * @return text with escaped delimiters
*/
protected String escapeBodyValue(Object value) {
StringBuffer buffer = new StringBuffer(value.toString());
@@ -396,6 +461,9 @@
/**
* <p>Escape the <code>toString</code> of the given object.
* For use in an attribute value.</p>
+ *
+ * @param value escape <code>value.toString()</code>
+ * @return text with characters restricted (for use in attributes) escaped
*/
protected String escapeAttributeValue(Object value) {
StringBuffer buffer = new StringBuffer(value.toString());
1.4 +4 -0 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.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- IDGenerator.java 14 Aug 2002 18:50:21 -0000 1.3
+++ IDGenerator.java 7 Jan 2003 22:32:57 -0000 1.4
@@ -78,11 +78,15 @@
/**
* Get the last <code>ID</code> value generated.
+ *
+ * @return the last value generated
*/
public String getLastId();
/**
* Generate a new <code>ID</code> attribute value.
+ *
+ * @return next value
*/
public String nextId();
}
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>