org.apache.axiom.om.impl.llom

Class OMDocumentImpl

java.lang.Object

org.apache.axiom.om.impl.llom.OMSerializableImpl

org.apache.axiom.om.impl.llom.OMDocumentImpl

All Implemented Interfaces:

IContainer, IParentNode, OMContainerEx, OMContainer, OMDocument, OMInformationItem, OMSerializable

Direct Known Subclasses:

SOAPMessageImpl

public class OMDocumentImpl
extends OMSerializableImpl
implements OMDocument, IContainer

Class OMDocumentImpl

Field Summary

Fields

Modifier and Type	Field and Description
protected OMXMLParserWrapper	builder
protected String	charSetEncoding Field charSetEncoding Default : UTF-8
protected OMNode	firstChild Field firstChild
protected String	isStandalone
protected OMNode	lastChild Field lastChild
protected int	state
protected String	xmlEncoding
protected String	xmlVersion Field xmlVersion

Fields inherited from class org.apache.axiom.om.impl.llom.OMSerializableImpl

factory

Fields inherited from interface org.apache.axiom.om.OMDocument

XML_10, XML_11

Fields inherited from interface org.apache.axiom.om.impl.common.IParentNode

COMPLETE, DISCARDED, INCOMPLETE

Constructor Summary

Constructors

Constructor and Description
OMDocumentImpl(OMFactory factory) Create a OMDocument given the OMFactory
OMDocumentImpl(OMXMLParserWrapper parserWrapper, OMFactory factory) Create the OMDocument with the factory

Method Summary

Modifier and Type	Method and Description
void	addChild(OMNode child) Adds the given node as the last child of this container.
void	addChild(OMNode omNode, boolean fromBuilder)
void	build() Builds itself.
OMInformationItem	clone(OMCloneOptions options) Clone this information item.
protected OMDocument	createClone(OMCloneOptions options)
void	discarded()
OMXMLParserWrapper	getBuilder() Returns the builder object.
String	getCharsetEncoding() Get the character set encoding scheme.
Iterator	getChildren() Returns a collection of this element.
Iterator	getChildrenWithLocalName(String localName) Returns an iterator for child nodes matching the local name.
Iterator	getChildrenWithName(QName elementQName) Searches for children with a given QName and returns an iterator to traverse through the OMNodes.
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 elementQName) Method getFirstChildWithName.
OMNode	getFirstOMChild() Method getFirstOMChild.
OMNode	getFirstOMChildIfAvailable() Get the first child if it is available.
OMNode	getLastKnownOMChild()
OMElement	getOMDocumentElement() Get the document element.
SAXSource	getSAXSource(boolean cache) Get a SAXSource representation for this node.
int	getState()
String	getXMLEncoding() Get the charset encoding of this document as specified in the XML declaration.
XMLStreamReader	getXMLStreamReader() Get a pull parser representation of this element with caching enabled.
XMLStreamReader	getXMLStreamReader(boolean cache) Get a pull parser representation of this information item.
XMLStreamReader	getXMLStreamReader(boolean cache, OMXMLStreamReaderConfiguration configuration) Get a pull parser representation of this information item.
XMLStreamReader	getXMLStreamReaderWithoutCaching() Get a pull parser representation of this element with caching disabled.
String	getXMLVersion() Returns the XML version.
void	internalSerialize(XMLStreamWriter writer) Serializes the document with cache.
void	internalSerialize(XMLStreamWriter writer, boolean cache) Serializes the node.
protected void	internalSerialize(XMLStreamWriter writer, boolean cache, boolean includeXMLDeclaration)
void	internalSerializeAndConsume(XMLStreamWriter writer) Serializes the document with the XML declaration.
boolean	isComplete() Indicates whether parser has parsed this information item completely or not.
String	isStandalone() XML standalone value.
void	removeChildren() Remove all children from this container.
void	setCharsetEncoding(String charEncoding) Sets the character set encoding scheme to be used.
void	setComplete(boolean complete) Method setComplete.
void	setFirstChild(OMNode firstChild) Method setFirstChild.
void	setLastChild(OMNode omNode) Forcefully set the last child
void	setOMDocumentElement(OMElement documentElement) Set the document element of the XML document.
void	setStandalone(String isStandalone)
void	setXMLEncoding(String encoding) Set the charset encoding for the XML declaration of this document.
void	setXMLVersion(String xmlVersion) Sets the XML version.

