org.apache.axiom.om
Interface OMContainer

All Superinterfaces:
OMSerializable
All Known Subinterfaces:
OMContainerEx, OMDocument, OMElement, OMSourcedElement, SOAPBody, SOAPEnvelope, SOAPFault, SOAPFaultClassifier, SOAPFaultCode, SOAPFaultDetail, SOAPFaultNode, SOAPFaultReason, SOAPFaultRole, SOAPFaultSubCode, SOAPFaultText, SOAPFaultValue, SOAPHeader, SOAPHeaderBlock, SOAPMessage
All Known Implementing Classes:
DocumentFragmentImpl, DocumentImpl, ElementImpl, OMDocumentImpl, OMElementImpl, OMSourcedElementImpl, ParentNode, SOAP11BodyImpl, SOAP11BodyImpl, SOAP11FaultCodeImpl, SOAP11FaultCodeImpl, SOAP11FaultDetailImpl, SOAP11FaultDetailImpl, SOAP11FaultImpl, SOAP11FaultImpl, SOAP11FaultReasonImpl, SOAP11FaultReasonImpl, SOAP11FaultRoleImpl, SOAP11FaultRoleImpl, SOAP11FaultSubCodeImpl, SOAP11FaultSubCodeImpl, SOAP11FaultTextImpl, SOAP11FaultTextImpl, SOAP11FaultValueImpl, SOAP11FaultValueImpl, SOAP11HeaderBlockImpl, SOAP11HeaderBlockImpl, SOAP11HeaderImpl, SOAP11HeaderImpl, SOAP12BodyImpl, SOAP12BodyImpl, SOAP12FaultCodeImpl, SOAP12FaultCodeImpl, SOAP12FaultDetailImpl, SOAP12FaultDetailImpl, SOAP12FaultImpl, SOAP12FaultImpl, SOAP12FaultNodeImpl, SOAP12FaultNodeImpl, SOAP12FaultReasonImpl, SOAP12FaultReasonImpl, SOAP12FaultRoleImpl, SOAP12FaultRoleImpl, SOAP12FaultSubCodeImpl, SOAP12FaultSubCodeImpl, SOAP12FaultTextImpl, SOAP12FaultTextImpl, SOAP12FaultValueImpl, SOAP12FaultValueImpl, SOAP12HeaderBlockImpl, SOAP12HeaderBlockImpl, SOAP12HeaderImpl, SOAP12HeaderImpl, SOAPBodyImpl, SOAPBodyImpl, SOAPElement, SOAPElement, SOAPEnvelopeImpl, SOAPEnvelopeImpl, SOAPFaultCodeImpl, SOAPFaultCodeImpl, SOAPFaultDetailImpl, SOAPFaultDetailImpl, SOAPFaultImpl, SOAPFaultImpl, SOAPFaultNodeImpl, SOAPFaultNodeImpl, SOAPFaultReasonImpl, SOAPFaultReasonImpl, SOAPFaultRoleImpl, SOAPFaultRoleImpl, SOAPFaultSubCodeImpl, SOAPFaultSubCodeImpl, SOAPFaultTextImpl, SOAPFaultTextImpl, SOAPFaultValueImpl, SOAPFaultValueImpl, SOAPHeaderBlockImpl, SOAPHeaderBlockImpl, SOAPHeaderImpl, SOAPHeaderImpl, SOAPMessageImpl, SOAPMessageImpl, SOAPTextImpl, SOAPTextImpl

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
 void addChild(OMNode omNode)
          Adds the given node as the last child.
 void buildNext()
           
 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.
 OMElement getFirstChildWithName(QName qname)
          Returns the first child in document order that matches the given QName.
 OMNode getFirstOMChild()
          Gets the first child.
 XMLStreamReader getXMLStreamReader()
          Get a pull parser representation of this element with caching enabled.
 XMLStreamReader getXMLStreamReader(boolean cache)
          Get a pull parser representation of this element.
 XMLStreamReader getXMLStreamReaderWithoutCaching()
          Get a pull parser representation of this element with caching disabled.
 void serialize(OutputStream output)
          Serializes the node with caching.
 void serialize(OutputStream output, OMOutputFormat format)
          Serializes the node with caching.
 void serialize(Writer writer)
          Serializes the node with caching.
 void serialize(Writer writer, OMOutputFormat format)
          Serializes the node with caching.
 void serializeAndConsume(OutputStream output)
          Serializes the node without caching.
 void serializeAndConsume(OutputStream output, OMOutputFormat format)
          Serializes the node without caching.
 void serializeAndConsume(Writer writer)
          Serializes the node without caching.
 void serializeAndConsume(Writer writer, OMOutputFormat format)
          Serializes the node without caching.
 
