Author: veithen
Date: Thu May 21 19:33:56 2009
New Revision: 777229
URL: http://svn.apache.org/viewvc?rev=777229&view=rev
Log:
Added proper documentation for the IS_DATA_HANDLERS_AWARE extension.
Modified:
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMConstants.java
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/StAXOMBuilder.java
Modified:
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMConstants.java
URL:
http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMConstants.java?rev=777229&r1=777228&r2=777229&view=diff
==============================================================================
---
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMConstants.java
(original)
+++
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/OMConstants.java
Thu May 21 19:33:56 2009
@@ -57,12 +57,33 @@
static final String XMLNS_PREFIX =
"xml";
+
+ /**
+ * {...@link javax.xml.stream.XMLStreamReader} property used to check if a
given
+ * {...@link javax.xml.stream.XMLStreamConstants#CHARACTERS} event
represents
+ * base64 encoded binary data exposed as a {...@link
javax.activation.DataHandler}.
+ *
+ * @see org.apache.axiom.om.impl.builder.StAXOMBuilder
+ */
String IS_BINARY = "Axiom.IsBinary";
+
+ /**
+ * {...@link javax.xml.stream.XMLStreamReader} property used to retrieve
the
+ * {...@link javax.activation.DataHandler} for a
+ * {...@link javax.xml.stream.XMLStreamConstants#CHARACTERS} event
representing
+ * base64 encoded binary data.
+ *
+ * @see org.apache.axiom.om.impl.builder.StAXOMBuilder
+ */
String DATA_HANDLER = "Axiom.DataHandler";
- // Indicates if the xmlstream reader is capable of handling data handlers.
- // Thus it is an immutable property and will either be true of false for
the
- // lifetime of that parser. @see OMStaxWrapper for an example
+ /**
+ * {...@link javax.xml.stream.XMLStreamReader} property indicating that the
+ * reader is capable of exposing base64 encoded binary content as
+ * {...@link javax.activation.DataHandler} objects.
+ *
+ * @see org.apache.axiom.om.impl.builder.StAXOMBuilder
+ */
String IS_DATA_HANDLERS_AWARE = "IsDatahandlersAwareParsing";
/** No its not a mistake. This is the default nsURI of the default
namespace of a node */
Modified:
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/StAXOMBuilder.java
URL:
http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/StAXOMBuilder.java?rev=777229&r1=777228&r2=777229&view=diff
==============================================================================
---
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/StAXOMBuilder.java
(original)
+++
webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om/impl/builder/StAXOMBuilder.java
Thu May 21 19:33:56 2009
@@ -46,6 +46,55 @@
/**
* StAX based builder that produces a pure XML infoset compliant object model.
+ *
+ * <h3>XMLStreamReader extensions for optimized base64 handling</h3>
+ *
+ * <p>This class supports {...@link XMLStreamReader} instances that expose
base64 encoded binary
+ * content as {...@link javax.activation.DataHandler} objects. For this to
work, the
+ * {...@link XMLStreamReader} must conform to the following requirements:</p>
+ * <ol>
+ * <li>{...@link XMLStreamReader#getProperty(String)} must return {...@link
Boolean#TRUE}
+ * for the property identified by
+ * {...@link org.apache.axiom.om.OMConstants#IS_DATA_HANDLERS_AWARE},
regardless of
+ * the current event. The property is assumed to be immutable and its
value must
+ * not change during the lifetime of the {...@link XMLStreamReader}
implementation.</li>
+ * <li><p>If the {...@link XMLStreamReader} wishes to expose base64 encoded
content using
+ * a {...@link javax.activation.DataHandler} object, it must do so using
a single
+ * {...@link XMLStreamConstants#CHARACTERS} event.</p>
+ * <p>To maintain compatibility with consumers that are unaware of the
extensions
+ * described here, the implementation should make sure that
+ * {...@link XMLStreamReader#getText()}, {...@link
XMLStreamReader#getTextStart()},
+ * {...@link XMLStreamReader#getTextLength()}, {...@link
XMLStreamReader#getTextCharacters()},
+ * {...@link XMLStreamReader#getTextCharacters(int, char[], int, int)}
and
+ * {...@link XMLStreamReader#getElementText()} behave as expected for
this type of event,
+ * i.e. return the base64 representation of the binary content.</p></li>
+ * <li>{...@link XMLStreamReader#getProperty(String)} must return {...@link
Boolean#TRUE}
+ * for the property identified by
+ * {...@link org.apache.axiom.om.OMConstants#IS_BINARY} if the current
event is a
+ * {...@link XMLStreamConstants#CHARACTERS} event representing base64
encoded binary
+ * content and for which a {...@link javax.activation.DataHandler} is
available.
+ * For all other events, the returned value must be {...@link
Boolean#FALSE}.</li>
+ * <li><p>If for a given event, the implementation returned {...@link
Boolean#TRUE} for the
+ * {...@link org.apache.axiom.om.OMConstants#IS_BINARY} property, then a
call to
+ * {...@link XMLStreamReader#getProperty(String)} with argument
+ * {...@link org.apache.axiom.om.OMConstants#DATA_HANDLER} must return
the
+ * corresponding {...@link javax.activation.DataHandler} object.</p>
+ * <p>The {...@link org.apache.axiom.om.OMConstants#DATA_HANDLER}
property is undefined
+ * for any other type of event. This implies that the consumer of the
+ * {...@link XMLStreamReader} must check the {...@link
org.apache.axiom.om.OMConstants#IS_BINARY}
+ * property before retrieving the {...@link
org.apache.axiom.om.OMConstants#DATA_HANDLER}
+ * property.</p></li>
+ * </ol>
+ * <p>The extension described will typically be implemented by {...@link
XMLStreamReader} instances
+ * provided by databinding frameworks or {...@link XMLStreamReader} proxies
that enrich a stream of
+ * StAX events with binary data existing outside of the XML document. Another
example is
+ * {...@link org.apache.axiom.om.impl.OMStAXWrapper}.</p>
+ * <p>One may ask why this extension is defined using {...@link
XMLStreamReader} properties and not
+ * simply as an extension interface that the reader may implement. The reason
is that the property
+ * based approach continues to work if the {...@link XMLStreamReader}
implementing the extension
+ * is accessed through a proxy implementing the {...@link XMLStreamReader}
interface but unaware
+ * of the extension, at least if the proxy correctly delegates calls to the
+ * {...@link XMLStreamReader#getProperty(String)} method.</p>
*/
public class StAXOMBuilder extends StAXBuilder {
/** Field document */