Methods inherited from class org.apache.axiom.om.impl.llom.OMSerializableImpl

close, getOMFactory, serialize, serialize, serialize, serialize, serialize, serialize, serializeAndConsume, serializeAndConsume, serializeAndConsume, serializeAndConsume, serializeAndConsume

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.axiom.om.OMContainer

serialize, serialize, serialize, serialize, serializeAndConsume, serializeAndConsume, serializeAndConsume, serializeAndConsume

Methods inherited from interface org.apache.axiom.om.OMSerializable

close, serialize, serialize, serializeAndConsume

Methods inherited from interface org.apache.axiom.om.OMInformationItem

getOMFactory

Field Detail

builder

protected OMXMLParserWrapper builder

state

protected int state

firstChild

protected OMNode firstChild

Field firstChild

lastChild

protected OMNode lastChild

Field lastChild

charSetEncoding

protected String charSetEncoding

Field charSetEncoding Default : UTF-8

xmlVersion

protected String xmlVersion

Field xmlVersion

xmlEncoding

protected String xmlEncoding

isStandalone

protected String isStandalone

Constructor Detail

OMDocumentImpl

public OMDocumentImpl(OMFactory factory)

Create a OMDocument given the OMFactory

Parameters:

factory - The OMFactory that created this instace

OMDocumentImpl

public OMDocumentImpl(OMXMLParserWrapper parserWrapper,
                      OMFactory factory)

Create the OMDocument with the factory

Parameters:

parserWrapper -

factory -

Method Detail

getBuilder

public OMXMLParserWrapper getBuilder()

Description copied from interface: OMContainer

Returns the builder object.

Specified by:

getBuilder in interface IParentNode

Specified by:

getBuilder in interface OMContainer

Specified by:

getBuilder in class OMSerializableImpl

Returns:

Returns the builder object used to construct the underlying XML infoset on the fly.

getOMDocumentElement

public OMElement getOMDocumentElement()

Description copied from interface: OMDocument

Get the document element.

Specified by:

getOMDocumentElement in interface OMDocument

Returns:

the document element, or null if the document doesn't have any children of type OMElement

setOMDocumentElement

public void setOMDocumentElement(OMElement documentElement)

Description copied from interface: OMDocument

Set the document element of the XML document. If the document has no document element, then the new document element will be appended as the last child. If the document already has a document element, then it will be replaced by the new one and the position of the other children relative to the document element is preserved.

Specified by:

setOMDocumentElement in interface OMDocument

Parameters:

documentElement - the new document element; must not be null

getState

public int getState()

Specified by:

getState in interface IParentNode

isComplete

public boolean isComplete()

Description copied from interface: OMSerializable

Indicates whether parser has parsed this information item completely or not. If some info are not available in the item, one has to check this attribute to make sure that, this item has been parsed completely or not.

Specified by:

isComplete in interface IParentNode

Specified by:

isComplete in interface OMSerializable

Returns:

Returns boolean.

setComplete

public void setComplete(boolean complete)

Method setComplete.

Specified by:

setComplete in interface OMContainerEx

Specified by:

setComplete in class OMSerializableImpl

Parameters:

state -

discarded

public void discarded()

Specified by:

discarded in interface OMContainerEx

addChild

public void addChild(OMNode child)

Description copied from interface: OMContainer

Adds the given node as the last child of this container.

Specified by:

addChild in interface OMContainer

Parameters:

child - the node to be added to this container

addChild

public void addChild(OMNode omNode,
                     boolean fromBuilder)

Specified by:

addChild in interface OMContainerEx

getChildren

public Iterator getChildren()

Returns a collection of this element. Children can be of types OMElement, OMText.

Specified by:

getChildren in interface OMContainer

Returns:

Returns iterator.

See Also:

OMContainer.getFirstChildWithName(javax.xml.namespace.QName), OMContainer.getChildrenWithName(javax.xml.namespace.QName)

getDescendants

public Iterator getDescendants(boolean includeSelf)

Description copied from interface: OMContainer

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.

Specified by:

getDescendants in interface OMContainer

Parameters:

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 container

Returns:

an iterator over the descendants of this container

getChildrenWithName

public Iterator getChildrenWithName(QName elementQName)

Searches for children with a given QName and returns an iterator to traverse through the OMNodes. The QName can contain any combination of prefix, localname and URI.

Specified by:

getChildrenWithName in interface OMContainer

