rdonkin 2003/01/12 05:52:03
Modified: betwixt/src/java/org/apache/commons/betwixt
ElementDescriptor.java NodeDescriptor.java
betwixt/src/java/org/apache/commons/betwixt/expression
Context.java MethodExpression.java
MethodUpdater.java
Log:
Improved java docs.
Revision Changes Path
1.6 +122 -27
jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/ElementDescriptor.java
Index: ElementDescriptor.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/ElementDescriptor.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- ElementDescriptor.java 6 Jan 2003 22:50:44 -0000 1.5
+++ ElementDescriptor.java 12 Jan 2003 13:52:03 -0000 1.6
@@ -114,56 +114,91 @@
*/
private boolean wrapCollectionsInElement = true;
- /** Base constructor */
+ /**
+ * Constructs an <code>ElementDescriptor</code> that refers to a primitive type.
+ */
public ElementDescriptor() {
}
-
+
+ /**
+ * Base constructor.
+ * @param primitiveType if true, this element refers to a primitive type
+ */
public ElementDescriptor(boolean primitiveType) {
this.primitiveType = primitiveType;
}
- /** Creates a <code>ElementDescriptor</code> with no namespace URI or prefix */
+ /**
+ * Creates a ElementDescriptor with no namespace URI or prefix.
+ *
+ * @param localName the (xml) local name of this node.
+ * This will be used to set both qualified and local name for this name.
+ */
public ElementDescriptor(String localName) {
super( localName );
}
- public String toString() {
- return
- "ElementDescriptor[qname=" + getQualifiedName() + ",pname=" +
getPropertyName()
- + ",class=" + getPropertyType() + ",singular=" +
getSingularPropertyType()
- + ",updater=" + getUpdater() + "]";
- }
+
- /** Creates a <code>ElementDescriptor</code> with namespace URI and qualified
name */
+ /**
+ * Creates a <code>ElementDescriptor</code> with namespace URI and qualified
name
+ * @param localName the (xml) local name of this node
+ * @param qualifiedName the (xml) qualified name of this node
+ * @param uri the (xml) namespace prefix of this node
+ */
public ElementDescriptor(String localName, String qualifiedName, String uri) {
super(localName, qualifiedName, uri);
}
- /** Returns true if this element has child elements */
+ /**
+ * Returns true if this element has child <code>ElementDescriptors</code>
+ * @return true if this element has child elements
+ * @see #getElementDescriptors
+ */
public boolean hasChildren() {
return elementDescriptors != null && elementDescriptors.length > 0;
}
- /** Returns true if this element has attributes */
+ /**
+ * Returns true if this element has <code>AttributeDescriptors</code>
+ * @return true if this element has attributes
+ * @see #getAttributeDescriptors
+ */
public boolean hasAttributes() {
return attributeDescriptors != null && attributeDescriptors.length > 0;
}
- /** Specifies if this is a collection element
- * Normally only used with the WrapCollectionsInElement setting
- * @param isCollection
+ /**
+ * Sets whether <code>Collection</code> bean properties should wrap items in a
parent element.
+ * In other words, should the mapping for bean properties which are
<code>Collection</code>s
+ * enclosed the item elements within a parent element.
+ * Normally only used when this describes a collection bean property.
+ *
+ * @param wrapCollectionsInElement true if the elements for the items in the
collection
+ * should be contained in a parent element
*/
public void setWrapCollectionsInElement(boolean wrapCollectionsInElement) {
this.wrapCollectionsInElement = wrapCollectionsInElement;
}
/**
- * Returns if this element is a collection element
+ * Returns true if collective bean properties should wrap the items in a parent
element.
+ * In other words, should the mapping for bean properties which are
<code>Collection</code>s
+ * enclosed the item elements within a parent element.
+ * Normally only used when this describes a collection bean property.
+ *
+ * @return true if the elements for the items in the collection should be
contained
+ * in a parent element
*/
public boolean isWrapCollectionsInElement() {
return this.wrapCollectionsInElement;
}
+ /**
+ * Adds an attribute to the element this <code>ElementDescriptor</code>
describes
+ * @param descriptor the <code>AttributeDescriptor</code> that will be added to
the
+ * attributes associated with element this <code>ElementDescriptor</code>
describes
+ */
public void addAttributeDescriptor(AttributeDescriptor descriptor) {
if ( attributeList == null ) {
attributeList = new ArrayList();
@@ -173,7 +208,12 @@
}
- /** Returns the attribute descriptors for this element */
+ /**
+ * Returns the attribute descriptors for this element
+ *
+ * @return descriptors for the attributes of the element that this
+ * <code>ElementDescriptor</code> describes
+ */
public AttributeDescriptor[] getAttributeDescriptors() {
if ( attributeDescriptors == null ) {
if ( attributeList == null ) {
@@ -189,12 +229,24 @@
return attributeDescriptors;
}
- /** Set <code>AttributesDescriptors</code> for this element */
+ /**
+ * Sets the <code>AttributesDescriptors</code> for this element.
+ * This sets descriptors for the attributes of the element describe by the
+ * <code>ElementDescriptor</code>.
+ *
+ * @param attributeDescriptors the <code>AttributeDescriptor</code> describe
the attributes
+ * of the element described by this <code>ElementDescriptor</code>
+ */
public void setAttributeDescriptors(AttributeDescriptor[] attributeDescriptors)
{
this.attributeDescriptors = attributeDescriptors;
this.attributeList = null;
}
+ /**
+ * Adds a descriptor for a child element.
+ *
+ * @param descriptor the <code>ElementDescriptor</code> describing the child
element to add
+ */
public void addElementDescriptor(ElementDescriptor descriptor) {
if ( elementList == null ) {
elementList = new ArrayList();
@@ -203,7 +255,11 @@
elementDescriptors = null;
}
- /** Returns the child element descriptors for this element */
+ /**
+ * Returns descriptors for the child elements of the element this describes.
+ * @return the <code>ElementDescriptor</code> describing the child elements
+ * of the element that this <code>ElementDescriptor</code> describes
+ */
public ElementDescriptor[] getElementDescriptors() {
if ( elementDescriptors == null ) {
if ( elementList == null ) {
@@ -219,28 +275,44 @@
return elementDescriptors;
}
- /** Set descriptors for child element of this element */
+ /**
+ * Sets the descriptors for the child element of the element this describes.
+ * @param elementDescriptors the <code>ElementDescriptor</code>s of the element
+ * that this describes
+ */
public void setElementDescriptors(ElementDescriptor[] elementDescriptors) {
this.elementDescriptors = elementDescriptors;
this.elementList = null;
}
- /** Returns the expression used to evaluate the new context of this element */
+ /**
+ * Returns the expression used to evaluate the new context of this element.
+ * @return the expression used to evaluate the new context of this element
+ */
public Expression getContextExpression() {
return contextExpression;
}
- /** Sets the expression used to evaluate the new context of this element */
+ /**
+ * Sets the expression used to evaluate the new context of this element
+ * @param contextExpression the expression used to evaluate the new context of
this element
+ */
public void setContextExpression(Expression contextExpression) {
this.contextExpression = contextExpression;
}
- /** @return whether this element refers to a primitive type (or property of a
parent object) */
+ /**
+ * Returns true if this element refers to a primitive type property
+ * @return whether this element refers to a primitive type (or property of a
parent object)
+ */
public boolean isPrimitiveType() {
return primitiveType;
}
- /** Sets whether this element refers to a primitive type (or property of a
parent object) */
+ /**
+ * Sets whether this element refers to a primitive type (or property of a
parent object)
+ * @param primitiveType true if this element refers to a primitive type
+ */
public void setPrimitiveType(boolean primitiveType) {
this.primitiveType = primitiveType;
}
@@ -249,9 +321,13 @@
//-------------------------------------------------------------------------
/**
- * Lazily creates the mutable List, nullifiying the array so that
+ * Lazily creates the mutable List.
+ * This nullifies {@link #attributeDescriptors} so that
* as items are added to the list the Array is ignored until it is
- * explicitly asked for
+ * explicitly asked for.
+ *
+ * @return list of <code>AttributeDescriptors</code>'s describing the attributes
+ * of the element that this <code>ElementDescriptor</code> describes
*/
protected List getAttributeList() {
if ( attributeList == null ) {
@@ -270,7 +346,15 @@
return attributeList;
}
- /** Lazily creates the mutable List */
+ /**
+ * Lazily creates the mutable List of child elements.
+ * This nullifies {@link #elementDescriptors} so that
+ * as items are added to the list the Array is ignored until it is
+ * explicitly asked for.
+ *
+ * @return list of <code>ElementDescriptor</code>'s describe the child elements
of
+ * the element that this <code>ElementDescriptor</code> describes
+ */
protected List getElementList() {
if ( elementList == null ) {
if ( elementDescriptors != null ) {
@@ -288,4 +372,15 @@
return elementList;
}
+ /**
+ * Returns something useful for logging.
+ *
+ * @return a string useful for logging
+ */
+ public String toString() {
+ return
+ "ElementDescriptor[qname=" + getQualifiedName() + ",pname=" +
getPropertyName()
+ + ",class=" + getPropertyType() + ",singular=" +
getSingularPropertyType()
+ + ",updater=" + getUpdater() + "]";
+ }
}
1.4 +71 -26
jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/NodeDescriptor.java
Index: NodeDescriptor.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/NodeDescriptor.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- NodeDescriptor.java 8 Jan 2003 22:07:21 -0000 1.3
+++ NodeDescriptor.java 12 Jan 2003 13:52:03 -0000 1.4
@@ -77,6 +77,7 @@
/** The local name of this node without any namespace prefix */
private String localName;
+ /** The qualified name of the xml node associated with this descriptor. */
private String qualifiedName;
/** The namespace URI of this node */
private String uri = "";
@@ -96,34 +97,50 @@
public NodeDescriptor() {
}
- /** Creates a NodeDescriptor with no namespace URI or prefix */
+ /**
+ * Creates a NodeDescriptor with no namespace URI or prefix.
+ *
+ * @param localName the (xml) local name of this node.
+ * This will be used to set both qualified and local name for this name.
+ */
public NodeDescriptor(String localName) {
this.localName = localName;
this.qualifiedName = localName;
}
- /** Creates a NodeDescriptor with namespace URI and qualified name */
+ /**
+ * Creates a NodeDescriptor with namespace URI and qualified name
+ * @param localName the (xml) local name of this node
+ * @param qualifiedName the (xml) qualified name of this node
+ * @param uri the (xml) namespace prefix of this node
+ */
public NodeDescriptor(String localName, String qualifiedName, String uri) {
this.localName = localName;
this.qualifiedName = qualifiedName;
this.uri = uri;
}
- /** Returns the local name, excluding any namespace prefix
- */
+ /**
+ * Gets the local name, excluding any namespace prefix
+ * @return the (xml) local name of this node
+ */
public String getLocalName() {
return localName;
}
- /** Sets the local name
- */
+ /**
+ * Sets the local name
+ * @param localName the (xml) local name of this node
+ */
public void setLocalName(String localName) {
this.localName = localName;
}
- /** Returns the qualified name, including any namespace prefix
- */
+ /**
+ * Gets the qualified name, including any namespace prefix
+ * @return the (xml) qualified name of this node. This may be null.
+ */
public String getQualifiedName() {
if ( qualifiedName == null ) {
qualifiedName = localName;
@@ -131,14 +148,17 @@
return qualifiedName;
}
- /** Sets the qualified name
- */
+ /**
+ * Sets the qualified name
+ * @param qualifiedName the new (xml) qualified name for this node
+ */
public void setQualifiedName(String qualifiedName) {
this.qualifiedName = qualifiedName;
}
/**
- * Returns the namespace URI that this node belongs to
+ * Gets the (xml) namespace URI prefix for this node.
+ * @return the namespace URI that this node belongs to
* or "" if there is no namespace defined
*/
public String getURI() {
@@ -146,7 +166,9 @@
}
- /** Sets the namespace URI that this node belongs to.
+ /**
+ * Sets the namespace URI that this node belongs to.
+ * @param uri the new namespace uri for this node
*/
public void setURI(String uri) {
if ( uri == null ) {
@@ -158,39 +180,62 @@
this.uri = uri;
}
- /** Returns the expression used to evaluate the text value of this node */
+ /**
+ * Gets the expression used to evaluate the text value of this node
+ * for a particular <code>Context</code>.
+ * @return the expression used to evaluate the text value of this node
+ */
public Expression getTextExpression() {
return textExpression;
}
- /** Sets the expression used to evaluate the text value of this node */
+ /**
+ * Sets the expression used to evaluate the text value of this node
+ * for a particular <code>Context</code>
+ * @param textExpression the Expression to be used to evaluate the value of
this node
+ */
public void setTextExpression(Expression textExpression) {
this.textExpression = textExpression;
}
- /** the updater used to update the current bean from the text value of this
node */
+ /**
+ * Gets the <code>Updater</code> used to update a <code>Context</code> from the
text value
+ * corresponding to this node in an xml document
+ * @return the Update that should be used to update the value of this node
+ */
public Updater getUpdater() {
return updater;
}
- /** sets the updater used to update the current bean from the text value of
this node */
+ /**
+ * Sets the <code>Updater</code> used to update a <code>Context</code> from the
text value
+ * corresponding to this node in an xml document
+ * @param updater the Updater to be used to update the values of this node
+ */
public void setUpdater(Updater updater) {
this.updater = updater;
}
- /** @return the property type associated with this node, if any */
+ /**
+ * Gets the type of the bean property associated with this node, if any
+ * @return the property type associated with this node, if any
+ */
public Class getPropertyType() {
return propertyType;
}
- /** Sets the property type associated with this node, if any */
+ /**
+ * Sets the type of the bean property associated with this node, if any
+ * @param propertyType the Class of the bean property
+ */
public void setPropertyType(Class propertyType) {
this.propertyType = propertyType;
}
/**
- * @return the property expression to which this node refers to,
+ *
+ * @return the name of the bean property to which this node refers to,
* or null if it is just a constant
*/
public String getPropertyName() {
@@ -198,16 +243,16 @@
}
/**
- * Sets the property expression to which this node refers to,
- * or null if it is just a constant
+ * Sets the name of the bean property to which this node refers to,
+ * @param propertyName the name of the bean property.
+ * Or null, if this node is not mapped to to a bean property
*/
public void setPropertyName(String propertyName) {
this.propertyName = propertyName;
}
/**
- * Gets the singular property type.
- * That is, the type ignoring the Collection or Array.
+ * Gets the underlying type ignoring any wrapping a Collection or Array.
*
* @return if this property is a 1-N relationship then this returns the type
* of a single property value.
@@ -220,10 +265,10 @@
}
/**
- * Sets the singular property type.
- * That is, the type ignoring the Collection or Array.
+ * Sets the underlying type ignoring any wrapping Collection or Array.
*
- * @param singularPropertyType
+ * @param singularPropertyType the Class of the items in the Collection or
Array.
+ * If node is associated with a collective bean property, then this should not
be null.
*/
public void setSingularPropertyType(Class singularPropertyType) {
this.singularPropertyType = singularPropertyType;
1.4 +32 -11
jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/Context.java
Index: Context.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/Context.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Context.java 11 Jan 2003 10:38:55 -0000 1.3
+++ Context.java 12 Jan 2003 13:52:03 -0000 1.4
@@ -130,54 +130,75 @@
/** Returns a new child context with the given bean but the same log and
variables.
*
* @param newBean create a child context for this bean
+ * @return new Context with new bean but shared variables
*/
public Context newContext(Object newBean) {
return new Context(newBean, variables, log);
}
- /** Returns the current bean.
- */
+ /**
+ * Gets the current bean.
+ * @return the bean against which expressions are evaluated
+ */
public Object getBean() {
return bean;
}
- /** Set the current bean.
+ /**
+ * Set the current bean.
+ * @param bean the Object against which expressions will be evaluated
*/
public void setBean(Object bean) {
this.bean = bean;
}
- /** Get context variables.
- */
+ /**
+ * Gets context variables.
+ * @return map containing variable values keyed by variable name
+ */
public Map getVariables() {
return variables;
}
- /** Set context variables.
+ /**
+ * Sets context variables.
+ * @param variables map containing variable values indexed by varibable name
Strings
*/
public void setVariables(Map variables) {
this.variables = variables;
}
- /** Get the value of a particular context variable.
+ /**
+ * Gets the value of a particular context variable.
+ * @param name the name of the variable whose value is to be returned
+ * @return the variable value or null if the variable isn't set
*/
public Object getVariable(String name) {
return variables.get( name );
}
- /** Set the value of a particular context variable.
+ /**
+ * Sets the value of a particular context variable.
+ * @param name the name of the variable
+ * @param value the value of the variable
*/
public void setVariable(String name, Object value) {
variables.put( name, value );
}
- /** Get the current log.
- */
+ /**
+ * Gets the current log.
+ *
+ * @return the implementation to which this class logs
+ */
public Log getLog() {
return log;
}
- /** Set the logger used to log (Doh!).
+ /**
+ * Set the log implementation to which this class logs
+ *
+ * @param log the implemetation that this class should log to
*/
public void setLog(Log log) {
this.log = log;
1.4 +58 -13
jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/MethodExpression.java
Index: MethodExpression.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/MethodExpression.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- MethodExpression.java 6 Jan 2003 22:50:44 -0000 1.3
+++ MethodExpression.java 12 Jan 2003 13:52:03 -0000 1.4
@@ -82,12 +82,23 @@
public MethodExpression() {
}
- /** Convenience constructor sets method property */
+ /**
+ * Convenience constructor sets method property
+ * @param method the Method whose return value when invoked on the bean
+ * will the value of this expression
+ */
public MethodExpression(Method method) {
this.method = method;
}
- /** Evaluate by calling the read method on the current bean */
+ /**
+ * Evaluate by calling the read method on the current bean
+ *
+ * @param context the context against which this expression will be evaluated
+ * @return the value returned by the method when it's invoked on the context's
bean,
+ * so long as the method can be invoked.
+ * Otherwise, null.
+ */
public Object evaluate(Context context) {
Object bean = context.getBean();
if ( bean != null ) {
@@ -113,16 +124,28 @@
return null;
}
+ /**
+ * 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 method used to evaluate this expression.
+ * @return the method whose value (when invoked against the context's bean)
will be used
+ * to evaluate this expression.
+ */
public Method getMethod() {
return method;
}
- /** Sets the constant value of this expression */
+ /**
+ * Sets the method used to evaluate this expression
+ * @param method method whose value (when invoked against the context's bean)
will be used
+ * to evaluate this expression
+ */
public void setMethod(Method method) {
this.method = method;
}
@@ -130,7 +153,10 @@
// Implementation methods
//-------------------------------------------------------------------------
- /** Allows derived objects to create arguments for the method call */
+ /**
+ * Allows derived objects to create arguments for the method call
+ * @return {@link #NULL_ARGUMENTS}
+ */
protected Object[] getArguments() {
return NULL_ARGUMENTS;
}
@@ -138,20 +164,32 @@
/** Tries to find an alternate method for the given type using interfaces
* which gets around the problem of inner classes,
* such as on Map.Entry implementations.
+ *
+ * @param type the Class whose methods are to be searched
+ * @param method the Method for which an alternative is to be search for
+ * @return the alternative Method, if one can be found. Otherwise null.
*/
protected Method findAlternateMethod(
Class type,
- Method method )
- throws
- NoSuchMethodException {
+ Method method ) {
+ // XXX
+ // Would it be better to use the standard reflection code in eg. lang
+ // since this code contains workarounds for common JVM bugs?
+ //
Class[] interfaces = type.getInterfaces();
if ( interfaces != null ) {
String name = method.getName();
for ( int i = 0, size = interfaces.length; i < size; i++ ) {
Class otherType = interfaces[i];
- Method alternate = otherType.getMethod( name, NULL_CLASSES );
- if ( alternate != null && alternate != method ) {
- return alternate;
+ //
+ // catch NoSuchMethodException so that all interfaces will be tried
+ try {
+ Method alternate = otherType.getMethod( name, NULL_CLASSES );
+ if ( alternate != null && alternate != method ) {
+ return alternate;
+ }
+ } catch (NoSuchMethodException e) {
+ // swallow
}
}
}
@@ -159,15 +197,22 @@
}
/**
- * <p> Log error to context's logger. </p>
+ * <p>Log error to context's logger.</p>
*
- * <p> Allows derived objects to handle exceptions differently. </p>
+ * <p>Allows derived objects to handle exceptions differently.</p>
+ *
+ * @param context the Context being evaluated when the exception occured
+ * @param e the exception to handle
*/
protected void handleException(Context context, Exception e) {
// use the context's logger to log the problem
context.getLog().error("[MethodExpression] Cannot evaluate expression", e);
}
+ /**
+ * Returns something useful for logging.
+ * @return something useful for logging
+ */
public String toString() {
return "MethodExpression [method=" + method + "]";
}
1.7 +28 -5
jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/MethodUpdater.java
Index: MethodUpdater.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/expression/MethodUpdater.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- MethodUpdater.java 6 Jan 2003 22:50:44 -0000 1.6
+++ MethodUpdater.java 12 Jan 2003 13:52:03 -0000 1.7
@@ -79,7 +79,10 @@
/** Logger */
private static Log log = LogFactory.getLog( MethodUpdater.class );
- /** Programmatically set log */
+ /**
+ * Programmatically set log
+ * @param aLog the implementation to which this class should log
+ */
public static void setLog( Log aLog ) {
log = aLog;
}
@@ -93,12 +96,19 @@
public MethodUpdater() {
}
- /** Convenience constructor sets method property */
+ /**
+ * Convenience constructor sets method property
+ * @param method the Method to be invoked on the context's bean in the update
+ */
public MethodUpdater(Method method) {
setMethod( method );
}
- /** Updates the current bean context with the given String value */
+ /**
+ * Updates the current bean context with the given String value
+ * @param context the Context to be updated
+ * @param newValue the update to this new value
+ */
public void update(Context context, Object newValue) {
Object bean = context.getBean();
if ( bean != null ) {
@@ -142,12 +152,19 @@
}
}
- /** Gets the constant value of this expression */
+ /**
+ * Gets the method which will be invoked by the update
+ *
+ * @return the Method to be invoked by the update
+ */
public Method getMethod() {
return method;
}
- /** Sets the constant value of this expression */
+ /**
+ * Sets the constant value of this expression
+ * @param method the Method to be invoked by the update
+ */
public void setMethod(Method method) {
this.method = method;
Class[] types = method.getParameterTypes();
@@ -162,11 +179,17 @@
/**
* Strategy method to allow derivations to handle exceptions differently.
+ * @param context the Context being updated when this exception occured
+ * @param e the Exception that occured during the update
*/
protected void handleException(Context context, Exception e) {
log.info( "Caught exception: " + e, e );
}
+ /**
+ * Returns something useful for logging.
+ * @return something useful for logging
+ */
public String toString() {
return "MethodUpdater [method=" + method + "]";
}
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
