org.apache.axiom.om
Interface OMElement

All Superinterfaces:
OMContainer, OMNode, OMSerializable
All Known Subinterfaces:
OMSourcedElement, SOAPBody, SOAPEnvelope, SOAPFault, SOAPFaultClassifier, SOAPFaultCode, SOAPFaultDetail, SOAPFaultNode, SOAPFaultReason, SOAPFaultRole, SOAPFaultSubCode, SOAPFaultText, SOAPFaultValue, SOAPHeader, SOAPHeaderBlock
All Known Implementing Classes:
ElementImpl, OMElementImpl, OMSourcedElementImpl, 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, SOAPTextImpl, SOAPTextImpl

public interface OMElement
extends OMNode, OMContainer

A particular kind of node that represents an element infoset information item.

An element has a collection of children, attributes, and namespace declarations. In contrast with DOM, this interface exposes namespace declarations separately from the attributes.

Namespace declarations are either added explicitly using declareNamespace(String, String), declareDefaultNamespace(String) or declareNamespace(OMNamespace), or are created implicitly as side effect of other method calls:

Thus, creating a new element or adding an attribute preserves the consistency of the object model with respect to namespaces. However, Axiom does not enforce namespace well-formedness for all possible operations on the object model. E.g. moving an element from one location in the tree to another one may cause the object model to loose its namespace well-formedness. In that case it is possible that the object model contains elements or attributes with namespaces for which no corresponding namespace declarations are in scope.

Fortunately, loosing namespace well-formedness has only very limited impact:


Field Summary
 
Fields inherited from interface org.apache.axiom.om.OMNode
CDATA_SECTION_NODE, COMMENT_NODE, DTD_NODE, ELEMENT_NODE, ENTITY_REFERENCE_NODE, PI_NODE, SPACE_NODE, TEXT_NODE
 
Method Summary
 OMAttribute addAttribute(OMAttribute attr)
          Adds an attribute to this element.
 OMAttribute addAttribute(String localName, String value, OMNamespace ns)
          Adds an attribute to this element.
 OMElement cloneOMElement()
          Clones this element.
 OMNamespace declareDefaultNamespace(String uri)
          This will declare a default namespace for this element explicitly
 OMNamespace declareNamespace(OMNamespace namespace)
          Declares a namespace with the element as its scope.
 OMNamespace declareNamespace(String uri, String prefix)
          Creates a namespace in the current element scope.
 OMNamespace findNamespace(String uri, String prefix)
          Finds a namespace with the given uri and prefix, in the scope of the hierarchy.
 OMNamespace findNamespaceURI(String prefix)
          Checks for a namespace in the context of this element with the given prefix and returns the relevant namespace object, if available.
 Iterator getAllAttributes()
          Returns a list of OMAttributes.
 Iterator getAllDeclaredNamespaces()
          Returns an iterator for all of the namespaces declared on this element.
 OMAttribute getAttribute(QName qname)
          Returns a named attribute if present.
 String getAttributeValue(QName qname)
          Returns a named attribute's value, if present.
 Iterator getChildElements()
          Returns a filtered list of children - just the elements.
 OMNamespace getDefaultNamespace()
          This will retrieve the default namespace of this element, if available. null returned if none is found.
 OMElement getFirstElement()
          Returns the first child element of the element.
 int getLineNumber()
           
 String getLocalName()
          Returns the local name of the element.
 OMNamespace getNamespace()
          Get the namespace this element is part of.
 String getNamespaceURI()
          Get the namespace URI of the element.
 QName getQName()
          Gets the QName of this node.
 String getText()
          Returns the non-empty text children as a string.
 QName getTextAsQName()
          OMText can contain its information as a QName as well.
 void removeAttribute(OMAttribute attr)
          Method removeAttribute
 QName resolveQName(String qname)
          Resolves a QName literal in the namespace context defined by this element and produces a corresponding QName object.
 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.
 void setBuilder(OMXMLParserWrapper wrapper)
          Method setBuilder.
 void setFirstChild(OMNode node)
          Deprecated. This method should not be called, un-intentionally. When some one randomly set the first child, all the links handling will not happen inside this method. So we have moved this method to the less visible interface, OMContainerEx.
 void setLineNumber(int lineNumber)
           
 void setLocalName(String localName)
          Method setLocalName
 void setNamespace(OMNamespace namespace)
          Sets the Namespace.
 void setNamespaceWithNoFindInCurrentScope(OMNamespace namespace)
          This will not search the namespace in the scope nor will declare in the current element, as in setNamespace(OMNamespace).
 void setText(QName qname)
          Set the content of this element to the given QName.
 void setText(String text)
           
 String toString()
          This is a convenience method only.
 String toStringWithConsume()
          This is a convenience method only.
 
