public interface OMElement extends OMNode, OMContainer, OMNamedInformationItem
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:
OMFactory.createOMElement(QName).
addAttribute(OMAttribute) for more
details.
Fortunately, loosing namespace well-formedness has only very limited impact:
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).
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.
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
OMNamedInformationItem.setNamespace(OMNamespace, boolean).
CDATA_SECTION_NODE, COMMENT_NODE, DTD_NODE, ELEMENT_NODE, ENTITY_REFERENCE_NODE, PI_NODE, SPACE_NODE, TEXT_NODE| 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 and its descendants using default options.
|
OMNamespace |
declareDefaultNamespace(String uri)
Add a namespace declaration for the default namespace to this element.
|
OMNamespace |
declareNamespace(OMNamespace namespace)
Declares a namespace with the element as its scope.
|
OMNamespace |
declareNamespace(String uri,
String prefix)
Add a namespace declaration for the given namespace URI to this element, optionally
generating a prefix for that namespace.
|
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()
Get the default namespace in scope on this element.
|
OMElement |
getFirstElement()
Returns the first child element of the element.
|
int |
getLineNumber() |
NamespaceContext |
getNamespaceContext(boolean detached)
Get the namespace context of this element, as determined by the namespace declarations
present on this element and its ancestors.
|
Iterator |
getNamespacesInScope()
Get an iterator that returns all namespaces in scope for this element.
|
String |
getText()
Returns the non-empty text children as a string.
|
QName |
getTextAsQName()
Resolve the content of this element to a
QName. |
Reader |
getTextAsStream(boolean cache)
Returns a stream representing the concatenation of the text nodes that are children of a
this element.
|
void |
removeAttribute(OMAttribute attr)
Removes the given attribute from this element.
|
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)
Serialize the node with caching enabled.
|
void |
serialize(OutputStream output,
OMOutputFormat format)
Serialize the node with caching enabled.
|
void |
serialize(Writer writer)
Serialize the node with caching enabled.
|
void |
serialize(Writer writer,
OMOutputFormat format)
Serialize the node with caching enabled.
|
void |
serializeAndConsume(OutputStream output)
Serialize the node without caching.
|
void |
serializeAndConsume(OutputStream output,
OMOutputFormat format)
Serialize the node without caching.
|
void |
serializeAndConsume(Writer writer)
Serialize the node without caching.
|
void |
serializeAndConsume(Writer writer,
OMOutputFormat format)
Serialize the node without caching.
|
void |
setLineNumber(int lineNumber) |
void |
setNamespace(OMNamespace namespace)
Set the namespace for this element.
|
void |
setNamespaceWithNoFindInCurrentScope(OMNamespace namespace)
Deprecated.
|
void |
setText(QName qname)
Set the content of this element to the given
QName. |
void |
setText(String text)
Set the content of this element to the given text.
|
String |
toString()
Convenience method to serialize the element to a string with caching enabled.
|
String |
toStringWithConsume()
Convenience method to serialize the element to a string without caching.
|
void |
undeclarePrefix(String prefix)
Add a namespace declaration that undeclares a given prefix.
|
void |
writeTextTo(Writer out,
boolean cache)
Write the content of the text nodes that are children of a given element to a
Writer. |
buildWithAttachments, detach, discard, getNextOMSibling, getParent, getPreviousOMSibling, getType, insertSiblingAfter, insertSiblingBeforeaddChild, getBuilder, getChildren, getChildrenWithLocalName, getChildrenWithName, getChildrenWithNamespaceURI, getDescendants, getFirstChildWithName, getFirstOMChild, getSAXResult, getSAXSource, getXMLStreamReader, getXMLStreamReader, getXMLStreamReader, getXMLStreamReaderWithoutCaching, removeChildrenbuild, close, isComplete, serialize, serialize, serializeAndConsumeclone, getOMFactorygetLocalName, getNamespace, getNamespaceURI, getPrefix, getQName, hasName, setLocalName, setNamespaceIterator getChildElements()
OMContainer.getChildren(),
OMContainer.getChildrenWithName(javax.xml.namespace.QName)OMNamespace declareNamespace(String uri, String prefix)
Note that this method can't be used to declare a default namespace. For that purpose use
declareDefaultNamespace(String) or declareNamespace(OMNamespace).
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 null or the empty string is
given, a prefix will be auto-generated. Please note that using the empty string
for this purpose is deprecated and will no longer be supported in Axiom 1.3.IllegalArgumentException - if an attempt is made to bind a prefix to the empty namespace namedeclareNamespace(OMNamespace),
findNamespace(String, String),
getAllDeclaredNamespaces()OMNamespace declareDefaultNamespace(String uri)
Note that this method will never change the namespace of the element itself. If an attempt is made to add a namespace declaration that conflicts with the namespace information of the element, an exception is thrown.
uri - The default namespace to declare in the current scope. The caller is expected to
ensure that the URI is a valid namespace name.OMException - if an attempt is made to add a conflicting namespace declarationOMNamespace getDefaultNamespace()
null if no default namespace is in scope. This
method never returns an OMNamespace object with an empty namespace URI; if
the element or one of its ancestors has a xmlns="" declaration, then
null is returned. Note that if the method returns an OMNamespace
object, then its prefix will obviously be the empty string.OMNamespace declareNamespace(OMNamespace namespace)
namespace - The namespace to declare. If the prefix specified by the OMNamespace
object is null, then a prefix will be generated.OMNamespace object passed
as parameter, except if the prefix was null, in which case the return
value contains the generated prefix.IllegalArgumentException - if an attempt is made to bind a prefix to the empty namespace namedeclareNamespace(String, String),
findNamespace(String, String),
getAllDeclaredNamespaces()void undeclarePrefix(String prefix)
A namespace declaration with empty namespace name will be added even if no existing namespace declaration for the given prefix is in scope in the context of the current element. If a namespace declaration for the given prefix is already defined on this element, it will be replaced.
The namespace declaration created by this method will be returned by
getAllDeclaredNamespaces(). It is represented as an OMNamespace object for
which OMNamespace.getNamespaceURI() returns an empty string.
prefix - the prefix to undeclareOMNamespace findNamespace(String uri, String prefix)
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.
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.declareNamespace(String, String),
declareNamespace(OMNamespace),
getAllDeclaredNamespaces()OMNamespace findNamespaceURI(String prefix)
prefix - Iterator getAllDeclaredNamespaces()
getNamespacesInScope() or getNamespaceContext(boolean) to calculate the
namespace context for the element.
findNamespace(String, String) and findNamespaceURI(String) to resolve a
namespace prefix or to find a namespace prefix for a given URI.
resolveQName(String) to resolve a QName literal.
AXIOMXPath.AXIOMXPath(OMElement, String) or
AXIOMXPath.AXIOMXPath(OMAttribute) to create an XPath expression using the namespace
context of a given element.
It is expected that applications only rarely use getAllDeclaredNamespaces()
directly.
The iterator returned by this method supports Iterator.remove() and that method can
be used to remove a namespace declaration from this element.
OMNamespace items declared on this element. If the
element has no namespace declarations, an empty iterator is returned.
Note that the returned iterator may be invalidated by a call to
declareNamespace(OMNamespace), declareNamespace(String, String),
declareDefaultNamespace(String) or any other method that modifies the
namespace declarations of this element.
Iterator getNamespacesInScope()
OMNamespace object with that prefix, and this object specifies
the namespace URI bound to the prefix. The iterator returns an OMNamespace object
with an empty prefix if and only if there is a default namespace. It will never return an
OMNamespace object with both the prefix and the namespace URI set to the empty
string, even if the element or one of its ancestors has a namespace declaration of the form
xmlns="".
The order in which the iterator returns the namespaces is undefined, and invoking the
Iterator.remove() method on the returned iterator is not supported. The iterator may
be a "live" object, which means that results are undefined if the document is modified (in a
way that would modify the namespace context for the element) while the iterator is in use.
NamespaceContext getNamespaceContext(boolean detached)
The method supports two different NamespaceContext implementation variants:
NamespaceContext.
Typically, creating a live NamespaceContext is cheaper, but the lookup performance of
a detached NamespaceContext is better. The detached variant should always be used if
the reference to the NamespaceContext is kept longer than the object model itself,
because in this case a live NamespaceContext would prevent the object model from
being garbage collected.
detached - true if the method should return a detached implementation,
false if the method should return a live objectIterator getAllAttributes()
Note that the iterator returned by this function will be invalidated by any addAttribute call.
OMAttribute items associated with the element. If the
element has no attributes, an empty iterator is returned.getAttribute(javax.xml.namespace.QName),
addAttribute(OMAttribute),
addAttribute(String, String, OMNamespace)OMAttribute getAttribute(QName qname)
qname - the qualified name to search forString getAttributeValue(QName qname)
qname - the qualified name to search fornull if no matching attribute is found.OMAttribute addAttribute(OMAttribute attr)
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.
attr - The attribute to add.attr, depending on whether the attribute specified
by this parameter already has an owner or not.OMAttribute addAttribute(String localName, String value, OMNamespace ns)
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.
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 for the attribute. If no corresponding namespace declaration is in
scope, then a new namespace declaration will be added to the element. The
OMNamespace may have a null prefix, in which case the method
will generate a prefix (if no namespace declaration for the given namespace URI is
in scope) or use an existing one.IllegalArgumentException - if an attempt is made to create a prefixed attribute with an empty namespace name
or an unprefixed attribute with a namespacevoid removeAttribute(OMAttribute attr)
attr - the attribute to removeOMException - if the attribute is not owned by this elementOMElement getFirstElement()
void setText(String text)
OMText after the method
returns. If the parameter is null or an empty string, then the element will have
no children.text - the new text content for the elementvoid setText(QName qname)
QName. If no matching namespace
declaration for the QName is in scope, then this method will add one. If the
QName specifies a namespace URI but no prefix, then a prefix will be generated. If
the element has children, then all these children are detached before the content is set. If
the parameter is not null, then the element will have a single child of type
OMText after the method returns. If the parameter is null, then the
element will have no children.qname - the QName valueString getText()
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.
Reader getTextAsStream(boolean cache)
new StringReader(element.getText())
The difference is that the stream implementation returned by this method is optimized for performance and is guaranteed to have constant memory usage, provided that:
OMElement, i.e.
cache is false or the element is an OMSourcedElement that
is backed by a non destructive OMDataSource.
XMLStreamReader in
the case of an OMSourcedElement) is non coalescing. Note that this is not the default
in Axiom and it may be necessary to configure the parser with
StAXParserConfiguration.NON_COALESCING.
When this method is used with cache set to false the caller must close the
returned stream before attempting to access other nodes in the tree.
cache - whether to enable caching when accessing the elementgetText()void writeTextTo(Writer out, boolean cache) throws IOException
Writer.
If cache is true, this method has the same effect as the following instruction:
out.write(element.getText())
The difference is that this method is guaranteed to have constant memory usage and is
optimized for performance (with the same restrictions that apply to
getTextAsStream(boolean)).
The method does not call Writer.close().
out - the stream to write the content tocache - whether to enable caching when accessing the elementOMException - if an error occurs when reading from the elementIOException - if an error occurs when writing to the streamgetText()QName getTextAsQName()
QName. The QName is interpreted in a way
that is compatible with the XML schema specification. In particular, surrounding whitespace
is ignored.null if the element is empty or the QName could
not be resolvedvoid setNamespace(OMNamespace namespace)
This method has the same effect as
OMNamedInformationItem.setNamespace(OMNamespace, boolean) with declare
set to true.
namespace - The new namespace for this element, or null to remove the namespace
from this element. If an OMNamespace instance with a null
prefix is given, then a prefix will be generated automatically. In this case, the
generated prefix can be determined using OMNamedInformationItem.getNamespace().IllegalArgumentException - if an attempt is made to bind a prefix to the empty namespace namevoid setNamespaceWithNoFindInCurrentScope(OMNamespace namespace)
OMNamedInformationItem.setNamespace(OMNamespace, boolean) with
declare set to false.String toString()
This method produces the same result as OMContainer.serialize(Writer). In particular,
the element is always serialized as plain XML and OMText nodes containing optimized
binary data are always inlined using base64 encoding. Since the output is accumulated into a
single string object, this may result in high memory consumption. Therefore this method
should be used with care.
String toStringWithConsume() throws XMLStreamException
As for toString(), this method may cause high memory consumption for object model
trees containing optimized binary data and should therefore be used with care.
XMLStreamExceptionQName resolveQName(String qname)
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.qname - the QName literal to resolveQName object, or null if the QName can't be resolved, i.e.
if the prefix is not bound in the namespace context of this elementOMElement cloneOMElement()
OMInformationItem.clone(OMCloneOptions) with default options.void setLineNumber(int lineNumber)
int getLineNumber()
void serialize(OutputStream output) throws XMLStreamException
This method will always serialize the infoset as plain XML. In particular, any OMText
containing optimized binary will be inlined using base64 encoding.
serialize in interface OMContainerserialize in interface OMNodeoutput - the byte stream to write the serialized infoset toXMLStreamExceptionvoid serialize(Writer writer) throws XMLStreamException
This method will always serialize the infoset as plain XML. In particular, any OMText
containing optimized binary will be inlined using base64 encoding.
serialize in interface OMContainerserialize in interface OMNodewriter - the character stream to write the serialized infoset toXMLStreamExceptionvoid serialize(OutputStream output, OMOutputFormat format) throws XMLStreamException
The format of the output is controlled by the provided OMOutputFormat object. In
particular, OMOutputFormat.setDoOptimize(boolean) can be used to instruct this method
to produce an XOP/MTOM encoded MIME message.
serialize in interface OMContainerserialize in interface OMNodeoutput - the byte stream to write the serialized infoset toformat - the output format to useXMLStreamExceptionvoid serialize(Writer writer, OMOutputFormat format) throws XMLStreamException
serialize in interface OMContainerserialize in interface OMNodewriter - the character stream to write the serialized infoset toformat - the output format to useXMLStreamExceptionvoid serializeAndConsume(OutputStream output) throws XMLStreamException
This method will always serialize the infoset as plain XML. In particular, any OMText
containing optimized binary will be inlined using base64 encoding.
serializeAndConsume in interface OMContainerserializeAndConsume in interface OMNodeoutput - the byte stream to write the serialized infoset toXMLStreamExceptionvoid serializeAndConsume(Writer writer) throws XMLStreamException
This method will always serialize the infoset as plain XML. In particular, any OMText
containing optimized binary will be inlined using base64 encoding.
serializeAndConsume in interface OMContainerserializeAndConsume in interface OMNodewriter - the character stream to write the serialized infoset toXMLStreamExceptionvoid serializeAndConsume(OutputStream output, OMOutputFormat format) throws XMLStreamException
The format of the output is controlled by the provided OMOutputFormat object. In
particular, OMOutputFormat.setDoOptimize(boolean) can be used to instruct this method
to produce an XOP/MTOM encoded MIME message.
serializeAndConsume in interface OMContainerserializeAndConsume in interface OMNodeoutput - the byte stream to write the serialized infoset toformat - the output format to useXMLStreamExceptionvoid serializeAndConsume(Writer writer, OMOutputFormat format) throws XMLStreamException
serializeAndConsume in interface OMContainerserializeAndConsume in interface OMNodewriter - the character stream to write the serialized infoset toformat - the output format to useXMLStreamExceptionCopyright © The Apache Software Foundation. All Rights Reserved.