Author: veithen
Date: Sun May 23 14:42:54 2010
New Revision: 947419
URL: http://svn.apache.org/viewvc?rev=947419&view=rev
Log:
WSCOMMONS-540: Also completed the Javadoc of StAXBuilder#getParser(), which had
the same issue as CustomBuilder.
Modified:
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/StAXBuilder.java
Modified:
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/StAXBuilder.java
URL:
http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/StAXBuilder.java?rev=947419&r1=947418&r2=947419&view=diff
==============================================================================
---
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/StAXBuilder.java
(original)
+++
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/StAXBuilder.java
Sun May 23 14:42:54 2010
@@ -518,9 +518,23 @@ public abstract class StAXBuilder implem
}
/**
- * Method getParser.
- *
- * @return Returns Object.
+ * Get the underlying {...@link XMLStreamReader} used by this builder.
Note that for this type of
+ * builder, accessing the underlying parser implies that can no longer be
used, and any attempt
+ * to call {...@link #next()} will result in an exception.
+ *
+ * @return The {...@link XMLStreamReader} object used by this builder.
Note that the constraints
+ * described in the Javadoc of the <code>reader</code> parameter
of the
+ * {...@link CustomBuilder#create(String, String, OMContainer,
XMLStreamReader, OMFactory)}
+ * method also apply to the stream reader returned by this method,
i.e.:
+ * <ul>
+ * <li>The caller should use
+ * {...@link
org.apache.axiom.util.stax.xop.XOPUtils#getXOPEncodedStream(XMLStreamReader)}
+ * to get an XOP encoded stream from the return value.
+ * <li>To get access to the bare StAX parser implementation, the
caller should use
+ * {...@link
org.apache.axiom.util.stax.XMLStreamReaderUtils#getOriginalXMLStreamReader(XMLStreamReader)}.
+ * </ul>
+ * @throws IllegalStateException
+ * if the parser has already been accessed
*/
public Object getParser() {
if (parserAccessed) {
