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/expression ConstantExpression.java EmptyExpression.java Expression.java IteratorExpression.java Updater.java
Date Thu, 09 Jan 2003 22:34:08 GMT
rdonkin     2003/01/09 14:34:08

  Modified:    betwixt/src/java/org/apache/commons/betwixt XMLBeanInfo.java
                        XMLIntrospector.java
               betwixt/src/java/org/apache/commons/betwixt/expression
                        ConstantExpression.java EmptyExpression.java
                        Expression.java IteratorExpression.java
                        Updater.java
  Log:
  Improved java docs. Less than one hundred checkstyle warnings to go now :)
  
  Revision  Changes    Path
  1.6       +4 -1      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.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- XMLBeanInfo.java	7 Jan 2003 22:32:57 -0000	1.5
  +++ XMLBeanInfo.java	9 Jan 2003 22:34:07 -0000	1.6
  @@ -157,7 +157,10 @@
           return idAttributeDescriptor;
       }
       
  -    /** ID attribute search implementation */
  +    /** 
  +     * ID attribute search implementation 
  +     * @return the AttributeDescriptor for the <code>ID</code> attribute
  +     */
       private AttributeDescriptor findIDAttribute() {
           // we'll check to see if the bean already has an id
           if ( getElementDescriptor().hasAttributes() ) {
  
  
  
  1.19      +98 -27    jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/XMLIntrospector.java
  
  Index: XMLIntrospector.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/XMLIntrospector.java,v
  retrieving revision 1.18
  retrieving revision 1.19
  diff -u -r1.18 -r1.19
  --- XMLIntrospector.java	6 Jan 2003 22:50:44 -0000	1.18
  +++ XMLIntrospector.java	9 Jan 2003 22:34:07 -0000	1.19
  @@ -130,7 +130,7 @@
        * It will default to the normal nameMapper.
        */
       private NameMapper attributeNameMapper;
  -    
  +    /** Should the existing bean info search path for java.reflect.Introspector be used?
*/
       private boolean useBeanInfoSearchPath = false;
       
       /** Base constructor */
  @@ -138,21 +138,23 @@
       }
       
       /**
  -     * <p> Get the current logging implementation. </p>
  +     * <p>Gets the current logging implementation. </p>
  +     * @return the Log implementation which this class logs to
        */ 
       public Log getLog() {
           return log;
       }
   
       /**
  -     * <p> Set the current logging implementation. </p>
  +     * <p>Sets the current logging implementation.</p>
  +     * @param log the Log implementation to use for logging
        */ 
       public void setLog(Log log) {
           this.log = log;
       }
       
       /** 
  -     * <p>Get current registry implementation used.
  +     * <p>Gets the current registry implementation.
        * The registry is checked to see if it has an <code>XMLBeanInfo</code>
for a class
        * before introspecting. 
        * After standard introspection is complete, the instance will be passed to the registry.</p>
  @@ -160,13 +162,15 @@
        * <p>This allows finely grained control over the caching strategy.
        * It also allows the standard introspection mechanism 
        * to be overridden on a per class basis.</p>
  +     *
  +     * @return the XMLBeanInfoRegistry currently used 
        */
       public XMLBeanInfoRegistry getRegistry() {
           return registry;
       }
       
       /** 
  -     * <p>Set current registry implementation used.
  +     * <p>Sets the <code>XMLBeanInfoRegistry</code> implementation.
        * The registry is checked to see if it has an <code>XMLBeanInfo</code>
for a class
        * before introspecting. 
        * After standard introspection is complete, the instance will be passed to the registry.</p>
  @@ -174,6 +178,8 @@
        * <p>This allows finely grained control over the caching strategy.
        * It also allows the standard introspection mechanism 
        * to be overridden on a per class basis.</p>
  +     *
  +     * @param registry the XMLBeanInfoRegistry to use
        */
       public void setRegistry(XMLBeanInfoRegistry registry) {
           this.registry = registry;
  @@ -184,6 +190,7 @@
        * Is <code>XMLBeanInfo</code> caching enabled? 
        *
        * @deprecated replaced by XMlBeanInfoRegistry
  +     * @return true if caching is enabled
        */
       public boolean isCachingEnabled() {
           return true;
  @@ -193,6 +200,7 @@
        * Set whether <code>XMLBeanInfo</code> caching should be enabled.
        *
        * @deprecated replaced by XMlBeanInfoRegistry
  +     * @param cachingEnabled ignored
        */    
       public void setCachingEnabled(boolean cachingEnabled) {
           //
  @@ -206,9 +214,13 @@
       public void flushCache() {}
       
       /** Create a standard <code>XMLBeanInfo</code> by introspection
  -        The actual introspection depends only on the <code>BeanInfo</code>
  -        associated with the bean.
  -        */
  +      * The actual introspection depends only on the <code>BeanInfo</code>
  +      * associated with the bean.
  +      * 
  +      * @param bean introspect this bean
  +      * @return XMLBeanInfo describing bean-xml mapping
  +      * @throws IntrospectionException when the bean introspection fails
  +      */
       public XMLBeanInfo introspect(Object bean) throws IntrospectionException {
           if (log.isDebugEnabled()) {
               log.debug( "Introspecting..." );
  @@ -218,8 +230,12 @@
       }
       
       /** Create a standard <code>XMLBeanInfo</code> by introspection.
  -        The actual introspection depends only on the <code>BeanInfo</code>
  -        associated with the bean.        
  +      * The actual introspection depends only on the <code>BeanInfo</code>
  +      * associated with the bean.    
  +      *    
  +      * @param aClass introspect this class
  +      * @return XMLBeanInfo describing bean-xml mapping
  +      * @throws IntrospectionException when the bean introspection fails
         */
       public XMLBeanInfo introspect(Class aClass) throws IntrospectionException {
           // we first reset the beaninfo searchpath.
  @@ -262,9 +278,13 @@
       }
       
       /** Create a standard <code>XMLBeanInfo</code> by introspection. 
  -        The actual introspection depends only on the <code>BeanInfo</code>
  -        associated with the bean.
  -        */
  +      * The actual introspection depends only on the <code>BeanInfo</code>
  +      * associated with the bean.
  +      *
  +      * @param beanInfo the BeanInfo the xml-bean mapping is based on
  +      * @return XMLBeanInfo describing bean-xml mapping
  +      * @throws IntrospectionException when the bean introspection fails
  +      */
       public XMLBeanInfo introspect(BeanInfo beanInfo) throws IntrospectionException {  
 
           XMLBeanInfo answer = createXMLBeanInfo( beanInfo );
   
  @@ -339,13 +359,19 @@
       // Properties
       //-------------------------------------------------------------------------       

       
  -    /** Should attributes (or elements) be used for primitive types.
  -     */
  +    /** 
  +      * Should attributes (or elements) be used for primitive types.
  +      * @return true if primitive types will be mapped to attributes in the introspection
  +      */
       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 trus to map primitives to attributes,
  +      *        pass false to map primitives to elements
  +      */
       public void setAttributesForPrimitives(boolean attributesForPrimitives) {
           this.attributesForPrimitives = attributesForPrimitives;
       }
  @@ -359,7 +385,12 @@
           return wrapCollectionsInElement;
       }
   
  -    /** Sets whether we should we wrap collections in an extra element? */
  +    /** 
  +     * Sets whether we should we wrap collections in an extra element.
  +     *
  +     * @param wrapCollectionsInElement pass true if collections should be wrapped in a
  +     *        parent element
  +     */
       public void setWrapCollectionsInElement(boolean wrapCollectionsInElement) {
           this.wrapCollectionsInElement = wrapCollectionsInElement;
       }
  @@ -378,12 +409,16 @@
       
       /** 
        * Sets the strategy used to detect matching singular and plural properties 
  +     *
  +     * @param pluralStemmer the PluralStemmer used to match singular and plural
        */
       public void setPluralStemmer(PluralStemmer pluralStemmer) {
           this.pluralStemmer = pluralStemmer;
       }
   
       /** 
  +     * Gets the name mapper strategy.
  +     * 
        * @return the strategy used to convert bean type names into element names
        * @deprecated getNameMapper is split up in 
        * {@link #getElementNameMapper()} and {@link #getAttributeNameMapper()}
  @@ -394,7 +429,7 @@
       
       /** 
        * Sets the strategy used to convert bean type names into element names
  -     * @param nameMapper
  +     * @param nameMapper the NameMapper strategy to be used
        * @deprecated setNameMapper is split up in 
        * {@link #setElementNameMapper(NameMapper)} and {@link #setAttributeNameMapper(NameMapper)}
        */
  @@ -404,7 +439,7 @@
   
   
       /**
  -     * Get the name mapping strategy used to convert bean names into elements.
  +     * Gets the name mapping strategy used to convert bean names into elements.
        *
        * @return the strategy used to convert bean type names into element 
        * names. If no element mapper is currently defined then a default one is created.
  @@ -417,8 +452,8 @@
       }
        
       /**
  -     *  Sets the strategy used to convert bean type names into element names
  -     * @param nameMapper
  +     * Sets the strategy used to convert bean type names into element names
  +     * @param nameMapper the NameMapper to use for the conversion
        */
       public void setElementNameMapper(NameMapper nameMapper) {
           this.elementNameMapper = nameMapper;
  @@ -426,7 +461,7 @@
       
   
       /**
  -     * Get the name mapping strategy used to convert bean names into attributes.
  +     * Gets the name mapping strategy used to convert bean names into attributes.
        *
        * @return the strategy used to convert bean type names into attribute
        * names. If no attributeNamemapper is known, it will default to the ElementNameMapper
  @@ -441,7 +476,7 @@
   
       /**
        * Sets the strategy used to convert bean type names into attribute names
  -     * @param nameMapper
  +     * @param nameMapper the NameMapper to use for the convertion
        */
       public void setAttributeNameMapper(NameMapper nameMapper) {
           this.attributeNameMapper = nameMapper;
  @@ -458,6 +493,8 @@
       /** 
        * A Factory method to lazily create a new strategy 
        * to detect matching singular and plural properties.
  +     *
  +     * @return new defualt PluralStemmer implementation
        */
       protected PluralStemmer createPluralStemmer() {
           return new DefaultPluralStemmer();
  @@ -466,6 +503,8 @@
       /** 
        * A Factory method to lazily create a strategy 
        * used to convert bean type names into element names.
  +     *
  +     * @return new default NameMapper implementation
        */
       protected NameMapper createNameMapper() {
           return new DefaultNameMapper();
  @@ -475,6 +514,10 @@
        * Attempt to lookup the XML descriptor for the given class using the
        * classname + ".betwixt" using the same ClassLoader used to load the class
        * or return null if it could not be loaded
  +     * 
  +     * @param aClass digester .betwixt file for this class
  +     * @return XMLBeanInfo digested from the .betwixt file if one can be found.
  +     *         Otherwise null.
        */
       protected synchronized XMLBeanInfo findByXMLDescriptor( Class aClass ) {
           // trim the package name
  @@ -511,7 +554,14 @@
           return null;
       }
               
  -    /** Loop through properties and process each one */
  +    /** 
  +     * Loop through properties and process each one 
  +     *
  +     * @param beanInfo the BeanInfo whose properties will be processed
  +     * @param elements ElementDescriptor list to which elements will be added
  +     * @param attributes AttributeDescriptor list to which attributes will be added
  +     * @throws IntrospectionException if the bean introspection fails
  +     */
       protected void addProperties(
                                       BeanInfo beanInfo, 
                                       List elements, 
  @@ -534,6 +584,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 beanInfo the BeanInfo whose property is being processed
  +     * @param propertyDescriptor the PropertyDescriptor to process
  +     * @param elements ElementDescriptor list to which elements will be added
  +     * @param attributes AttributeDescriptor list to which attributes will be added
  +     * @throws IntrospectionException if the bean introspection fails
        */
       protected void addProperty(
                                   BeanInfo beanInfo, 
  @@ -556,23 +612,38 @@
           }
       }
       
  -    /** Factory method to create XMLBeanInfo instances */
  +    /** 
  +     * Factory method to create XMLBeanInfo instances 
  +     *
  +     * @param beanInfo the BeanInfo from which the XMLBeanInfo will be created
  +     * @return XMLBeanInfo describing the bean-xml mapping
  +     */
       protected XMLBeanInfo createXMLBeanInfo( BeanInfo beanInfo ) {
           XMLBeanInfo answer = new XMLBeanInfo( beanInfo.getBeanDescriptor().getBeanClass()
);
           return answer;
       }
   
  -    /** Returns true if the type is a loop type */
  +    /** 
  +     * Is this class a loop?
  +     *
  +     * @param type the Class to test
  +     * @return true if the type is a loop type 
  +     */
       public boolean isLoopType(Class type) {
           return XMLIntrospectorHelper.isLoopType(type);
       }
       
       
  -    /** Returns true for primitive types */
  +    /** 
  +     * Is this class a primitive?
  +     * @param type the Class to test
  +     * @return true for primitive types 
  +     */
       public boolean isPrimitiveType(Class type) {
           return XMLIntrospectorHelper.isPrimitiveType(type);
       }
       /**
  +     * Should the original <code>java.reflect.Introspector</code> bean info
search path be used?
        * By default it will be false.
        * 
        * @return boolean if the beanInfoSearchPath should be used.
  
  
  
  1.3       +20 -4     jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/ConstantExpression.java
  
  Index: ConstantExpression.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/ConstantExpression.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- ConstantExpression.java	1 Jul 2002 18:53:52 -0000	1.2
  +++ ConstantExpression.java	9 Jan 2003 22:34:07 -0000	1.3
  @@ -78,8 +78,10 @@
       public ConstantExpression() {
       }
       
  -    /** Convenience constructor sets <code>value</code> property.
  -     */
  +    /** 
  +      * Convenience constructor sets <code>value</code> property.
  +      * @param value the Object which is the constant value for this expression
  +      */
       public ConstantExpression(Object value) {
           this.value = value;
       }
  @@ -94,20 +96,34 @@
           return value;
       }
       
  +    /**
  +     * Do nothing
  +     * @see org.apache.commons.betwixt.expression.Expression
  +     */
       public void update(Context context, String newValue) {
           // do nothing
       }
   
  -    /** Gets the constant value of this expression */
  +    /** 
  +     * Gets the constant value of this expression 
  +     * @return this expression's constant value 
  +     */
       public Object getValue() {
           return value;
       }
       
  -    /** Sets the constant value of this expression */
  +    /**  
  +     * Sets the constant value of this expression 
  +     * @param value the constant value for this expression
  +     */
       public void setValue(Object value) {
           this.value = value;
       }
       
  +    /**
  +     * Returns something useful for logging
  +     * @return something useful for logging
  +     */
       public String toString() {
           return "ConstantExpression [value=" + value + "]";
       }
  
  
  
  1.3       +11 -1     jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/EmptyExpression.java
  
  Index: EmptyExpression.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/EmptyExpression.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- EmptyExpression.java	1 Jul 2002 18:54:38 -0000	1.2
  +++ EmptyExpression.java	9 Jan 2003 22:34:07 -0000	1.3
  @@ -73,7 +73,9 @@
       /** Don't need more than one <code>EmptyExpression</code>*/
       private static final EmptyExpression singleton = new EmptyExpression();
       
  -    /** Return the <code>EmptyExpression</code> singleton. 
  +    /**
  +     * Gets the singleton instance.
  +     * @return the EmptyExpression singleton. 
        */
       public static EmptyExpression getInstance() {
           return singleton;
  @@ -85,15 +87,23 @@
       }
       
       /** Return the bean we're evaluating.
  +     * @see org.apache.commons.betwixt.expression.Expression
        */ 
       public Object evaluate(Context context) {
           return context.getBean();
       }
       
  +    /** Do nothing
  +     * @see org.apache.commons.betwixt.expression.Expression
  +     */ 
       public void update(Context context, String newValue) {
           // do nothing
       }
       
  +    /**
  +     * Return something useful for logging.
  +     * @return short name for this class
  +     */
       public String toString() {
           return "EmptyExpression";
       }
  
  
  
  1.2       +15 -2     jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/Expression.java
  
  Index: Expression.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/Expression.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- Expression.java	10 Jun 2002 17:53:33 -0000	1.1
  +++ Expression.java	9 Jan 2003 22:34:07 -0000	1.2
  @@ -70,12 +70,25 @@
   
       /** Evaluates the expression on the bean with the given context
        * and returns the result 
  +     *
  +     * @param context evaluate against this <code>Context</code>
  +     * @return the value of the expression
        */
       public Object evaluate(Context context);    
       
  -    /** Updates the current bean context with a new String value.
  +    
  +    /* XXX 
  +       Is update actually useful?
  +       None of the expression implementations i can find do anything when it's called.
  +       I suspect that it's been replaced by Updater
  +       but i maybe i'm missing something subtle
  +    */
  +    /** <p>Updates the current bean context with a new String value.
        * This is typically used when parsing XML and updating a beans value
  -     * from XML 
  +     * from XML.<p>
  +     *
  +     * @param context update this <code>Context</code> 
  +     * @param newValue the new value for this expression
        */
       public void update(Context context, String newValue);
   }
  
  
  
  1.5       +17 -3     jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/IteratorExpression.java
  
  Index: IteratorExpression.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/IteratorExpression.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- IteratorExpression.java	6 Jan 2003 22:50:44 -0000	1.4
  +++ IteratorExpression.java	9 Jan 2003 22:34:07 -0000	1.5
  @@ -81,13 +81,19 @@
       /** Use this <code>Expression</code> to perform initial evaluation*/
       private Expression expression;
       
  -    /** Construct <code>IteratorExpression</code> using given expression for
initial evaluation.
  +    /** 
  +     * Construct <code>IteratorExpression</code> using given expression for
initial evaluation.
  +     * @param expression this expression will be evaluated and the result converted to
an 
  +     *        iterator.
        */
       public IteratorExpression(Expression expression) {
           this.expression = expression;
       }
       
  -    /** Returns an interator over the current context */
  +    /** 
  +     * Returns an interator over the current context 
  +     * @see org.apache.commons.betwixt.expression.Expression
  +     */
       public Object evaluate(Context context) {        
           // evaluate wrapped expression against context
           Object value = expression.evaluate( context );
  @@ -124,11 +130,19 @@
           // so return an empty iterator
           return Collections.EMPTY_LIST.iterator();
       }
  -    
  +
  +    /** 
  +     * Do nothing
  +     * @see org.apache.commons.betwixt.expression.Expression
  +     */
       public void update(Context context, String newValue) {
           // do nothing
       }
       
  +    /**
  +     * Returns something useful for logging
  +     * @return string useful for logging
  +     */
       public String toString() {
           return "IteratorExpression [expression=" + expression + "]";
       }
  
  
  
  1.3       +3 -0      jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/Updater.java
  
  Index: Updater.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/Updater.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- Updater.java	2 Jul 2002 15:56:58 -0000	1.2
  +++ Updater.java	9 Jan 2003 22:34:07 -0000	1.3
  @@ -71,6 +71,9 @@
       /** Updates the current bean context with a new String value.
        * This is typically used when parsing XML and updating a bean value
        * from XML 
  +     *
  +     * @param context update the bean in this <code>Context</code>
  +     * @param newValue set value to this <code>Object</code>
        */
       public void update(Context context, Object newValue);
   }
  
  
  

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