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

[ve...@apache.org]

Author: veithen
Date: Tue May 18 21:18:31 2010
New Revision: 945893

URL: http://svn.apache.org/viewvc?rev=945893&view=rev
Log:
Added some Javadoc related to WSCOMMONS-518.

Modified:
    webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/CustomBuilder.java

Modified: webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/CustomBuilder.java
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/CustomBuilder.java?rev=945893&r1=945892&r2=945893&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/CustomBuilder.java (original)
+++ webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/CustomBuilder.java Tue May 18 21:18:31 2010
@@ -43,6 +43,20 @@ public interface CustomBuilder {
      * @param namespace
      * @param localPart
      * @param parent
+     *            The stream reader to read the StAX events from. The
+     *            implementation MUST NOT assume that this is the original
+     *            reader returned by the StAX implementation. In general, it
+     *            will be a wrapper around the original reader, e.g. one added
+     *            by the {@link org.apache.axiom.util.stax.dialect.StAXDialect}
+     *            implementation. If the method requires access to the original
+     *            parser (e.g. to pass the {@link XMLStreamReader} object to
+     *            another library that uses some special optimizations for
+     *            particular parser implementations), it SHOULD use
+     *            {@link org.apache.axiom.util.stax.XMLStreamReaderUtils#getOriginalXMLStreamReader(XMLStreamReader)}
+     *            to unwrap the reader. If the method solely relies on the
+     *            conformance of the reader to the StAX specification, it SHOULD
+     *            NOT attempt to unwrap it.
+     * 
      * @param reader
      * @return null or OMElement
      */