Parameters:

elementQName -

Returns:

Returns Iterator.

Throws:

OMException

getChildrenWithLocalName

public Iterator getChildrenWithLocalName(String localName)

Description copied from interface: OMContainer

Returns an iterator for child nodes matching the local name.

Specified by:

getChildrenWithLocalName in interface OMContainer

Returns:

Returns an iterator of OMElement items that match the given localName

getChildrenWithNamespaceURI

public Iterator getChildrenWithNamespaceURI(String uri)

Description copied from interface: OMContainer

Returns an iterator for child nodes matching the namespace uri.

Specified by:

getChildrenWithNamespaceURI in interface OMContainer

Returns:

Returns an iterator of OMElement items that match the given uri

getFirstOMChild

public OMNode getFirstOMChild()

Method getFirstOMChild.

Specified by:

getFirstOMChild in interface OMContainer

Returns:

Returns first om child.

getFirstOMChildIfAvailable

public OMNode getFirstOMChildIfAvailable()

Description copied from interface: IParentNode

Get the first child if it is available. The child is available if it is complete or if the builder has started building the node. In the latter case, OMSerializable.isComplete() may return false when called on the child. In contrast to OMContainer.getFirstOMChild(), this method will never modify the state of the underlying parser.

Specified by:

getFirstOMChildIfAvailable in interface IParentNode

Returns:

the first child or null if the container has no children or the builder has not yet started to build the first child

getLastKnownOMChild

public OMNode getLastKnownOMChild()

Specified by:

getLastKnownOMChild in interface IContainer

getFirstChildWithName

public OMElement getFirstChildWithName(QName elementQName)
                                throws OMException

Method getFirstChildWithName.

Specified by:

getFirstChildWithName in interface OMContainer

Parameters:

elementQName -

Returns:

Returns OMElement.

Throws:

OMException

See Also:

OMContainer.getChildrenWithName(QName)

setFirstChild

public void setFirstChild(OMNode firstChild)

Method setFirstChild.

Specified by:

setFirstChild in interface IContainer

Parameters:

firstChild -

setLastChild

public void setLastChild(OMNode omNode)

Forcefully set the last child

Specified by:

setLastChild in interface IContainer

Parameters:

omNode -

getCharsetEncoding

public String getCharsetEncoding()

Description copied from interface: OMDocument

Get the character set encoding scheme. This is the encoding that was used used for this document at the time of the parsing. This is null when it is not known, such as when the document was created in memory or from a character stream.

Specified by:

getCharsetEncoding in interface OMDocument

Returns:

the charset encoding for this document, or null if the encoding is not known

setCharsetEncoding

public void setCharsetEncoding(String charEncoding)

Description copied from interface: OMDocument

Sets the character set encoding scheme to be used.

Specified by:

setCharsetEncoding in interface OMDocument

isStandalone

public String isStandalone()

Description copied from interface: OMDocument

XML standalone value. This will be yes, no or null (if not available)

Specified by:

isStandalone in interface OMDocument

Returns:

Returns boolean.

setStandalone

public void setStandalone(String isStandalone)

Specified by:

setStandalone in interface OMDocument

getXMLVersion

public String getXMLVersion()

Description copied from interface: OMDocument

Returns the XML version.

Specified by:

getXMLVersion in interface OMDocument

Returns:

Returns String.

setXMLVersion

public void setXMLVersion(String xmlVersion)

Description copied from interface: OMDocument

Sets the XML version.

Specified by:

setXMLVersion in interface OMDocument

See Also:

OMDocument.XML_10, OMDocument.XML_11

getXMLEncoding

public String getXMLEncoding()

Description copied from interface: OMDocument

Get the charset encoding of this document as specified in the XML declaration.

Specified by:

getXMLEncoding in interface OMDocument

Returns:

the charset encoding specified in the XML declaration, or null if the document didn't have an XML declaration or if the encoding attribute was not specified in the XML declaration

setXMLEncoding

public void setXMLEncoding(String encoding)

Description copied from interface: OMDocument

Set the charset encoding for the XML declaration of this document.

Specified by:

setXMLEncoding in interface OMDocument

Parameters:

encoding - the value of the encoding attribute of the XML declaration

internalSerialize

public void internalSerialize(XMLStreamWriter writer,
                              boolean cache)
                       throws XMLStreamException

Description copied from class: OMSerializableImpl

Serializes the node.