Methods inherited from interface org.apache.axiom.om.OMNode
buildWithAttachments, detach, discard, getNextOMSibling, getParent, getPreviousOMSibling, getType, insertSiblingAfter, insertSiblingBefore
 
Methods inherited from interface org.apache.axiom.om.OMContainer
addChild, buildNext, getBuilder, getChildren, getChildrenWithLocalName, getChildrenWithName, getChildrenWithNamespaceURI, getFirstChildWithName, getFirstOMChild, getXMLStreamReader, getXMLStreamReader, getXMLStreamReaderWithoutCaching
 
Methods inherited from interface org.apache.axiom.om.OMSerializable
build, close, getOMFactory, isComplete, serialize, serialize, serializeAndConsume
 

Method Detail

getChildElements

Iterator getChildElements()
Returns a filtered list of children - just the elements.

Returns:
Returns an iterator over the child elements.
See Also:
OMContainer.getChildren(), OMContainer.getChildrenWithName(javax.xml.namespace.QName)

declareNamespace

OMNamespace declareNamespace(String uri,
                             String prefix)
Creates a namespace in the current element scope.

Parameters:
uri - The namespace to declare in the current scope. The caller is expected to ensure that the URI is a valid namespace name.
prefix - The prefix to associate with the given namespace. The caller is expected to ensure that this is a valid XML prefix. If "" is given, first this will check for an existing namespace with the same uri. If not found, a prefix will be auto-generated.
Returns:
Returns the created namespace information item.
See Also:
declareNamespace(OMNamespace), findNamespace(String, String), getAllDeclaredNamespaces()

declareDefaultNamespace

OMNamespace declareDefaultNamespace(String uri)
This will declare a default namespace for this element explicitly

Parameters:
uri -

getDefaultNamespace

OMNamespace getDefaultNamespace()
This will retrieve the default namespace of this element, if available. null returned if none is found.


declareNamespace

OMNamespace declareNamespace(OMNamespace namespace)
Declares a namespace with the element as its scope.

Parameters:
namespace - The namespace to declare.
Returns:
Returns the namespace parameter passed.
See Also:
declareNamespace(String, String), findNamespace(String, String), getAllDeclaredNamespaces()

findNamespace

OMNamespace findNamespace(String uri,
                          String prefix)
Finds a namespace with the given uri and prefix, in the scope of the hierarchy.

Searches from the current element and goes up the hiararchy until a match is found. If no match is found, returns null.

Either prefix or uri should be null. Results are undefined if both are specified.

Parameters:
uri - The namespace to look for. If this is specified, prefix should be null.
prefix - The prefix to look for. If this is specified, uri should be null.
Returns:
Returns the matching namespace declaration, or null if none was found.
See Also:
declareNamespace(String, String), declareNamespace(OMNamespace), getAllDeclaredNamespaces()

findNamespaceURI

OMNamespace findNamespaceURI(String prefix)
Checks for a namespace in the context of this element with the given prefix and returns the relevant namespace object, if available. If not available, returns null.

Parameters:
prefix -

getAllDeclaredNamespaces

Iterator getAllDeclaredNamespaces()
                                  throws OMException
Returns an iterator for all of the namespaces declared on this element.

If you're interested in all namespaces in scope, you need to call this function for all parent elements as well. Note that the iterator may be invalidated by any call to either declareNamespace function.

