public interface OMContainer extends OMSerializable
Exposes the ability to add, find, and iterate over the children of a document or element.
Modifier and Type | Method and Description |
---|---|
void |
addChild(OMNode omNode)
Adds the given node as the last child of this container.
|
OMXMLParserWrapper |
getBuilder()
Returns the builder object.
|
Iterator |
getChildren()
Returns an iterator for the children of the container.
|
Iterator |
getChildrenWithLocalName(String localName)
Returns an iterator for child nodes matching the local name.
|
Iterator |
getChildrenWithName(QName elementQName)
Returns an iterator for child nodes matching the given QName.
|
Iterator |
getChildrenWithNamespaceURI(String uri)
Returns an iterator for child nodes matching the namespace uri.
|
Iterator |
getDescendants(boolean includeSelf)
Get an iterator over all descendants of the container.
|
OMElement |
getFirstChildWithName(QName qname)
Returns the first child in document order that matches the given QName.
|
OMNode |
getFirstOMChild()
Gets the first child.
|
SAXResult |
getSAXResult()
Get a
SAXResult object that can be used to append child nodes to this container. |
SAXSource |
getSAXSource(boolean cache)
Get a
SAXSource representation for this node. |
javax.xml.stream.XMLStreamReader |
getXMLStreamReader()
Get a pull parser representation of this element with caching enabled.
|
javax.xml.stream.XMLStreamReader |
getXMLStreamReader(boolean cache)
Get a pull parser representation of this information item.
|
javax.xml.stream.XMLStreamReader |
getXMLStreamReader(boolean cache,
OMXMLStreamReaderConfiguration configuration)
Get a pull parser representation of this information item.
|
javax.xml.stream.XMLStreamReader |
getXMLStreamReaderWithoutCaching()
Get a pull parser representation of this element with caching disabled.
|
void |
removeChildren()
Remove all children from this container.
|
void |
serialize(OutputStream output)
Serialize the node with caching enabled.
|
void |
serialize(OutputStream output,
OMOutputFormat format)
Serialize the node with caching enabled.
|
void |
serialize(Writer writer)
Serialize the node with caching enabled.
|
void |
serialize(Writer writer,
OMOutputFormat format)
Serialize the node with caching enabled.
|
void |
serializeAndConsume(OutputStream output)
Serialize the node without caching.
|
void |
serializeAndConsume(OutputStream output,
OMOutputFormat format)
Serialize the node without caching.
|
void |
serializeAndConsume(Writer writer)
Serialize the node without caching.
|
void |
serializeAndConsume(Writer writer,
OMOutputFormat format)
Serialize the node without caching.
|
build, close, isComplete, serialize, serialize, serializeAndConsume
clone, getOMFactory
OMXMLParserWrapper getBuilder()
void addChild(OMNode omNode)
The method may throw an OMException
if the node is not allowed at this position of
the document.
omNode
- the node to be added to this containerIterator getChildrenWithName(QName elementQName)
elementQName
- The QName specifying namespace and local name to match.OMElement
items that match the given QNameIterator getChildrenWithLocalName(String localName)
localName
- OMElement
items that match the given localNameIterator getChildrenWithNamespaceURI(String uri)
uri
- OMElement
items that match the given uriOMElement getFirstChildWithName(QName qname) throws OMException
getChildrenWithName(QName)
method.qname
- The QName to use for matching.qname
criteria, or null
if none is found.OMException
- If an error occurs during deferred parsing.getChildrenWithName(QName)
Iterator getChildren()
Iterator
of children, all of which implement OMNode
.getFirstChildWithName(javax.xml.namespace.QName)
,
getChildrenWithName(javax.xml.namespace.QName)
Iterator getDescendants(boolean includeSelf)
includeSelf
- true
if the iterator should also return the container itself;
false
if the first item returned by the iterator should be the first
child of the containerOMNode getFirstOMChild()
void removeChildren()
for (Iterator it = container.getChildren(); it.hasNext(); ) { it.next(); it.remove(); }However, the implementation may do this in an optimized way. In particular, if the node is incomplete, it may choose not to instantiate child node that would become unreachable anyway.
void serialize(OutputStream output) throws javax.xml.stream.XMLStreamException
This method will always serialize the infoset as plain XML. In particular, any OMText
containing optimized binary will be inlined using base64 encoding.
output
- the byte stream to write the serialized infoset tojavax.xml.stream.XMLStreamException
void serialize(Writer writer) throws javax.xml.stream.XMLStreamException
This method will always serialize the infoset as plain XML. In particular, any OMText
containing optimized binary will be inlined using base64 encoding.
writer
- the character stream to write the serialized infoset tojavax.xml.stream.XMLStreamException
void serialize(OutputStream output, OMOutputFormat format) throws javax.xml.stream.XMLStreamException
The format of the output is controlled by the provided OMOutputFormat
object. In
particular, OMOutputFormat.setDoOptimize(boolean)
can be used to instruct this method
to produce an XOP/MTOM encoded MIME message.
output
- the byte stream to write the serialized infoset toformat
- the output format to usejavax.xml.stream.XMLStreamException
void serialize(Writer writer, OMOutputFormat format) throws javax.xml.stream.XMLStreamException
writer
- the character stream to write the serialized infoset toformat
- the output format to usejavax.xml.stream.XMLStreamException
void serializeAndConsume(OutputStream output) throws javax.xml.stream.XMLStreamException
This method will always serialize the infoset as plain XML. In particular, any OMText
containing optimized binary will be inlined using base64 encoding.
output
- the byte stream to write the serialized infoset tojavax.xml.stream.XMLStreamException
void serializeAndConsume(Writer writer) throws javax.xml.stream.XMLStreamException
This method will always serialize the infoset as plain XML. In particular, any OMText
containing optimized binary will be inlined using base64 encoding.
writer
- the character stream to write the serialized infoset tojavax.xml.stream.XMLStreamException
void serializeAndConsume(OutputStream output, OMOutputFormat format) throws javax.xml.stream.XMLStreamException
The format of the output is controlled by the provided OMOutputFormat
object. In
particular, OMOutputFormat.setDoOptimize(boolean)
can be used to instruct this method
to produce an XOP/MTOM encoded MIME message.
output
- the byte stream to write the serialized infoset toformat
- the output format to usejavax.xml.stream.XMLStreamException
void serializeAndConsume(Writer writer, OMOutputFormat format) throws javax.xml.stream.XMLStreamException
writer
- the character stream to write the serialized infoset toformat
- the output format to usejavax.xml.stream.XMLStreamException
javax.xml.stream.XMLStreamReader getXMLStreamReader()
getXMLStreamReader(boolean)
with cache
set to
true
.XMLStreamReader
representation of this elementjavax.xml.stream.XMLStreamReader getXMLStreamReaderWithoutCaching()
getXMLStreamReader(boolean)
with cache
set to
false
.XMLStreamReader
representation of this elementjavax.xml.stream.XMLStreamReader getXMLStreamReader(boolean cache)
XMLStreamReader
instance that produces a sequence of StAX events for this container and
its content. The sequence of events is independent of the state of this element and the value
of the cache
parameter, but the side effects of calling this method and
consuming the reader are different:
State | cache |
Side effects |
---|---|---|
The element is fully built (or was created programmatically). | true |
No side effects. The reader will synthesize StAX events from the object model. |
false |
||
The element is partially built, i.e. deferred parsing is taking place. | true |
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. |
false |
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 (also called "pull through" mode).
This will consume the part of the object model from which the reader was requested.
An attempt to access that part of the object model afterwards will result in a
NodeUnavailableException . Other parts of the object model can be accessed in a normal
way once the reader has been completely consumed or closed. |
To free any resources associated with the returned reader, the caller MUST invoke the
XMLStreamReader.close()
method.
The returned reader MAY implement the extension defined by
DataHandlerReader
and any binary content will
be reported using this extension. More precisely, if the object model contains an
OMText
instance with OMText.isBinary()
returning true
(or
would contain such an instance after it has been fully built), then its data will always be
exposed through this extension.
The caller MUST NOT make any other assumption about the returned reader, in particular about its runtime type.
Note (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:
OMXMLStreamReader
interface of the returned reader to switch
off MTOM inlining using OMXMLStreamReader.setInlineMTOM(boolean)
. This has now been
deprecated and it is recommended to use
XOPEncodingStreamReader
instead.OMAttachmentAccessor
interface of the returned
reader to fetch attachments using OMAttachmentAccessor.getDataHandler(String)
. There
is no reason anymore to do so:
OMXMLStreamReader.setInlineMTOM(boolean)
is used to disable MTOM inlining,
OMAttachmentAccessor.getDataHandler(String)
must be used to retrieve the binary
content. The fact that this method is deprecated removes the need for this.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 cache
parameter, and all binary content is reported through the
DataHandlerReader
extension.OMAttachmentAccessor.getDataHandler(String)
doesn't give access to the attachments in the SwA case (neither in 1.2.9 nor in previous
versions).
Code making any of these assumptions should be fixed, so that only XMLStreamReader
and DataHandlerReader
are used (and if
necessary, XOPEncodingStreamReader
).
cache
- indicates if caching should be enabledXMLStreamReader
representation of this information itemjavax.xml.stream.XMLStreamReader getXMLStreamReader(boolean cache, OMXMLStreamReaderConfiguration configuration)
getXMLStreamReader(boolean)
, but accepts an OMXMLStreamReaderConfiguration
object that allows to specify additional options and to customize the behavior of the
returned reader.cache
- indicates if caching should be enabledconfiguration
- additional configuration options; see the Javadoc of
OMXMLStreamReaderConfiguration
for more information about the available
optionsXMLStreamReader
representation of this information itemSAXSource getSAXSource(boolean cache)
SAXSource
representation for this node. This method can be used to integrate
Axiom with APIs and third party libraries that don't support StAX. In particular it can be
used with the Transformer
API.
The returned object supports all events defined by ContentHandler
and
LexicalHandler
. DTDHandler
and DeclHandler
are not supported.
If the node is an element and has a parent which is not a document, care is taken to properly
generate ContentHandler.startPrefixMapping(String, String)
and
ContentHandler.endPrefixMapping(String)
events also for namespace mappings declared
on the ancestors of the element. To understand why this is important, consider the following
example:
<root xmlns:ns="urn:ns"><element attr="ns:someThing"/><root>
In that case, to correctly interpret the attribute value, the SAX content handler must be aware of the namespace mapping for the ns prefix, even if the serialization starts only at the child element.
No other form of namespace repairing is performed.
SAXResult getSAXResult()
SAXResult
object that can be used to append child nodes to this container. Note
that existing child nodes will not be removed. In order to replace the content of the
container, call removeChildren()
first.
The SAX content handler linked to the returned SAXResult
supports
ContentHandler
, LexicalHandler
, DeclHandler
and DTDHandler
.
DTD related events are processed in the following way:
LexicalHandler.startDTD(String, String, String)
events will create an
OMDocType
if the container is an OMDocument
. If the container is an
OMElement
, the event will be ignored silently.
OMEntityReference
objects are
created for LexicalHandler.startEntity(String)
events.
Nodes created by the ContentHandler
linked to the returned SAXResult
will
have the same characteristics as programmatically created nodes; in particular they will have
no associated builder.
SAXResult
objectOMXMLBuilderFactory.createOMBuilder(SAXSource, boolean)
,
OMXMLBuilderFactory.createOMBuilder(OMFactory, SAXSource, boolean)
Copyright © The Apache Software Foundation. All Rights Reserved.