rdonkin 2003/01/08 14:07:21
Modified: betwixt/src/java/org/apache/commons/betwixt
NodeDescriptor.java
betwixt/src/java/org/apache/commons/betwixt/digester
XMLIntrospectorHelper.java
betwixt/src/java/org/apache/commons/betwixt/io
BeanCreateRule.java BeanReader.java
SAXBeanWriter.java
Log:
Java docs improvements
Revision Changes Path
1.3 +7 -1
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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- NodeDescriptor.java 5 Jan 2003 17:18:32 -0000 1.2
+++ NodeDescriptor.java 8 Jan 2003 22:07:21 -0000 1.3
@@ -206,6 +206,9 @@
}
/**
+ * Gets the singular property type.
+ * That is, the type ignoring the Collection or Array.
+ *
* @return if this property is a 1-N relationship then this returns the type
* of a single property value.
*/
@@ -217,7 +220,10 @@
}
/**
- * Sets the singular property type (i.e. the type ignoring the Collection or
Array
+ * Sets the singular property type.
+ * That is, the type ignoring the Collection or Array.
+ *
+ * @param singularPropertyType
*/
public void setSingularPropertyType(Class singularPropertyType) {
this.singularPropertyType = singularPropertyType;
1.16 +1 -1
jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/XMLIntrospectorHelper.java
Index: XMLIntrospectorHelper.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/digester/XMLIntrospectorHelper.java,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- XMLIntrospectorHelper.java 7 Jan 2003 22:32:57 -0000 1.15
+++ XMLIntrospectorHelper.java 8 Jan 2003 22:07:21 -0000 1.16
@@ -390,7 +390,7 @@
rootDescriptor,
propertyName );
- if ( log.isDebugEnabled() ) {
+ if ( log.isDebugEnabled() ) {
log.debug( "!! " + propertyName + " -> " + descriptor );
log.debug( "!! " + name + " -> " +
descriptor.getPropertyName() );
}
1.17 +65 -6
jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/BeanCreateRule.java
Index: BeanCreateRule.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/BeanCreateRule.java,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- BeanCreateRule.java 6 Jan 2003 22:50:44 -0000 1.16
+++ BeanCreateRule.java 8 Jan 2003 22:07:21 -0000 1.17
@@ -91,7 +91,10 @@
/** Logger */
private static Log log = LogFactory.getLog( BeanCreateRule.class );
- /** Set log to be used by <code>BeanCreateRule</code> instances */
+ /**
+ * Set log to be used by <code>BeanCreateRule</code> instances
+ * @param aLog the <code>Log</code> implementation for this class to log to
+ */
public static void setLog(Log aLog) {
log = aLog;
}
@@ -113,6 +116,10 @@
/**
* Convenience constructor which uses <code>ID's</code> for matching.
+ *
+ * @param descriptor the <code>ElementDescriptor</code> describing the element
mapped
+ * @param beanClass the <code>Class</code> to be created
+ * @param pathPrefix the digester style path
*/
public BeanCreateRule(
ElementDescriptor descriptor,
@@ -123,6 +130,11 @@
/**
* Constructor taking a class.
+ *
+ * @param descriptor the <code>ElementDescriptor</code> describing the element
mapped
+ * @param beanClass the <code>Class</code> to be created
+ * @param pathPrefix the digester style path
+ * @param matchIDs should <code>ID</code>/<code>IDREF</code>'s be used for
matching
*/
public BeanCreateRule(
ElementDescriptor descriptor,
@@ -139,6 +151,9 @@
/**
* Convenience constructor which uses <code>ID's</code> for matching.
+ *
+ * @param descriptor the <code>ElementDescriptor</code> describing the element
mapped
+ * @param beanClass the <code>Class</code> to be created
*/
public BeanCreateRule( ElementDescriptor descriptor, Class beanClass ) {
this( descriptor, beanClass, true );
@@ -146,6 +161,10 @@
/**
* Constructor uses standard qualified name.
+ *
+ * @param descriptor the <code>ElementDescriptor</code> describing the element
mapped
+ * @param beanClass the <code>Class</code> to be created
+ * @param matchIDs should <code>ID</code>/<code>IDREF</code>'s be used for
matching
*/
public BeanCreateRule( ElementDescriptor descriptor, Class beanClass, boolean
matchIDs ) {
this( descriptor, beanClass, descriptor.getQualifiedName() + "/" , matchIDs
);
@@ -153,6 +172,10 @@
/**
* Convenience constructor which uses <code>ID's</code> for match.
+ *
+ * @param descriptor the <code>ElementDescriptor</code> describing the element
mapped
+ * @param context the <code>Context</code> to be used to evaluate expressions
+ * @param pathPrefix the digester path prefix
*/
public BeanCreateRule(
ElementDescriptor descriptor,
@@ -163,6 +186,11 @@
/**
* Constructor taking a context.
+ *
+ * @param descriptor the <code>ElementDescriptor</code> describing the element
mapped
+ * @param context the <code>Context</code> to be used to evaluate expressions
+ * @param pathPrefix the digester path prefix
+ * @param matchIDs should <code>ID</code>/<code>IDREF</code>'s be used for
matching
*/
public BeanCreateRule(
ElementDescriptor descriptor,
@@ -179,6 +207,12 @@
/**
* Base constructor (used by other constructors).
+ *
+ * @param descriptor the <code>ElementDescriptor</code> describing the element
mapped
+ * @param beanClass the <code>Class</code> of the bean to be created
+ * @param context the <code>Context</code> to be used to evaluate expressions
+ * @param pathPrefix the digester path prefix
+ * @param matchIDs should <code>ID</code>/<code>IDREF</code>'s be used for
matching
*/
private BeanCreateRule(
ElementDescriptor descriptor,
@@ -209,7 +243,7 @@
*
* @param attributes The attribute list of this element
*/
- public void begin(Attributes attributes) throws Exception {
+ public void begin(Attributes attributes) {
log.debug( "Called with descriptor: " + descriptor
+ " propertyType: " + descriptor.getPropertyType() );
@@ -301,7 +335,7 @@
/**
* Process the end of this element.
*/
- public void end() throws Exception {
+ public void end() {
if ( createdBean ) {
// force any setters of the parent bean to be called for this new bean
instance
@@ -339,8 +373,13 @@
// Implementation methods
//-------------------------------------------------------------------------
- /** Factory method to create new bean instances */
- protected Object createBean(Attributes attributes) throws Exception {
+ /**
+ * Factory method to create new bean instances
+ *
+ * @param attributes the <code>Attributes</code> used to match
<code>ID/IDREF</code>
+ * @return the created bean
+ */
+ protected Object createBean(Attributes attributes) {
//
// See if we've got an IDREF
//
@@ -386,7 +425,12 @@
}
}
- /** Add child rules for given descriptor at given prefix */
+ /**
+ * Add child rules for given descriptor at given prefix
+ *
+ * @param prefix add child rules at this (digester) path prefix
+ * @param currentDescriptor add child rules for this descriptor
+ */
protected void addChildRules(String prefix, ElementDescriptor currentDescriptor
) {
BeanReader digester = getBeanReader();
@@ -496,6 +540,8 @@
/**
* Get the associated bean reader.
+ *
+ * @return the <code>BeanReader</code digesting the xml
*/
protected BeanReader getBeanReader() {
// XXX this breaks the rule contact
@@ -506,6 +552,9 @@
/** Allows the navigation from a reference to a property object to the
descriptor defining what
* the property is. i.e. doing the join from a reference to a type to lookup
its descriptor.
* This could be done automatically by the NodeDescriptors. Refer to TODO.txt
for more info.
+ *
+ * @param propertyDescriptor find descriptor for property object referenced by
this descriptor
+ * @return descriptor for the singular property class type referenced.
*/
protected ElementDescriptor getElementDescriptor( ElementDescriptor
propertyDescriptor ) {
Class beanClass = propertyDescriptor.getSingularPropertyType();
@@ -525,6 +574,9 @@
/**
* Adds a new Digester rule to process the text as a primitive type
+ *
+ * @param path digester path where this rule will be attached
+ * @param childDescriptor update this <code>ElementDescriptor</code> with the
body text
*/
protected void addPrimitiveTypeRule(String path, final ElementDescriptor
childDescriptor) {
Rule rule = new Rule() {
@@ -537,6 +589,9 @@
/**
* Safely add a rule with given path.
+ *
+ * @param path the digester path to add rule at
+ * @param rule the <code>Rule</code> to add
*/
protected void addRule(String path, Rule rule) {
Rules rules = digester.getRules();
@@ -560,6 +615,8 @@
/**
* Get the map used to index beans (previously read in) by id.
* This is stored in the evaluation context.
+ *
+ * @return map indexing beans created by id
*/
protected Map getBeansById() {
//
@@ -580,6 +637,8 @@
/**
* Return something meaningful for logging.
+ *
+ * @return something useful for logging
*/
public String toString() {
return "BeanCreateRule [path prefix=" + pathPrefix + " descriptor=" +
descriptor + "]";
1.10 +25 -2
jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/BeanReader.java
Index: BeanReader.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/BeanReader.java,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- BeanReader.java 5 Jan 2003 17:18:32 -0000 1.9
+++ BeanReader.java 8 Jan 2003 22:07:21 -0000 1.10
@@ -104,6 +104,8 @@
* JAXP1.1 (such as WebLogic 6.0). Thanks for the request to change go to
* James House ([EMAIL PROTECTED]). This may help in places where
* you are able to load JAXP 1.1 classes yourself.
+ *
+ * @param parser use this <code>SAXParser</code>
*/
public BeanReader(SAXParser parser) {
super(parser);
@@ -115,6 +117,8 @@
* JAXP1.1 (such as WebLogic 6.0). Note that if you use this option you
* have to configure namespace and validation support yourself, as these
* properties only affect the SAXParser and emtpy constructor.
+ *
+ * @param reader use this <code>XMLReader</code> as source for SAX events
*/
public BeanReader(XMLReader reader) {
super(reader);
@@ -124,6 +128,9 @@
/**
* Registers a bean class which is used by the reader
* to deduce the digester rules.
+ *
+ * @param beanClass the <code>Class</code> to be registered
+ * @throws IntrospectionException if the bean introspection fails
*/
public void registerBeanClass(Class beanClass) throws IntrospectionException {
if ( ! registeredClasses.contains( beanClass ) ) {
@@ -148,6 +155,11 @@
/**
* Registers a bean class at the given path expression
* which is used by the reader to deduce the digester rules.
+ *
+ * @param path the xml path expression where the class is to registered.
+ * This should be in digester path notation
+ * @param beanClass the <code>Class</code> to be registered
+ * @throws IntrospectionException if the bean introspection fails
*/
public void registerBeanClass(String path, Class beanClass) throws
IntrospectionException {
if ( ! registeredClasses.contains( beanClass ) ) {
@@ -173,6 +185,8 @@
* created by the <code>XMLIntrospector</code>.
* One way in which the mapping can be customized is by
* altering the <code>XMLIntrospector</code>. </p>
+ *
+ * @return the <code>XMLIntrospector</code> used for the introspection
*/
public XMLIntrospector getXMLIntrospector() {
return introspector;
@@ -196,7 +210,7 @@
/**
* <p> Get the current level for logging. </p>
*
- * @return a <code>org.apache.commons.logging.Log</code> level constant
+ * @return the <code>Log</code> implementation this class logs to
*/
public Log getLog() {
return log;
@@ -205,7 +219,7 @@
/**
* <p> Set the current logging level. </p>
*
- * @param level a <code>org.apache.commons.logging.Log</code> level constant
+ * @param log the <code>Log</code>implementation to use for logging
*/
public void setLog(Log log) {
this.log = log;
@@ -214,6 +228,9 @@
/**
* Should the reader use <code>ID</code> attributes to match beans.
+ *
+ * @return true if <code>ID</code> and <code>IDREF</code>
+ * attributes should be used to match instances
*/
public boolean getMatchIDs() {
return matchIDs;
@@ -221,6 +238,8 @@
/**
* Set whether the read should use <code>ID</code> attributes to match beans.
+ *
+ * @param matchIDs pass true if <code>ID</code>'s should be matched
*/
public void setMatchIDs(boolean matchIDs) {
this.matchIDs = matchIDs;
@@ -231,6 +250,10 @@
/**
* Adds a new bean create rule for the specified path
+ *
+ * @param path the digester path at which this rule should be added
+ * @param elementDescriptor the <code>ElementDescriptor</code> describes the
expected element
+ * @param beanClass the <code>Class</code> of the bean created by this rule
*/
protected void addBeanCreateRule(
String path,
1.6 +42 -16
jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/SAXBeanWriter.java
Index: SAXBeanWriter.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/betwixt/src/java/org/apache/commons/betwixt/io/SAXBeanWriter.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- SAXBeanWriter.java 15 Dec 2002 19:03:34 -0000 1.5
+++ SAXBeanWriter.java 8 Jan 2003 22:07:21 -0000 1.6
@@ -86,21 +86,19 @@
/** Log used for logging (Doh!) */
private Log log = LogFactory.getLog( SAXBeanWriter.class );
- private String lastElementName;
-
/**
* Place holder for elements that are started.
*/
private Stack elementStack;
-
+ /** Current element's attributes. */
private AttributesImpl attributes;
-
+ /** Is there a element currently waiting to be written out? */
private boolean elementWaiting = false;
/**
* <p> Constructor sets writer used for output.</p>
*
- * @param writer write out representations to this writer
+ * @param contentHandler feed events to this content handler
*/
public SAXBeanWriter(ContentHandler contentHandler) {
this.contentHandler = contentHandler;
@@ -108,6 +106,8 @@
/**
* <p> Set the log implementation used. </p>
+ *
+ * @return <code>Log</code> implementation that this class logs to
*/
public Log getLog() {
return log;
@@ -126,7 +126,12 @@
// Expression methods
//-------------------------------------------------------------------------
- /** Express an element tag start using given qualified name */
+ /**
+ * Express an element tag start using given qualified name
+ *
+ * @param qualifiedName the fully qualified element name
+ * @throws SAXException if the <code>ContentHandler</code> has a problem
+ */
protected void expressElementStart(String qualifiedName) throws SAXException {
if (elementStack == null) {
elementStack = new Stack();
@@ -139,12 +144,18 @@
elementWaiting = true;
}
+ /** Element end */
protected void expressTagClose() {
// using this could probably make life easier
// but i only know that i needed it after i'd written the rest
}
- /** Express an element end tag using given qualifiedName */
+ /**
+ * Express an element end tag
+ *
+ * @param qualifiedName the fully qualified name of the element
+ * @throws SAXException if the <code>ContentHandler</code> has a problem
+ */
protected void expressElementEnd(String qualifiedName) throws SAXException {
if (elementWaiting) {
elementWaiting = false;
@@ -154,14 +165,21 @@
contentHandler.endElement("","",qualifiedName);
}
- /** Express an empty element end */
+ /**
+ * Express an empty element end
+ * @throws SAXException if the <code>ContentHandler</code> has a problem
+ */
protected void expressElementEnd() throws SAXException {
// last element name must be correct since there haven't been any tag in
between
String lastElement = (String) elementStack.peek();
contentHandler.endElement("","",lastElement);
}
- /** Express body text */
+ /**
+ * Express body text
+ * @param text the element body text
+ * @throws SAXException if the <code>ContentHandler</code> has a problem
+ */
protected void expressBodyText(String text) throws SAXException {
// FIX ME
// CHECK UNICODE->CHAR CONVERSION!
@@ -174,7 +192,12 @@
contentHandler.characters(body, 0, body.length);
}
- /** Express an attribute */
+ /**
+ * Express an attribute
+ * @param qualifiedName the fully qualified attribute name
+ * @param value the attribute value
+ * @throws SAXException if the <code>ContentHandler</code> has a problem
+ */
protected void expressAttribute(
String qualifiedName,
String value)
@@ -189,6 +212,10 @@
// Implementation methods
//-------------------------------------------------------------------------
+ /**
+ * Send the start element event to the <code>ContentHandler</code>
+ * @throws SAXException if the <code>ContentHandler</code> has a problem
+ */
private void sendElementStart() throws SAXException {
String lastElement = (String)elementStack.peek();
contentHandler.startElement("","",lastElement,attributes);
@@ -199,7 +226,6 @@
*
* @see org.apache.commons.betwixt.io.AbstractBeanWriter#end()
*/
-
public void start() throws SAXException {
contentHandler.startDocument();
}
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
