svn commit: r947419 - /webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/StAXBuilder.java

[ve...@apache.org]

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) {