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:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>