Returns:
Returns an iterator over the OMNamespace items declared on the current element.
Throws:
OMException
See Also:
findNamespace(String, String), declareNamespace(String, String), declareNamespace(OMNamespace)

getAllAttributes

Iterator getAllAttributes()
Returns a list of OMAttributes.

Note that the iterator returned by this function will be invalidated by any addAttribute call.

Returns:
Returns an Iterator of OMAttribute items associated with the element.
See Also:
getAttribute(javax.xml.namespace.QName), addAttribute(OMAttribute), addAttribute(String, String, OMNamespace)

getAttribute

OMAttribute getAttribute(QName qname)
Returns a named attribute if present.

Parameters:
qname - the qualified name to search for
Returns:
Returns an OMAttribute with the given name if found, or null

getAttributeValue

String getAttributeValue(QName qname)
Returns a named attribute's value, if present.

Parameters:
qname - the qualified name to search for
Returns:
The attribute value, or null if no matching attribute is found.

addAttribute

OMAttribute addAttribute(OMAttribute attr)
Adds an attribute to this element.

If the attribute already has an owner, the attribute is cloned (i.e. its name, value and namespace are copied to a new attribute) and the new attribute is added to the element. Otherwise the existing instance specified by the attr parameter is added to the element. In both cases the owner of the added attribute is set to be the particular OMElement.

If there is already an attribute with the same name and namespace URI, it will be replaced and its owner set to null.

In the particular case where the attribute specified by attr is already owned by the element, calling this method has no effect.

Attributes are not stored in any particular order. In particular, there is no guarantee that the added attribute will be returned as the last item by the iterator produced by a subsequent call to getAllAttributes().

If the attribute being added has a namespace, but no corresponding namespace declaration is in scope for the element (i.e. declared on the element or one of its ancestors), a new namespace declaration is added to the element. Note that both the namespace prefix and URI are taken into account when looking for an existing namespace declaration.

Parameters:
attr - The attribute to add.
Returns:
The attribute that was added to the element. As described above this may or may not be the same as attr, depending on whether the attribute specified by this parameter already has an owner or not.

addAttribute

OMAttribute addAttribute(String localName,
                         String value,
                         OMNamespace ns)
Adds an attribute to this element.

If the element already has an attribute with the same local name and namespace URI, then this existing attribute will be removed from the element, i.e. this method will always create a new OMAttribute instance and never update an existing one.

Parameters:
localName - The local name for the attribute.
value - The string value of the attribute. This function does not check to make sure that the given attribute value can be serialized directly as an XML value. The caller may, for example, pass a string with the character 0x01.
ns - The namespace has to be one of the in scope namespace. i.e. the passed namespace must be declared in the parent element of this attribute or ancestors of the parent element of the attribute.
Returns:
Returns the added attribute.

removeAttribute

void removeAttribute(OMAttribute attr)
Method removeAttribute

Parameters:
attr -

setBuilder

void setBuilder(OMXMLParserWrapper wrapper)
Method setBuilder.

Parameters:
wrapper -

setFirstChild

void setFirstChild(OMNode node)
Deprecated. This method should not be called, un-intentionally. When some one randomly set the first child, all the links handling will not happen inside this method. So we have moved this method to the less visible interface, OMContainerEx.

Sets the first child.

Parameters:
node -

getFirstElement

OMElement getFirstElement()
Returns the first child element of the element.

Returns:
Returns the first child element of the element, or null if none was found.

setText

void setText(String text)
Parameters:
text -

setText

void setText(QName qname)
Set the content of this element to the given QName. If no matching namespace declaration for the QName is in scope, then this method will add one.

Parameters:
qname - the QName value

getText

String getText()
Returns the non-empty text children as a string.

This method iterates over all the text children of the element and concatenates them to a single string. Only direct children will be considered, i.e. the text is not extracted recursively. For example the return value for <element>A<child>B</child>C</element> will be AC.

All whitespace will be preserved.

