public class XMLStreamReaderUtils extends Object
XMLStreamReader
objects, including the extension
defined by DataHandlerReader
. In addition to DataHandlerReader
support, this
class also provides support for the legacy extension mechanism described below.
XMLStreamReader
instances supporting the legacy extension must conform to the following
requirements:
XMLStreamReader.getProperty(String)
must return Boolean.TRUE
for the
property identified by 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 XMLStreamReader
implementation.
If the XMLStreamReader
wishes to expose base64 encoded content using a
DataHandler
object, it must do so using a single
XMLStreamConstants.CHARACTERS
event.
To maintain compatibility with consumers that are unaware of the extensions described here, the
implementation should make sure that XMLStreamReader.getText()
,
XMLStreamReader.getTextStart()
, XMLStreamReader.getTextLength()
,
XMLStreamReader.getTextCharacters()
,
XMLStreamReader.getTextCharacters(int, char[], int, int)
and
XMLStreamReader.getElementText()
behave as expected for this type of event, i.e. return
the base64 representation of the binary content.
XMLStreamReader.getProperty(String)
must return Boolean.TRUE
for the
property identified by OMConstants.IS_BINARY
if the current event is
a XMLStreamConstants.CHARACTERS
event representing base64 encoded binary content and for
which a DataHandler
is available. For all other events, the returned
value must be Boolean.FALSE
.
If for a given event, the implementation returned Boolean.TRUE
for the
OMConstants.IS_BINARY
property, then a call to
XMLStreamReader.getProperty(String)
with argument
OMConstants.DATA_HANDLER
must return the corresponding
DataHandler
object.
The OMConstants.DATA_HANDLER
property is undefined for any other type
of event. This implies that the consumer of the XMLStreamReader
must check the
OMConstants.IS_BINARY
property before retrieving the
OMConstants.DATA_HANDLER
property.
Modifier and Type | Method and Description |
---|---|
static javax.activation.DataHandler |
getDataHandlerFromElement(javax.xml.stream.XMLStreamReader reader)
Get a
DataHandler for the binary data encoded in an element. |
static DataHandlerReader |
getDataHandlerReader(javax.xml.stream.XMLStreamReader reader)
Get the
DataHandlerReader extension for a given XMLStreamReader , if
available. |
static Reader |
getElementTextAsStream(javax.xml.stream.XMLStreamReader reader,
boolean allowNonTextChildren)
Get the text content of the current element as a
Reader object. |
static javax.xml.stream.XMLStreamReader |
getOriginalXMLStreamReader(javax.xml.stream.XMLStreamReader parser)
Searches the wrapper and delegate classes to find the original
XMLStreamReader . |
static Object |
processGetProperty(DataHandlerReader extension,
String propertyName)
Helper method to implement
XMLStreamReader.getProperty(String) . |
static void |
writeTextTo(javax.xml.stream.XMLStreamReader reader,
Writer writer)
Get the character data for the current event from the given reader and
write it to the given writer.
|
public static DataHandlerReader getDataHandlerReader(javax.xml.stream.XMLStreamReader reader)
DataHandlerReader
extension for a given XMLStreamReader
, if
available. If the XMLStreamReader
only supports the legacy extension (as described
above), then this method will return a compatibility wrapper. Note that this wrapper doesn't
support deferred loading of the binary content.reader
- the stream reader to get the DataHandlerReader
extension fromnull
if the
XMLStreamReader
doesn't expose base64 encoded binary content as
DataHandler
objects.public static Object processGetProperty(DataHandlerReader extension, String propertyName)
XMLStreamReader.getProperty(String)
. This method
processed the properties defined by DataHandlerReader.PROPERTY
and the legacy
extension mechanism (as described above). It can therefore be used to make a
XMLStreamReader
implementation compatible with code that expects it to implement this
legacy extension.extension
- the reference to the DataHandlerReader
extension for the
XMLStreamReader
implementationpropertyName
- the name of the property, as passed to the
XMLStreamReader.getProperty(String)
methodDataHandlerReader
or legacy extension;
null
if the property is not specified by any of these two extensionspublic static javax.activation.DataHandler getDataHandlerFromElement(javax.xml.stream.XMLStreamReader reader) throws javax.xml.stream.XMLStreamException
DataHandler
for the binary data encoded in an element. The method supports
base64 encoded character data as well as optimized binary data through the
DataHandlerReader
extension.
Precondition: the reader is on a XMLStreamConstants.START_ELEMENT
Postcondition: the reader is on the corresponding
XMLStreamConstants.END_ELEMENT
reader
- the stream to read the data fromjavax.xml.stream.XMLStreamException
public static void writeTextTo(javax.xml.stream.XMLStreamReader reader, Writer writer) throws javax.xml.stream.XMLStreamException, IOException
reader
- the reader to get the character data fromwriter
- the writer to write the character data tojavax.xml.stream.XMLStreamException
- if the underlying XML source is not well-formedIOException
- if an I/O error occurs when writing the character dataIllegalStateException
- if this state is not a valid text state.CharacterDataReader
public static Reader getElementTextAsStream(javax.xml.stream.XMLStreamReader reader, boolean allowNonTextChildren)
Reader
object.reader
- The XML stream reader to read the element text from. The reader must be positioned
on a XMLStreamConstants.START_ELEMENT
event.allowNonTextChildren
- If set to true
, non text child nodes are allowed and skipped. If set
to false
only text nodes are allowed and the presence of any other
type of child node will trigger an exception.XMLStreamConstants.END_ELEMENT
event corresponding to the initial
XMLStreamConstants.START_ELEMENT
event. Calling Reader.close()
on the
returned reader has no effect. Any parser exception will be reported by the reader
using XMLStreamIOException
.IllegalStateException
- if the XML stream reader is not positioned on a
XMLStreamConstants.START_ELEMENT
eventpublic static javax.xml.stream.XMLStreamReader getOriginalXMLStreamReader(javax.xml.stream.XMLStreamReader parser)
XMLStreamReader
.
This method should only be used when a consumer of Axiom really needs to
access the original stream reader.parser
- XMLStreamReader used by AxiomCopyright © 2004-2013 The Apache Software Foundation. All Rights Reserved.