public interface OMElement extends OMNode, OMContainer
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
OMAttribute.setOMNamespace(OMNamespace)
. [TODO: this is currently not entirely true; see
WSCOMMONS-517]
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.
|
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.
|
buildWithAttachments, detach, discard, getNextOMSibling, getParent, getPreviousOMSibling, getType, insertSiblingAfter, insertSiblingBefore
addChild, buildNext, getBuilder, getChildren, getChildrenWithLocalName, getChildrenWithName, getChildrenWithNamespaceURI, getFirstChildWithName, getFirstOMChild, getXMLStreamReader, getXMLStreamReader, getXMLStreamReaderWithoutCaching
build, close, getOMFactory, isComplete, serialize, serialize, serializeAndConsume
Iterator getChildElements()
OMContainer.getChildren()
,
OMContainer.getChildrenWithName(javax.xml.namespace.QName)
OMNamespace declareNamespace(String uri, String prefix)
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.declareNamespace(OMNamespace)
,
findNamespace(String, String)
,
getAllDeclaredNamespaces()
OMNamespace declareDefaultNamespace(String uri)
uri
- OMNamespace getDefaultNamespace()
OMNamespace declareNamespace(OMNamespace namespace)
namespace
- The namespace to declare.declareNamespace(String, String)
,
findNamespace(String, String)
,
getAllDeclaredNamespaces()
OMNamespace 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() throws OMException
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.
OMNamespace
items declared on the current
element.OMException
findNamespace(String, String)
,
declareNamespace(String, String)
,
declareNamespace(OMNamespace)
Iterator getAllAttributes()
Note that the iterator returned by this function will be invalidated by any addAttribute call.
Iterator
of OMAttribute
items associated with the
element.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 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.void removeAttribute(OMAttribute attr)
attr
- void setBuilder(OMXMLParserWrapper wrapper)
wrapper
- void setFirstChild(OMNode node)
node
- OMElement getFirstElement()
void setText(String text)
text
- void setText(QName qname)
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.
QName getTextAsQName()
String getLocalName()
void setLocalName(String localName)
localName
- OMNamespace getNamespace()
null
if the element has no namespaceString getNamespaceURI()
Node.getNamespaceURI()
(when called on an
Element
).null
if the element has no namespacevoid setNamespace(OMNamespace namespace)
namespace
- void setNamespaceWithNoFindInCurrentScope(OMNamespace namespace)
namespace
- String toString()
String toStringWithConsume() throws javax.xml.stream.XMLStreamException
QName 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()
void setLineNumber(int lineNumber)
int getLineNumber()
void serialize(OutputStream output) throws javax.xml.stream.XMLStreamException
serialize
in interface OMContainer
serialize
in interface OMNode
output
- javax.xml.stream.XMLStreamException
void serialize(Writer writer) throws javax.xml.stream.XMLStreamException
serialize
in interface OMContainer
serialize
in interface OMNode
writer
- javax.xml.stream.XMLStreamException
void serialize(OutputStream output, OMOutputFormat format) throws javax.xml.stream.XMLStreamException
serialize
in interface OMContainer
serialize
in interface OMNode
output
- format
- javax.xml.stream.XMLStreamException
void serialize(Writer writer, OMOutputFormat format) throws javax.xml.stream.XMLStreamException
serialize
in interface OMContainer
serialize
in interface OMNode
writer
- format
- javax.xml.stream.XMLStreamException
void serializeAndConsume(OutputStream output) throws javax.xml.stream.XMLStreamException
serializeAndConsume
in interface OMContainer
serializeAndConsume
in interface OMNode
output
- javax.xml.stream.XMLStreamException
void serializeAndConsume(Writer writer) throws javax.xml.stream.XMLStreamException
serializeAndConsume
in interface OMContainer
serializeAndConsume
in interface OMNode
writer
- javax.xml.stream.XMLStreamException
void serializeAndConsume(OutputStream output, OMOutputFormat format) throws javax.xml.stream.XMLStreamException
serializeAndConsume
in interface OMContainer
serializeAndConsume
in interface OMNode
output
- format
- javax.xml.stream.XMLStreamException
void serializeAndConsume(Writer writer, OMOutputFormat format) throws javax.xml.stream.XMLStreamException
serializeAndConsume
in interface OMContainer
serializeAndConsume
in interface OMNode
writer
- format
- javax.xml.stream.XMLStreamException
Copyright © 2004-2013 The Apache Software Foundation. All Rights Reserved.