You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by di...@apache.org on 2005/09/27 22:51:42 UTC
svn commit: r292040 - in
/webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om:
OMContainer.java OMElement.java OMNode.java impl/llom/OMDocumentImpl.java
impl/llom/OMElementImpl.java impl/llom/OMNodeImpl.java
Author: dims
Date: Tue Sep 27 13:51:38 2005
New Revision: 292040
URL: http://svn.apache.org/viewcvs?rev=292040&view=rev
Log:
fix for AXIS2-243 - Missing javadoc, javadoc warnings, undocumented behavior\n from Eric Johnson
Modified:
webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/OMContainer.java
webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/OMElement.java
webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/OMNode.java
webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/impl/llom/OMDocumentImpl.java
webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/impl/llom/OMElementImpl.java
webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/impl/llom/OMNodeImpl.java
Modified: webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/OMContainer.java
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/OMContainer.java?rev=292040&r1=292039&r2=292040&view=diff
==============================================================================
--- webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/OMContainer.java (original)
+++ webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/OMContainer.java Tue Sep 27 13:51:38 2005
@@ -19,16 +19,80 @@
import javax.xml.namespace.QName;
import java.util.Iterator;
+/**
+ * Captures the operations related to containment shared by both a document and an element.
+ *
+ * <p>Exposes the ability to add, find, and iterate over the children of a document or
+ * element.</p>
+ */
public interface OMContainer {
+ /**
+ * This will add the given node as the last child.
+ *
+ * child to the element. One must preserve the order of children, in this operation
+ * Tip : appending the new child is prefered
+ *
+ * @param omNode
+ */
public void addChild(OMNode omNode);
- public Iterator getChildrenWithName(QName elementQName) throws OMException;
+ /**
+ * Returns an iterator for child nodes matching the criteria indicated by the given QName.
+ *
+ * <p>This function searches in three ways:
+ * <ul>
+ * <li>Exact match - Both parts of the passed QName are non-null. Only children with the
+ * same namespace and local name will be returned.
+ * </li>
+ * <li>Namespace match - The local name of the passed QName is null. All children matching the
+ * namespace will be returned by the iterator.
+ * </li>
+ * <li>Local name match - The namespace of the passed QName is null. All children with the
+ * matching local name will be returned by the iterator.
+ * </li>
+ * </ul>
+ *
+ * <p>
+ * <b>Example:</b> <code>header.getChildrenWithName( new QName(ADDRESSING_NAMESPACE, null));</code>
+ * will return all of the "addressing" headers.
+ * </p>
+ *
+ * @param elementQName The QName specifying namespace and local name to match.
+ * @return An iterator of {@link OMElement} items that match the given QName appropriately.
+ */
+ public Iterator getChildrenWithName(QName elementQName);
+ /**
+ * Returns the first child in document order that matches the given QName criteria.
+ *
+ * <p>The QName filter is applied as in the function {@link #getChildrenWithName}.</p>
+ *
+ * @param elementQName The QName to use for matching.
+ *
+ * @return The first element in document order that matches the <tt>elementQName</tt> criteria.
+ *
+ * @see #getChildrenWithName
+ *
+ * @throws OMException Could indirectly trigger building of child nodes.
+ */
public OMElement getFirstChildWithName(QName elementQName) throws OMException;
+ /**
+ * Returns an iterator for the children of the container.
+ *
+ * @return Returns a {@link Iterator} of children, all of which implement {@link OMNode}.
+ *
+ * @see #getFirstChildWithName
+ * @see #getChildrenWithName
+ */
public Iterator getChildren();
+ /**
+ * Get the first child.
+ *
+ * @return Returns the first child. May return null if the container has no children.
+ */
public OMNode getFirstChild();
public boolean isComplete();
Modified: webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/OMElement.java
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/OMElement.java?rev=292040&r1=292039&r2=292040&view=diff
==============================================================================
--- webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/OMElement.java (original)
+++ webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/OMElement.java Tue Sep 27 13:51:38 2005
@@ -21,109 +21,116 @@
import java.util.Iterator;
/**
- * Interface OMElement
+ * A particular kind of node that represents an element infoset information item.
+ *
+ * <p>An element has a collection of children, attributes, and namespaces.</p>
+ *
+ * <p>In contrast with DOM, this interface exposes namespaces separately from the
+ * attributes.</p>
*/
public interface OMElement extends OMNode, OMContainer {
- /**
- * This will add child to the element. One must preserve the order of children, in this operation
- * Tip : appending the new child is prefered
- *
- * @param omNode
- */
- public void addChild(OMNode omNode);
-
- /**
- * This will search for children with a given QName and will return an iterator to traverse through
- * the OMNodes.
- * This will match localName and namespaceURI only. localName only or namespaceURI only can also be given. But
- * the other parameter should be set to null
- * Example : If you want to get all the addressing headers, header.getChildrenWithName(new QName(AddressingNamespace, null))
- * will do.
- *
- * @param elementQName
- * @return
- * @throws OMException
- */
- public Iterator getChildrenWithName(QName elementQName) throws OMException;
-
- /**
- * This will return the first matched child, return null if none found
- *
- * @param elementQName
- * @return
- * @throws OMException
- */
- public OMElement getFirstChildWithName(QName elementQName) throws OMException;
-
-
- /**
- * This returns a collection of this element.
- * Children can be of types OMElement, OMText.
- *
- * @return
- */
- public Iterator getChildren();
/**
* Returns a filtered list of children - just the elements.
*
* @return an iterator over the child elements
+ *
+ * @see #getChildren()
+ * @see #getChildrenWithName(javax.xml.namespace.QName)
*/
public Iterator getChildElements();
/**
* THis will create a namespace in the current element scope
*
- * @param uri
- * @param prefix
- * @return
+ * @param uri The namespace to declare in the current scope. The
+ * caller is expected to ensure that the URI is a valid namespace name.
+ * @param prefix The prefix to associate with the given namespace.
+ * The caller is expected to ensure that this is a valid XML prefix.
+ *
+ * @return The created namespace information item.
+ *
+ * @see #declareNamespace(OMNamespace)
+ * @see #findNamespace(String, String)
+ * @see #getAllDeclaredNamespaces()
*/
public OMNamespace declareNamespace(String uri, String prefix);
/**
- * @param namespace
- * @return
+ * Declare a namespace with the element as its scope.
+ *
+ * @param namespace The namespace to declare
+ *
+ * @return The namespace parameter passed.
+ *
+ * @see #declareNamespace(String, String)
+ * @see #findNamespace(String, String)
+ * @see #getAllDeclaredNamespaces()
*/
public OMNamespace declareNamespace(OMNamespace namespace);
/**
* This will find a namespace with the given uri and prefix, in the scope of the hierarchy.
- * This will start to find from the current element and goes up in the hiararchy until this finds one.
- * If none is found, return null
*
- * @param uri
- * @param prefix
- * @return
- * @throws OMException
+ * <p>This will search from the current element and go up the hiararchy until a match is found.
+ * If no match is found, return <tt>null</tt>.</p>
+ *
+ * <p>Either <tt>prefix</tt> or <tt>uri</tt> should be null. Results are undefined
+ * if both are specified.</p>
+ *
+ * @param uri The namespace to look for. If this is specified, <tt>prefix</tt> should be null.
+ * @param prefix The prefix to look for. If this is specified, <tt>uri</tt> should be null.
+ *
+ * @return The matching namespace declaration, or <tt>null</tt> if none was found.
+ *
+ * @see #declareNamespace(String, String)
+ * @see #declareNamespace(OMNamespace)
+ * @see #getAllDeclaredNamespaces()
*/
- public OMNamespace findNamespace(String uri, String prefix)
- throws OMException;
+ public OMNamespace findNamespace(String uri, String prefix);
/**
- * @return
- * @throws OMException
+ * Returns an iterator for all of the namespaces declared on this element.
+ *
+ * <p>If you're interested in all namespaces in scope, you need to call this function
+ * for all parent elements as well. Note that the iterator may be invalidated by
+ * any call to either <tt>declareNamespace</tt> function.
+ * </p>
+ *
+ * @return An iterator over the {@link OMNamespace} items declared on the current element.
+ *
+ * @see #findNamespace(String, String)
+ * @see #declareNamespace(String, String)
+ * @see #declareNamespace(OMNamespace)
*/
public Iterator getAllDeclaredNamespaces() throws OMException;
/**
- * This will help to search for an attribute with a given QName within this Element
+ * This will search for an attribute with a given QName within this Element
*
- * @param qname
- * @return
- * @throws OMException
+ * @param qname The attribute name to match.
+ * @return The attribute, if found, or <tt>null</tt> otherwise.
*/
- public OMAttribute getFirstAttribute(QName qname) throws OMException;
+ public OMAttribute getFirstAttribute(QName qname);
/**
- * This will return a List of OMAttributes
+ * This will return a List of OMAttributes.
+ *
+ * <p>Note that the iterator returned by this function will be invalidated by
+ * any <tt>addAttribute</tt> call.
+ * </p>
+ *
+ * @return Returns an {@link Iterator} of {@link OMAttribute} items associated with the element.
*
- * @return
+ * @see #getAttribute
+ * @see #addAttribute(OMAttribute)
+ * @see #addAttribute(String, String, OMNamespace)
*/
public Iterator getAttributes();
/**
- * Return a named attribute if present
+ * Return a named attribute if present.
*
* @param qname the qualified name to search for
* @return an OMAttribute with the given name if found, or null
@@ -131,20 +138,27 @@
public OMAttribute getAttribute(QName qname);
/**
- * This will insert attribute to this element. Implementor can decide as to insert this
- * in the front or at the end of set of attributes
+ * This will add an attribute to this element.
*
- * @param attr
- * @return
+ * <p>There is no order implied by added attributes.</p>
+ *
+ * @param attr The attribute to add.
+ *
+ * @return The passed in attribute.
*/
public OMAttribute addAttribute(OMAttribute attr);
/**
- * @param attributeName
- * @param value
- * @param ns - the namespace has to be one of the in scope namespace. i.e. the passed namespace
- * must be declared in the parent element of this attribute or ancestors of the parent element of the attribute
- * @return
+ * Add an attribute to the current element.
+ *
+ * <p>This function does not check to make sure that the given attribute value can be serialized directly
+ * as an XML value. The caller may, for example, pass a string with the character 0x01.
+ * @param attributeName The "local name" for the attribute.
+ * @param value The string value of the attribute.
+ * @param ns The namespace has to be one of the in scope namespace. i.e. the passed namespace
+ * must be declared in the parent element of this attribute or ancestors of the parent element of the attribute.
+ *
+ * @return The added attribute.
*/
public OMAttribute addAttribute(String attributeName, String value,
OMNamespace ns);
@@ -164,9 +178,9 @@
public void setBuilder(OMXMLParserWrapper wrapper);
/**
- * Method getBuilder
+ * Returns the builder object.
*
- * @return
+ * @return The builder object used to construct the underlying XML infoset on the fly.
*/
public OMXMLParserWrapper getBuilder();
@@ -178,16 +192,9 @@
public void setFirstChild(OMNode node);
/**
- * Get the first child
+ * Returns the first child element of the element.
*
- * @return
- */
- public OMNode getFirstChild();
-
- /**
- * Convenience extension of the getFirstChild
- *
- * @return
+ * @return The first child element of the element, or <tt>null</tt> if none was found.
*/
public OMElement getFirstElement();
@@ -195,17 +202,21 @@
/**
* Returns the pull parser that will generate the pull
- * events relevant to THIS element. Caching is on
+ * events relevant to THIS element.
*
- * @return
+ * <p>Caching is on.</p>
+ *
+ * @return Return an XMLStreamReader relative to this element.
*/
public XMLStreamReader getXMLStreamReader();
/**
* Returns the pull parser that will generate the pull
- * events relevant to THIS element.caching is off
+ * events relevant to THIS element.
+ *
+ * <p>Caching is off.</p>
*
- * @return
+ * @return Return an XMLStreamReader relative to this element, with no caching.
*/
public XMLStreamReader getXMLStreamReaderWithoutCaching();
@@ -217,14 +228,14 @@
/**
* This will return the non-empty text children as a String
*
- * @return
+ * @return A String representing the concatenation of the child text nodes.
*/
public String getText();
/**
- * Method getLocalName
+ * Returns the local name of the element.
*
- * @return
+ * @return The local name of the element.
*/
public String getLocalName();
@@ -249,9 +260,9 @@
public void setNamespace(OMNamespace namespace);
/**
- * Get the Qname of this node
+ * Get the QName of this node
*
- * @return
+ * @return The {@link QName} for the element.
*/
public QName getQName();
Modified: webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/OMNode.java
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/OMNode.java?rev=292040&r1=292039&r2=292040&view=diff
==============================================================================
--- webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/OMNode.java (original)
+++ webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/OMNode.java Tue Sep 27 13:51:38 2005
@@ -23,63 +23,88 @@
import javax.xml.stream.XMLStreamWriter;
/**
- * Interface OMNode
+ * Defines the the base interface used by most of the XML object model within Axis.
+ *
+ * <p>This tree model for XML captures the idea of deferring the construction of child nodes
+ * until they are needed. The <code>isComplete</code> function identifies whether or not
+ * a particular node has been fully parsed. A node may not be fully parsed, for example, if
+ * all of the children of an element have not yet been parsed.</p>
+ *
+ * <p>In comparison to DOM, in this model, you will not find document fragments, or entities.
+ * In addition, while {@link OMDocument} and {@link OMAttribute} exist, neither is an extension
+ * of <code>OMNode</code>.
+ * </p>
*/
public interface OMNode {
/**
* The node is an <code>Element</code>.
+ *
+ * @see #getType()
*/
public static final short ELEMENT_NODE = 1;
/**
* The node is a <code>Text</code> node.
+ *
+ * @see #getType()
*/
public static final short TEXT_NODE = XMLStreamConstants.CHARACTERS;
/**
* The node is a <code>CDATASection</code>.
+ *
+ * @see #getType()
*/
public static final short CDATA_SECTION_NODE = XMLStreamConstants.CDATA;
/**
* The node is a <code>Comment</code>.
+ *
+ * @see #getType()
*/
public static final short COMMENT_NODE = XMLStreamConstants.COMMENT;
/**
* This node is a <code>DTD</code>.
+ *
+ * @see #getType()
*/
public static final short DTD_NODE = XMLStreamConstants.DTD;
/**
* This node is a <code>ProcessingInstruction</code>.
+ *
+ * @see #getType()
*/
public static final short PI_NODE = XMLStreamConstants.PROCESSING_INSTRUCTION;
/**
* This node is a <code>Entity Reference</code>.
+ *
+ * @see #getType()
*/
public static final short ENTITY_REFERENCE_NODE = XMLStreamConstants.ENTITY_REFERENCE;
/**
* This node is a <code>Entity Reference</code>.
+ *
+ * @see #getType()
*/
public static final short SPACE_NODE = XMLStreamConstants.SPACE;
/**
- * This method should return the immediate parent of the node.
- * Parent is always an Element
+ * Returns the parent containing node.
*
- * @return
- * @throws OMException
+ * <p>Returns the parent container, which may be either an {@link OMDocument} or {@link OMElement}.
+ *
+ * @return The {@link OMContainer} of the node.
*/
- public OMContainer getParent() throws OMException;
+ public OMContainer getParent();
/**
- * This will give the next sibling. This can be an OMAttribute for OMAttribute or OMText or OMELement for others.
+ * Returns the next sibling in document order.
*
- * @return
- * @throws OMException
+ * @return The next sibling in document order.
*/
public OMNode getNextSibling() throws OMException;
@@ -93,45 +118,53 @@
public boolean isComplete();
/**
- * This will remove this information item and its children, from the model completely.
- * Important to note that this method will detach the OMNode once it is fully built.
- * Half built nodes are not to be detached!
+ * Removes a node (and all of its children) from its containing parent.
*
- * @throws OMException
+ * <p>Removes a node from its parent. Partially complete nodes will be completed before
+ * they are detached from the model. A node cannot be detached until its next sibling
+ * has been identified, so that the next sibling and parent can be updated appropriately.
+ * </p>
+ *
+ * @throws OMException If a node is not complete, the detach can trigger further
+ * parsing, which may cause an exception.
*/
public OMNode detach() throws OMException;
/**
- * Discards a Node. Discrad goes to the parser level and if the element is not
- * completely built, then it will be completely skipped at the parser level
+ * Discards a node.
+ *
+ * <p>Discard goes to the parser level and if the element is not completely built, then it will be
+ * completely skipped at the parser level.</p>
*
* @throws OMException
*/
public void discard() throws OMException;
/**
- * This will insert a sibling just after the current information item.
+ * Inserts a new sibling after the current node.
+ *
+ * @param sibling The node that will be added after the current node.
*
- * @param sibling
* @throws OMException
*/
public void insertSiblingAfter(OMNode sibling) throws OMException;
/**
- * This will insert a sibling just before the current information item
+ * This will insert a sibling just before the current node.
*
- * @param sibling
+ * @param sibling The node that will be added before the current node.
* @throws OMException
*/
public void insertSiblingBefore(OMNode sibling) throws OMException;
/**
- * This is to get the type of node, as this is the super class of all the nodes
+ * Returns the type of node.
*
- * @return
- * @throws OMException
+ * @return One of {@link #ELEMENT_NODE}, {@link #TEXT_NODE}, {@link #CDATA_SECTION_NODE}, {@link #COMMENT_NODE},
+ * {@link #DTD_NODE}, {@link #PI_NODE}, {@link #ENTITY_REFERENCE_NODE}, {@link #SPACE_NODE},
+ * or {@link #TEXT_NODE}.
*/
- public int getType() throws OMException;
+ public int getType();
/**
* get the previous sibling
Modified: webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/impl/llom/OMDocumentImpl.java
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/impl/llom/OMDocumentImpl.java?rev=292040&r1=292039&r2=292040&view=diff
==============================================================================
--- webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/impl/llom/OMDocumentImpl.java (original)
+++ webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/impl/llom/OMDocumentImpl.java Tue Sep 27 13:51:38 2005
@@ -193,10 +193,8 @@
* @param elementQName
* @return
* @throws org.apache.axis2.om.OMException
- *
- * @throws OMException
*/
- public Iterator getChildrenWithName(QName elementQName) throws OMException {
+ public Iterator getChildrenWithName(QName elementQName) {
return new OMChildrenQNameIterator(getFirstChild(),
elementQName);
}
Modified: webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/impl/llom/OMElementImpl.java
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/impl/llom/OMElementImpl.java?rev=292040&r1=292039&r2=292040&view=diff
==============================================================================
--- webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/impl/llom/OMElementImpl.java (original)
+++ webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/impl/llom/OMElementImpl.java Tue Sep 27 13:51:38 2005
@@ -188,7 +188,7 @@
*
* @throws OMException
*/
- public Iterator getChildrenWithName(QName elementQName) throws OMException {
+ public Iterator getChildrenWithName(QName elementQName) {
return new OMChildrenQNameIterator(getFirstChild(),
elementQName);
}
@@ -292,13 +292,8 @@
* This will find a namespace with the given uri and prefix, in the scope of the docuemnt.
* This will start to find from the current element and goes up in the hiararchy until this finds one.
* If none is found, return null
- *
- * @throws org.apache.axis2.om.OMException
- *
- * @throws OMException
*/
- public OMNamespace findNamespace(String uri, String prefix)
- throws OMException {
+ public OMNamespace findNamespace(String uri, String prefix) {
// check in the current element
OMNamespace namespace = findDeclaredNamespace(uri, prefix);
@@ -326,13 +321,11 @@
}
/**
- * This will ckeck for the namespace <B>only</B> in the current Element
- * This can also be used to retrieve the prefix of a known namespace URI
+ * This will ckeck for the namespace <B>only</B> in the current Element.
*
- * @throws OMException
+ * This can also be used to retrieve the prefix of a known namespace URI
*/
- private OMNamespace findDeclaredNamespace(String uri, String prefix)
- throws OMException {
+ private OMNamespace findDeclaredNamespace(String uri, String prefix) {
if (namespaces == null) {
return null;
}
@@ -366,12 +359,8 @@
/**
* This will help to search for an attribute with a given QName within this Element
- *
- * @throws org.apache.axis2.om.OMException
- *
- * @throws OMException
*/
- public OMAttribute getFirstAttribute(QName qname) throws OMException {
+ public OMAttribute getFirstAttribute(QName qname) {
if (attributes == null) {
return null;
}
@@ -517,12 +506,8 @@
/**
* This is to get the type of node, as this is the super class of all the nodes
- *
- * @throws org.apache.axis2.om.OMException
- *
- * @throws OMException
*/
- public int getType() throws OMException {
+ public int getType() {
return OMNode.ELEMENT_NODE;
}
Modified: webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/impl/llom/OMNodeImpl.java
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/impl/llom/OMNodeImpl.java?rev=292040&r1=292039&r2=292040&view=diff
==============================================================================
--- webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/impl/llom/OMNodeImpl.java (original)
+++ webservices/axis2/trunk/java/modules/xml/src/org/apache/axis2/om/impl/llom/OMNodeImpl.java Tue Sep 27 13:51:38 2005
@@ -83,11 +83,10 @@
* Parent is always an Element
*
* @return
- * @throws org.apache.axis2.om.OMException
*
* @throws OMException
*/
- public OMContainer getParent() throws OMException {
+ public OMContainer getParent() {
return parent;
}
@@ -237,12 +236,11 @@
/**
* This is to get the type of node, as this is the super class of all the nodes
*
- * @return
- * @throws org.apache.axis2.om.OMException
+ * @return Returns the type of node as indicated by {@link #setType}
*
- * @throws OMException
+ * @see #setType
*/
- public int getType() throws OMException {
+ public int getType() {
return nodeType;
}