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