Author: veithen
Date: Sat Aug 15 20:27:00 2009
New Revision: 804525
URL: http://svn.apache.org/viewvc?rev=804525&view=rev
Log:
As suggested by Senaka Fernando, added some more documentation to the
getXMLStreamReader method explaining the assumptions that the caller can make
about the returned reader.
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=804525&r1=804524&r2=804525&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
Sat Aug 15 20:27:00 2009
@@ -264,9 +264,99 @@
XMLStreamReader getXMLStreamReaderWithoutCaching();
/**
- * Get a pull parser representation of this element.
- *
- * @param cache indicates if caching should be enabled
+ * Get a pull parser representation of this element. This methods creates
an
+ * {...@link XMLStreamReader} instance that produces a sequence of StAX
events for this element and
+ * its content. The sequence of events is independent of the state of this
element and the value
+ * of the <code>cache</code> parameter, but the side effects of calling
this method and
+ * consuming the reader are different:
+ * <p>
+ * <table border="2" rules="all" cellpadding="4" cellspacing="0">
+ * <tr>
+ * <th>State</th>
+ * <th><code>cache</code></th>
+ * <th>Side effects</th>
+ * </tr>
+ * <tr>
+ * <td rowspan="2">The element is fully built (or was created
programmatically).</td>
+ * <td><code>true</code></td>
+ * <td rowspan="2">No side effects. The reader will synthesize StAX events
from the object
+ * model.</td>
+ * </tr>
+ * <tr>
+ * <td><code>false</code></td>
+ * </tr>
+ * <tr>
+ * <td rowspan="2">The element is partially built, i.e. deferred parsing
is taking place.</td>
+ * <td><code>true</code></td>
+ * <td>When a StAX event is requested from the reader, it will built the
information item (if
+ * necessary) and synthesize the StAX event. If the caller completely
consumes the reader, the
+ * element will be completely built. Otherwise it will be partially
built.</td>
+ * </tr>
+ * <tr>
+ * <td><code>false</code></td>
+ * <td>The reader will delegate to the underlying parser starting from the
event corresponding
+ * to the last information item that has been built. In other words, after
synthesizing a number
+ * of events, the reader will switch to delegation mode. An attempt to
access the object model
+ * afterwards will result in an error.</td>
+ * </tr>
+ * </table>
+ * <p>
+ * To free any resources associated with the returned reader, the caller
MUST invoke the
+ * {...@link XMLStreamReader#close()} method.
+ * <p>
+ * The returned reader MAY implement the extension defined by
+ * {...@link org.apache.axiom.ext.stax.datahandler.DataHandlerReader} and
any binary content will
+ * be reported using this extension. More precisely, if the object model
contains an
+ * {...@link OMText} instance with {...@link OMText#isBinary()} returning
<code>true</code> (or
+ * would contain such an instance after it has been fully built), then its
data will always be
+ * exposed through this extension.
+ * <p>
+ * The caller MUST NOT make any other assumption about the returned
reader, in particular about
+ * its runtime type.
+ * <p>
+ * <b>Note</b> (non normative): For various reasons, existing code based
on Axiom versions
+ * prior to 1.2.9 makes assumptions on the returned reader that should no
longer be considered
+ * valid:
+ * <ul>
+ * <li>Some code assumes that the returned reader is an instance of
+ * {...@link org.apache.axiom.om.impl.OMStAXWrapper}. While it is true
that Axiom internally uses
+ * this class to synthesize StAX events, it may wrap this instance in
another reader
+ * implementation. E.g. depending on the log level, the reader will be
wrapped using
+ * {...@link org.apache.axiom.om.util.OMXMLStreamReaderValidator}. This
was already the case in
+ * Axiom versions prior to 1.2.9. It should also be noted that instances of
+ * {...@link OMSourcedElement} (which extends the present interface) may
return a reader that is
+ * not implemented using {...@link
org.apache.axiom.om.impl.OMStAXWrapper}.</li>
+ * <li>Some code uses the {...@link OMXMLStreamReader} interface of the
returned reader to switch
+ * off MTOM inlining using {...@link
OMXMLStreamReader#setInlineMTOM(boolean)}. This has now been
+ * deprecated and it is recommended to use
+ * {...@link org.apache.axiom.util.stax.xop.XOPEncodingStreamReader}
instead.</li>
+ * <li>Some existing code uses the {...@link OMAttachmentAccessor}
interface of the returned
+ * reader to fetch attachments using {...@link
OMAttachmentAccessor#getDataHandler(String)}. There
+ * is no reason anymore to do so:</li>
+ * <ul>
+ * <li>When {...@link OMXMLStreamReader#setInlineMTOM(boolean)} is used to
disable MTOM inlining,
+ * {...@link OMAttachmentAccessor#getDataHandler(String)} must be used to
retrieve the binary
+ * content. The fact that this method is deprecated removes the need for
this.</li>
+ * <li>In Axiom versions prior to 1.2.9, the sequence of events was
inconsistent if the
+ * underlying stream is XOP encoded and caching is disabled (see
WSCOMMONS-485). This made it
+ * necessary for the caller to (partially) handle the XOP processing and
to use
+ * {...@link OMAttachmentAccessor#getDataHandler(String)} to retrieve the
binary content. Starting
+ * with 1.2.9 this is no longer be the case: as specified above, the
sequence of events is
+ * independent of the state of the object model and the value of the
<code>cache</code>
+ * parameter, and all binary content is reported through the
+ * {...@link org.apache.axiom.ext.stax.datahandler.DataHandlerReader}
extension.</li>
+ * <li>Finally, it should be noted that {...@link
OMAttachmentAccessor#getDataHandler(String)}
+ * doesn't give access to the attachments in the SwA case (neither in
1.2.9 nor in previous
+ * versions).</li>
+ * </ul>
+ * </ul>
+ * <p>
+ * Code making any of these assumptions should be fixed, so that only
{...@link XMLStreamReader}
+ * and {...@link org.apache.axiom.ext.stax.datahandler.DataHandlerReader}
are used (and if
+ * necessary, {...@link
org.apache.axiom.util.stax.xop.XOPEncodingStreamReader}).
+ *
+ * @param cache
+ * indicates if caching should be enabled
* @return an {...@link XMLStreamReader} representation of this element
*/
XMLStreamReader getXMLStreamReader(boolean cache);