Methods inherited from interface org.apache.axiom.om.OMSerializable
build, close, getOMFactory, 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. One must preserve the order of children, in this operation. Tip : appending the new child is preferred.

Parameters:
omNode -

getChildrenWithName

Iterator 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 OMElement items that match the given QName

getChildrenWithLocalName

Iterator getChildrenWithLocalName(String localName)
Returns an iterator for child nodes matching the local name.

Parameters:
localName -
Returns:
Returns an iterator of OMElement items that match the given localName

getChildrenWithNamespaceURI

Iterator getChildrenWithNamespaceURI(String uri)
Returns an iterator for child nodes matching the namespace uri.

Parameters:
uri -
Returns:
Returns an iterator of OMElement items 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 the getChildrenWithName(QName) method.

Parameters:
qname - The QName to use for matching.
Returns:
The first child element in document order that matches the qname criteria, or null if none is found.
Throws:
OMException - If an error occurs during deferred parsing.
See Also:
getChildrenWithName(QName)

getChildren

Iterator getChildren()
Returns an iterator for the children of the container.

Returns:
Returns a Iterator of children, all of which implement OMNode.
See Also:
getFirstChildWithName(javax.xml.namespace.QName), getChildrenWithName(javax.xml.namespace.QName)

getFirstOMChild

OMNode getFirstOMChild()
Gets the first child.

Returns:
Returns the first child. May return null if the container has no children.

serialize

void serialize(OutputStream output)
               throws XMLStreamException
Serializes the node with caching.

Parameters:
output -
Throws:
XMLStreamException

serialize

void serialize(Writer writer)
               throws XMLStreamException
Serializes the node with caching.

Parameters:
writer -
Throws:
XMLStreamException

serialize

void serialize(OutputStream output,
               OMOutputFormat format)
               throws XMLStreamException
Serializes the node with caching.

Parameters:
output -
format -
Throws:
XMLStreamException

serialize

void serialize(Writer writer,
               OMOutputFormat format)
               throws XMLStreamException
Serializes the node with caching.

Parameters:
writer -
format -
Throws:
XMLStreamException

serializeAndConsume

void serializeAndConsume(OutputStream output)
                         throws XMLStreamException
Serializes the node without caching.

Parameters:
output -
Throws:
XMLStreamException

serializeAndConsume

void serializeAndConsume(Writer writer)
                         throws XMLStreamException
Serializes the node without caching.

Parameters:
writer -
Throws:
XMLStreamException

serializeAndConsume

void serializeAndConsume(OutputStream output,
                         OMOutputFormat format)
                         throws XMLStreamException
Serializes the node without caching.

Parameters:
output -
format -
Throws:
XMLStreamException

serializeAndConsume

void serializeAndConsume(Writer writer,
                         OMOutputFormat format)
                         throws XMLStreamException
Serializes the node without caching.

Parameters:
writer -
format -
Throws:
XMLStreamException

buildNext

void buildNext()

getXMLStreamReader

XMLStreamReader getXMLStreamReader()
Get a pull parser representation of this element with caching enabled. This method has the same effect as getXMLStreamReader(boolean) with cache set to true.

Returns:
an XMLStreamReader representation of this element

getXMLStreamReaderWithoutCaching

XMLStreamReader getXMLStreamReaderWithoutCaching()
Get a pull parser representation of this element with caching disabled. This method has the same effect as getXMLStreamReader(boolean) with cache set to false.

Returns:
an XMLStreamReader representation of this element

getXMLStreamReader

XMLStreamReader getXMLStreamReader(boolean cache)
Get a pull parser representation of this element. This methods creates an XMLStreamReader instance that produces a sequence of StAX events for this element 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. An attempt to access the object model afterwards will result in an error.

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:

Code making any of these assumptions should be fixed, so that only XMLStreamReader and DataHandlerReader are used (and if necessary, XOPEncodingStreamReader).

Parameters:
cache - indicates if caching should be enabled
Returns:
an XMLStreamReader representation of this element


Copyright © 2004-2013 The Apache Software Foundation. All Rights Reserved.