Author: veithen
Date: Thu Jul 21 16:08:00 2011
New Revision: 1149245
URL: http://svn.apache.org/viewvc?rev=1149245&view=rev
Log:
Improved the Javadoc of OMElement#getAllDeclaredNamespaces().
Modified:
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMElement.java
Modified:
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMElement.java
URL:
http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMElement.java?rev=1149245&r1=1149244&r2=1149245&view=diff
==============================================================================
---
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMElement.java
(original)
+++
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMElement.java
Thu Jul 21 16:08:00 2011
@@ -22,6 +22,8 @@ package org.apache.axiom.om;
import javax.xml.namespace.QName;
import javax.xml.stream.XMLStreamException;
+import org.apache.axiom.om.xpath.AXIOMXPath;
+
import java.io.OutputStream;
import java.io.Writer;
import java.util.Iterator;
@@ -164,17 +166,27 @@ public interface OMElement extends OMNod
OMNamespace findNamespaceURI(String prefix);
/**
- * Returns an iterator for all of the namespaces declared on this element.
- * <p/>
- * <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 Returns an iterator over the {@link OMNamespace} items declared
on the current
- * element.
- * @see #findNamespace(String, String)
- * @see #declareNamespace(String, String)
- * @see #declareNamespace(OMNamespace)
+ * Returns an iterator for all of the namespaces declared on this element.
Note that this is not
+ * the same as the set of namespace declarations in scope. Since building
a namespace context
+ * and resolving namespace prefixes has some subtleties associated with it
(such as masked
+ * namespace declarations and prefix undeclaring), it is generally
recommended to use one of the
+ * following specialized methods for this purpose:
+ * <ul>
+ * <li>{@link #findNamespace(String, String)} and {@link
#findNamespaceURI(String)} to resolve a
+ * namespace prefix or to find a namespace prefix for a given URI.
+ * <li>{@link #resolveQName(String)} to resolve a QName literal.
+ * <li>{@link AXIOMXPath#AXIOMXPath(OMElement, String)} or
+ * {@link AXIOMXPath#AXIOMXPath(OMAttribute)} to create an XPath
expression using the namespace
+ * context of a given element.
+ * </ul>
+ * <p>
+ * It is expected that applications only rarely use {@link
#getAllDeclaredNamespaces()}
+ * directly.
+ *
+ * @return An iterator over the {@link OMNamespace} items declared on this
element. Note that
+ * the iterator may be invalidated by a call to {@link
#declareNamespace(OMNamespace)},
+ * {@link #declareNamespace(String, String)}, {@link
#declareDefaultNamespace(String)}
+ * or any other method that modifies the namespace declarations of
this element.
*/
Iterator getAllDeclaredNamespaces() throws OMException;
