OMElement (Axiom API 1.2.11-wso2v21 API)

All Superinterfaces:

OMContainer, OMNode, OMSerializable

All Known Subinterfaces:

OMSourcedElement, SOAPBody, SOAPEnvelope, SOAPFault, SOAPFaultClassifier, SOAPFaultCode, SOAPFaultDetail, SOAPFaultNode, SOAPFaultReason, SOAPFaultRole, SOAPFaultSubCode, SOAPFaultText, SOAPFaultValue, SOAPHeader, SOAPHeaderBlock
```
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:
- If the element is created with a namespace and no matching namespace declaration is in scope in the location in the tree where the element is created, then an appropriate namespace declaration will be automatically added to the newly created element. The exact rules depend on the method chosen to create the element; see for example OMFactory.createOMElement(QName).
- If an attribute with a namespace is added, but no matching namespace declaration is in scope in the element, one is automatically added. See addAttribute(OMAttribute) for more details.
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:
- If namespace well-formedness is lost, the string to QName resolution for attribute values and element content may be inconsistent, i.e. resolveQName(String), getTextAsQName() and OMText.getTextAsQName() may return incorrect results. However, it should be noted that these methods are most relevant for object model instances that have been loaded from existing documents or messages. These object models are guaranteed to be well-formed with respect to namespaces (unless they have been modified after loading).
- During serialization, Axiom will automatically repair any namespace inconsistencies. It will add necessary namespace declarations to the output document where they are missing in the object model and generate modified namespace declarations where the original ones in the object model are inconsistent. It will also omit redundant namespace declarations. Axiom guarantees that in the output document, every element and attribute (and OMText instance with a QName value) will have the same namespace URI as in the object model, thus preserving the intended semantics of the document. On the other hand, the namespace prefixes used in the output document may differ from the ones in the object model.
- More precisely, Axiom will always make sure that any OMElement or OMAttribute node will keep the namespace URI that has been assigned to the node at creation time, unless the namespace is explicitly changed using setNamespace(OMNamespace) or OMAttribute.setOMNamespace(OMNamespace). [TODO: this is currently not entirely true; see WSCOMMONS-517]

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

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method and Description
`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.
`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.
`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.
`XMLStreamReader`	`getXMLStreamReader(boolean cache, boolean preserveNamespaceContext)` Get a pull parser representation of this element, optionally preserving the namespace context determined by the ancestors of the element.
`void`	`removeAttribute(OMAttribute attr)` Method removeAttribute
`QName`	`resolveQName(String qname)` Turns a prefix:local qname string into a proper QName, evaluating it in the OMElement context.
`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
  - 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)
```
    Turns a prefix:local qname string into a proper QName, evaluating it in the OMElement context. Unprefixed qnames resolve to the local namespace.
    
    Parameters:
    
    qname - prefixed qname string to resolve
    
    Returns:
    
    Returns null for any failure to extract a qname.
  - 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
  - getXMLStreamReader
```
XMLStreamReader getXMLStreamReader(boolean cache,
                                   boolean preserveNamespaceContext)
```
    Get a pull parser representation of this element, optionally preserving the namespace context determined by the ancestors of the element. This method is similar to OMContainer.getXMLStreamReader(boolean) but supports an additional feature that allows to strictly preserve the namespace context. When this feature is enabled, the XMLStreamReader.getNamespaceCount(), XMLStreamReader.getNamespacePrefix(int) and XMLStreamReader.getNamespaceURI(int) will report additional namespace declarations for the XMLStreamConstants#START_ELEMENT event corresponding to the element on which this method is called, i.e. the root element of the resulting stream. These namespace declarations correspond to namespaces declared by the ancestors of the element and that are visible in the context of the element.
    More precisely, if this feature is enabled, then the namespace declarations reported for the first XMLStreamConstants#START_ELEMENT event in the returned stream will be the same as the declarations that would be returned by #getNamespacesInScope(), with the exception that a xmlns="" declaration present on the element will be preserved.
    This feature is useful for code that relies on the namespace declarations reported by the XMLStreamReader to reconstruct the namespace context (instead of using the namespace context provided by XMLStreamReader.getNamespaceContext()). An example helps to illustrate how this works. Consider the following XML message:
```
 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
     <ns:echo xmlns:ns="urn:test">
       <in xsi:type="xsd:string">test</in>
     </ns:echo>
   </soapenv:Body>
 </soapenv:Envelope>
 
```
    When OMContainer.getXMLStreamReader(boolean) is invoked on the OMElement corresponding to ns:echo, only the namespace declaration for the ns prefix will be reported. This may cause a problem when the caller attempts to resolve the QName value xsd:string of the xsi:type attribute. If namespace context preservation is enabled, then the XMLStreamReader returned by this method will generate additional namespace declarations for the soapenv, xsd and xsi prefixes. They are reported for the XMLStreamConstants#START_ELEMENT event representing the ns:echo element.
    Parameters:
    
    cache - indicates if caching should be enabled
    
    preserveNamespaceContext - indicates if additional namespace declarations should be generated to preserve the namespace context of the element
    
    Returns:
    
    an XMLStreamReader representation of this element

Interface OMElement

Field Summary

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

Method Summary

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

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

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

Method Detail

getChildElements

declareNamespace

declareDefaultNamespace

getDefaultNamespace

declareNamespace

findNamespace

findNamespaceURI

getAllDeclaredNamespaces

getAllAttributes

getAttribute

getAttributeValue

addAttribute

addAttribute

removeAttribute

setBuilder

setFirstChild

getFirstElement

setText

setText

getText

getTextAsQName

getLocalName

setLocalName

getNamespace

setNamespace

setNamespaceWithNoFindInCurrentScope

getQName

toString

toStringWithConsume

resolveQName

cloneOMElement

setLineNumber

getLineNumber

serialize

serialize

serialize

serialize

serializeAndConsume

serializeAndConsume

serializeAndConsume

serializeAndConsume

getXMLStreamReader