You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commons-dev@ws.apache.org by ve...@apache.org on 2009/05/21 21:33:57 UTC
svn commit: r777229 - in
/webservices/commons/trunk/modules/axiom/modules/axiom-api/src/main/java/org/apache/axiom/om:
OMConstants.java impl/builder/StAXOMBuilder.java
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 */