Interface OMContainer
-
- All Superinterfaces:
OMInformationItem,OMSerializable
- All Known Subinterfaces:
OMDocument,OMElement,OMSourcedElement,SOAPBody,SOAPEnvelope,SOAPFault,SOAPFaultClassifier,SOAPFaultCode,SOAPFaultDetail,SOAPFaultNode,SOAPFaultReason,SOAPFaultRole,SOAPFaultSubCode,SOAPFaultText,SOAPFaultValue,SOAPHeader,SOAPHeaderBlock,SOAPMessage
public interface OMContainer extends OMSerializable
Captures the operations related to containment shared by both a document and an element.Exposes the ability to add, find, and iterate over the children of a document or element.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description voidaddChild(OMNode omNode)Adds the given node as the last child of this container.OMXMLParserWrappergetBuilder()Returns the builder object.Iterator<OMNode>getChildren()Returns an iterator for the children of the container.Iterator<OMElement>getChildrenWithLocalName(String localName)Returns an iterator for child nodes matching the local name.Iterator<OMElement>getChildrenWithName(QName elementQName)Returns an iterator for child nodes matching the given QName.Iterator<OMElement>getChildrenWithNamespaceURI(String uri)Returns an iterator for child nodes matching the namespace uri.Iterator<? extends OMSerializable>getDescendants(boolean includeSelf)Get an iterator over all descendants of the container.OMElementgetFirstChildWithName(QName qname)Returns the first child in document order that matches the given QName.OMNodegetFirstOMChild()Gets the first child.SAXResultgetSAXResult()Get aSAXResultobject that can be used to append child nodes to this container.SAXSourcegetSAXSource(boolean cache)Get aSAXSourcerepresentation for this node.XMLStreamReadergetXMLStreamReader()Get a pull parser representation of this element with caching enabled.XMLStreamReadergetXMLStreamReader(boolean cache)Get a pull parser representation of this information item.XMLStreamReadergetXMLStreamReader(boolean cache, OMXMLStreamReaderConfiguration configuration)Get a pull parser representation of this information item.XMLStreamReadergetXMLStreamReaderWithoutCaching()Get a pull parser representation of this element with caching disabled.XOPEncoded<XMLStreamReader>getXOPEncodedStreamReader(boolean cache)Get an XOP encoded pull parser representation of this information item.voidremoveChildren()Remove all children from this container.voidserialize(OutputStream output)Deprecated.Useserialize(OutputStream, boolean)instead.voidserialize(OutputStream output, boolean cache)Serialize the node.voidserialize(OutputStream output, OMOutputFormat format)Deprecated.Useserialize(OutputStream, OMOutputFormat, boolean)instead.voidserialize(OutputStream output, OMOutputFormat format, boolean cache)Serialize the node.voidserialize(Writer writer)Deprecated.Useserialize(Writer, boolean)instead.voidserialize(Writer writer, boolean cache)Serialize the node.voidserialize(Writer writer, OMOutputFormat format)Deprecated.Useserialize(Writer, OMOutputFormat, boolean)instead.voidserialize(Writer writer, OMOutputFormat format, boolean cache)Serialize the node.voidserializeAndConsume(OutputStream output)Deprecated.Useserialize(OutputStream, boolean)instead.voidserializeAndConsume(OutputStream output, OMOutputFormat format)Deprecated.Useserialize(OutputStream, OMOutputFormat, boolean)instead.voidserializeAndConsume(Writer writer)Deprecated.Useserialize(Writer, boolean)instead.voidserializeAndConsume(Writer writer, OMOutputFormat format)Deprecated.Useserialize(Writer, OMOutputFormat, boolean)instead.-
Methods inherited from interface org.apache.axiom.om.OMInformationItem
clone, getOMFactory
-
Methods inherited from interface org.apache.axiom.om.OMSerializable
build, close, isComplete, serialize, serialize, serializeAndConsume
-
-
-
-
Method Detail
-
getBuilder
OMXMLParserWrapper getBuilder()
Returns the builder object.- Returns:
- Returns the builder object used to construct the underlying XML infoset on the fly.
-
addChild
void addChild(OMNode omNode)
Adds the given node as the last child of this container.The method may throw an
OMExceptionif the node is not allowed at this position of the document.- Parameters:
omNode- the node to be added to this container
-
getChildrenWithName
Iterator<OMElement> getChildrenWithName(QName elementQName)
Returns an iterator for child nodes matching the given QName.- Parameters:
elementQName- The QName specifying namespace and local name to match.- Returns:
- Returns an iterator of
OMElementitems that match the given QName
-
getChildrenWithLocalName
Iterator<OMElement> getChildrenWithLocalName(String localName)
Returns an iterator for child nodes matching the local name.- Parameters:
localName-- Returns:
- Returns an iterator of
OMElementitems that match the given localName
-
getChildrenWithNamespaceURI
Iterator<OMElement> getChildrenWithNamespaceURI(String uri)
Returns an iterator for child nodes matching the namespace uri.- Parameters:
uri-- Returns:
- Returns an iterator of
OMElementitems that match the given uri
-
getFirstChildWithName
OMElement getFirstChildWithName(QName qname) throws OMException
Returns the first child in document order that matches the given QName. The QName filter is applied in the same way as by thegetChildrenWithName(QName)method.- Parameters:
qname- The QName to use for matching.- Returns:
- The first child element in document order that matches the
qnamecriteria, ornullif none is found. - Throws:
OMException- If an error occurs during deferred parsing.- See Also:
getChildrenWithName(QName)
-
getChildren
Iterator<OMNode> getChildren()
Returns an iterator for the children of the container.- Returns:
- Returns a
Iteratorof children, all of which implementOMNode. - See Also:
getFirstChildWithName(javax.xml.namespace.QName),getChildrenWithName(javax.xml.namespace.QName)
-
getDescendants
Iterator<? extends OMSerializable> getDescendants(boolean includeSelf)
Get an iterator over all descendants of the container. The items are returned in document order. Note that attributes and namespace declarations are not considered descendants.- Parameters:
includeSelf-trueif the iterator should also return the container itself;falseif the first item returned by the iterator should be the first child of the container- Returns:
- an iterator over the descendants of this container
-
getFirstOMChild
OMNode getFirstOMChild()
Gets the first child.- Returns:
- Returns the first child. May return null if the container has no children.
-
removeChildren
void removeChildren()
Remove all children from this container. This method has the same effect as the following code: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.
-
serialize
void serialize(OutputStream output, boolean cache) throws IOException
Serialize the node.This method will always serialize the infoset as plain XML. In particular, any
OMTextcontaining optimized binary will be inlined using base64 encoding.- Parameters:
output- the byte stream to write the serialized infoset tocache- indicates if caching should be enabled- Throws:
IOException- if the stream throws anIOException
-
serialize
void serialize(Writer writer, boolean cache) throws IOException
Serialize the node.This method will always serialize the infoset as plain XML. In particular, any
OMTextcontaining optimized binary will be inlined using base64 encoding.- Parameters:
writer- the character stream to write the serialized infoset tocache- indicates if caching should be enabled- Throws:
IOException- if the stream throws anIOException
-
serialize
void serialize(OutputStream output, OMOutputFormat format, boolean cache) throws IOException
Serialize the node.The format of the output is controlled by the provided
OMOutputFormatobject. In particular,OMOutputFormat.setDoOptimize(boolean)can be used to instruct this method to produce an XOP/MTOM encoded MIME message.- Parameters:
output- the byte stream to write the serialized infoset toformat- the output format to usecache- indicates if caching should be enabled- Throws:
IOException- if the stream throws anIOException
-
serialize
void serialize(Writer writer, OMOutputFormat format, boolean cache) throws IOException
Serialize the node.- Parameters:
writer- the character stream to write the serialized infoset toformat- the output format to usecache- indicates if caching should be enabled- Throws:
IOException- if the stream throws anIOException
-
serialize
void serialize(OutputStream output) throws XMLStreamException
Deprecated.Useserialize(OutputStream, boolean)instead.- Throws:
XMLStreamException
-
serialize
void serialize(Writer writer) throws XMLStreamException
Deprecated.Useserialize(Writer, boolean)instead.- Throws:
XMLStreamException
-
serialize
void serialize(OutputStream output, OMOutputFormat format) throws XMLStreamException
Deprecated.Useserialize(OutputStream, OMOutputFormat, boolean)instead.- Throws:
XMLStreamException
-
serialize
void serialize(Writer writer, OMOutputFormat format) throws XMLStreamException
Deprecated.Useserialize(Writer, OMOutputFormat, boolean)instead.- Throws:
XMLStreamException
-
serializeAndConsume
void serializeAndConsume(OutputStream output) throws XMLStreamException
Deprecated.Useserialize(OutputStream, boolean)instead.- Throws:
XMLStreamException
-
serializeAndConsume
void serializeAndConsume(Writer writer) throws XMLStreamException
Deprecated.Useserialize(Writer, boolean)instead.- Throws:
XMLStreamException
-
serializeAndConsume
void serializeAndConsume(OutputStream output, OMOutputFormat format) throws XMLStreamException
Deprecated.Useserialize(OutputStream, OMOutputFormat, boolean)instead.- Throws:
XMLStreamException
-
serializeAndConsume
void serializeAndConsume(Writer writer, OMOutputFormat format) throws XMLStreamException
Deprecated.Useserialize(Writer, OMOutputFormat, boolean)instead.- Throws:
XMLStreamException
-
getXMLStreamReader
XMLStreamReader getXMLStreamReader()
Get a pull parser representation of this element with caching enabled. This method has the same effect asgetXMLStreamReader(boolean)withcacheset totrue.- Returns:
- an
XMLStreamReaderrepresentation of this element
-
getXMLStreamReaderWithoutCaching
XMLStreamReader getXMLStreamReaderWithoutCaching()
Get a pull parser representation of this element with caching disabled. This method has the same effect asgetXMLStreamReader(boolean)withcacheset tofalse.- Returns:
- an
XMLStreamReaderrepresentation of this element
-
getXMLStreamReader
XMLStreamReader getXMLStreamReader(boolean cache)
Get a pull parser representation of this information item. This methods creates anXMLStreamReaderinstance 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 thecacheparameter, but the side effects of calling this method and consuming the reader are different:Side effects of consuming events from the reader returned by getXMLStreamReader(boolean)State cacheSide effects The element is fully built (or was created programmatically). trueNo side effects. The reader will synthesize StAX events from the object model. falseThe element is partially built, i.e. deferred parsing is taking place. trueWhen 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. falseThe 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
DataHandlerReaderand any binary content will be reported using this extension. More precisely, if the object model contains anOMTextinstance withOMText.isBinary()returningtrue(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.
- Parameters:
cache- indicates if caching should be enabled- Returns:
- an
XMLStreamReaderrepresentation of this information item
-
getXMLStreamReader
XMLStreamReader getXMLStreamReader(boolean cache, OMXMLStreamReaderConfiguration configuration)
Get a pull parser representation of this information item. This method is similar togetXMLStreamReader(boolean), but accepts anOMXMLStreamReaderConfigurationobject that allows to specify additional options and to customize the behavior of the returned reader.- Parameters:
cache- indicates if caching should be enabledconfiguration- additional configuration options; see the Javadoc ofOMXMLStreamReaderConfigurationfor more information about the available options- Returns:
- an
XMLStreamReaderrepresentation of this information item
-
getSAXSource
SAXSource getSAXSource(boolean cache)
Get aSAXSourcerepresentation 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 theTransformerAPI.The returned object supports all events defined by
ContentHandlerandLexicalHandler.DTDHandlerandDeclHandlerare 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)andContentHandler.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
nsprefix, even if the serialization starts only at the child element.No other form of namespace repairing is performed.
-
getSAXResult
SAXResult getSAXResult()
Get aSAXResultobject 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, callremoveChildren()first.The SAX content handler linked to the returned
SAXResultsupportsContentHandler,LexicalHandler,DeclHandlerandDTDHandler. DTD related events are processed in the following way:- A
LexicalHandler.startDTD(String, String, String)events will create anOMDocTypeif the container is anOMDocument. If the container is anOMElement, the event will be ignored silently. - Entity references are always replaced, i.e. no
OMEntityReferenceobjects are created forLexicalHandler.startEntity(String)events.
Nodes created by the
ContentHandlerlinked to the returnedSAXResultwill have the same characteristics as programmatically created nodes; in particular they will have no associated builder.- Returns:
- the
SAXResultobject - See Also:
OMXMLBuilderFactory.createOMBuilder(SAXSource, boolean),OMXMLBuilderFactory.createOMBuilder(OMFactory, SAXSource, boolean)
- A
-
getXOPEncodedStreamReader
XOPEncoded<XMLStreamReader> getXOPEncodedStreamReader(boolean cache)
Get an XOP encoded pull parser representation of this information item.- Parameters:
cache- indicates if caching should be enabled- Returns:
- an XOP encoded representation of this information item
-
-