Returns:
A string representing the concatenation of the child text nodes. If there are no child text nodes, an empty string is returned.

getTextAsQName

QName getTextAsQName()
OMText can contain its information as a QName as well. This will return the text as a QName


getLocalName

String getLocalName()
Returns the local name of the element.

Returns:
Returns the local name of the element.

setLocalName

void setLocalName(String localName)
Method setLocalName

Parameters:
localName -

getNamespace

OMNamespace getNamespace()
Get the namespace this element is part of.

Returns:
the namespace of this element, or null if the element has no namespace

getNamespaceURI

String getNamespaceURI()
Get the namespace URI of the element. Note that the contract of this method is identical to DOM's Node.getNamespaceURI() (when called on an Element).

Returns:
the namespace URI of the element or null if the element has no namespace

setNamespace

void setNamespace(OMNamespace namespace)
Sets the Namespace. This will first search for a namespace in the current scope with the given namespace. If no namespace is found with the given details, then it will declare a new one. Then that namespace will be assigned to this element.

Parameters:
namespace -

setNamespaceWithNoFindInCurrentScope

void setNamespaceWithNoFindInCurrentScope(OMNamespace namespace)
This will not search the namespace in the scope nor will declare in the current element, as in setNamespace(OMNamespace). This will just assign the given namespace to the element.

Parameters:
namespace -

getQName

QName getQName()
Gets the QName of this node.

Returns:
Returns the QName for the element.

toString

String toString()
This is a convenience method only. This will basically serialize the given OMElement to a String but will build the OMTree in the memory

Overrides:
toString in class Object

toStringWithConsume

String toStringWithConsume()
                           throws XMLStreamException
This is a convenience method only. This basically serializes the given OMElement to a String but will NOT build the OMTree in the memory. So you are at your own risk of losing information.

Throws:
XMLStreamException

resolveQName

QName resolveQName(String qname)
Resolves a QName literal in the namespace context defined by this element and produces a corresponding QName object. The implementation uses the algorithm defined by the XML Schema specification. In particular, the namespace for an unprefixed QName is the default namespace (not the null namespace), i.e. QNames are resolved in the same way as element names.

Parameters:
qname - the QName literal to resolve
Returns:
the QName object, or null if the QName can't be resolved, i.e. if the prefix is not bound in the namespace context of this element

cloneOMElement

OMElement cloneOMElement()
Clones this element. Since both elements are build compleletely, you will lose the differed building capability.

Returns:
Returns OMElement.

setLineNumber

void setLineNumber(int lineNumber)

getLineNumber

int getLineNumber()

serialize

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

Specified by:
serialize in interface OMContainer
Specified by:
serialize in interface OMNode
Parameters:
output -
Throws:
XMLStreamException

serialize

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

Specified by:
serialize in interface OMContainer
Specified by:
serialize in interface OMNode
Parameters:
writer -
Throws:
XMLStreamException

serialize

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

Specified by:
serialize in interface OMContainer
Specified by:
serialize in interface OMNode
Parameters:
output -
format -
Throws:
XMLStreamException

serialize

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

Specified by:
serialize in interface OMContainer
Specified by:
serialize in interface OMNode
Parameters:
writer -
format -
Throws:
XMLStreamException

serializeAndConsume

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

Specified by:
serializeAndConsume in interface OMContainer
Specified by:
serializeAndConsume in interface OMNode
Parameters:
output -
Throws:
XMLStreamException

serializeAndConsume

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

Specified by:
serializeAndConsume in interface OMContainer
Specified by:
serializeAndConsume in interface OMNode
Parameters:
writer -
Throws:
XMLStreamException

serializeAndConsume

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

Specified by:
serializeAndConsume in interface OMContainer
Specified by:
serializeAndConsume in interface OMNode
Parameters:
output -
format -
Throws:
XMLStreamException

serializeAndConsume

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

Specified by:
serializeAndConsume in interface OMContainer
Specified by:
serializeAndConsume in interface OMNode
Parameters:
writer -
format -
Throws:
XMLStreamException


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