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