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/src/java/org/apache/commons/betwixt/io BeanWriter.java IDGenerator.java
Date Tue, 07 Jan 2003 22:32:58 GMT
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 "&lt;xml version='1.0' encoding='UTF-8' ?&gt;
  +     *
  +     * @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:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message