Specified by:

internalSerialize in class OMSerializableImpl

Throws:

XMLStreamException

internalSerialize

protected void internalSerialize(XMLStreamWriter writer,
                                 boolean cache,
                                 boolean includeXMLDeclaration)
                          throws XMLStreamException

Throws:

XMLStreamException

internalSerializeAndConsume

public void internalSerializeAndConsume(XMLStreamWriter writer)
                                 throws XMLStreamException

Serializes the document with the XML declaration.

Throws:

XMLStreamException

internalSerialize

public void internalSerialize(XMLStreamWriter writer)
                       throws XMLStreamException

Serializes the document with cache.

Throws:

XMLStreamException

getXMLStreamReader

public XMLStreamReader getXMLStreamReader()

Description copied from interface: OMContainer

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

Specified by:

getXMLStreamReader in interface OMContainer

Returns:

an XMLStreamReader representation of this element

getXMLStreamReaderWithoutCaching

public XMLStreamReader getXMLStreamReaderWithoutCaching()

Description copied from interface: OMContainer

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

Specified by:

getXMLStreamReaderWithoutCaching in interface OMContainer

Returns:

an XMLStreamReader representation of this element

getXMLStreamReader

public XMLStreamReader getXMLStreamReader(boolean cache)

Description copied from interface: OMContainer

Get a pull parser representation of this information item. 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:

• Some code assumes that the returned reader is an instance of OMStAXWrapper. While it is true that Axiom internally uses this class to synthesize StAX events, it may wrap this instance in another reader implementation. E.g. depending on the log level, the reader will be wrapped using OMXMLStreamReaderValidator. This was already the case in Axiom versions prior to 1.2.9. It should also be noted that instances of OMSourcedElement (which extends the present interface) may return a reader that is not implemented using OMStAXWrapper.
• Some code uses the 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.
• Some existing code uses the OMAttachmentAccessor interface of the returned reader to fetch attachments using OMAttachmentAccessor.getDataHandler(String). There is no reason anymore to do so:
• When 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.
• In Axiom versions prior to 1.2.9, the sequence of events was inconsistent if the underlying stream is XOP encoded and caching is disabled (see AXIOM-255). This made it necessary for the caller to (partially) handle the XOP processing and to use 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.
• Finally, it should be noted that 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).

Specified by:

getXMLStreamReader in interface OMContainer

Parameters:

cache - indicates if caching should be enabled

Returns:

an XMLStreamReader representation of this information item

getXMLStreamReader

public XMLStreamReader getXMLStreamReader(boolean cache,
                                          OMXMLStreamReaderConfiguration configuration)

Description copied from interface: OMContainer

Get a pull parser representation of this information item. This method is similar to OMContainer.getXMLStreamReader(boolean), but accepts an OMXMLStreamReaderConfiguration object that allows to specify additional options and to customize the behavior of the returned reader.

Specified by:

getXMLStreamReader in interface OMContainer

Parameters:

cache - indicates if caching should be enabled

configuration - additional configuration options; see the Javadoc of OMXMLStreamReaderConfiguration for more information about the available options

Returns:

an XMLStreamReader representation of this information item

getSAXSource

public SAXSource getSAXSource(boolean cache)

Description copied from interface: OMContainer

Get a 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.

Specified by:

getSAXSource in interface OMContainer

Parameters:

cache - Indicates if caching should be enabled. If set to false, the returned SAXSource may only be used once, and using it may have the side effect of consuming the original content of this node.

Returns:

a SAXSource representation of this element

build

public void build()

Description copied from interface: OMSerializable

Builds itself.

Specified by:

build in interface OMSerializable

removeChildren

public void removeChildren()

Description copied from interface: OMContainer

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.

Specified by:

removeChildren in interface OMContainer

clone

public OMInformationItem clone(OMCloneOptions options)

Description copied from interface: OMInformationItem

Clone this information item. If the information item is a container, then its descendants will be cloned recursively. Note that in this case, this method will traverse the descendants and create clones immediately. It will also preserve the original nodes. This means that after the execution of this method, both the returned clone and the original container will be completely built.

Specified by:

clone in interface OMInformationItem

Parameters:

options - the options to use when cloning this element and its descendants; for object models with domain specific extensions (such as SOAP), this may be a subclass of OMCloneOptions

Returns:

the cloned element

createClone

protected OMDocument createClone(OMCloneOptions options)