|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface OMElement
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:
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]
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 attributeName,
String value,
OMNamespace ns)
Adds an attribute to the current 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. |
OMXMLParserWrapper |
getBuilder()
Returns the builder object. |
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()
Get a pull parser representation of this element with caching enabled. |
XMLStreamReader |
getXMLStreamReader(boolean cache)
Get a pull parser representation of this element. |
XMLStreamReader |
getXMLStreamReaderWithoutCaching()
Get a pull parser representation of this element with caching disabled. |
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 text)
|
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.OMSerializable |
---|
build, close, getOMFactory, isComplete, serialize, serialize, serializeAndConsume |
Methods inherited from interface org.apache.axiom.om.OMContainer |
---|
addChild, buildNext, getChildren, getChildrenWithLocalName, getChildrenWithName, getChildrenWithNamespaceURI, getFirstChildWithName, getFirstOMChild |
Methods inherited from interface org.apache.axiom.om.OMSerializable |
---|
build, close, getOMFactory, isComplete, serialize, serialize, serializeAndConsume |
Method Detail |
---|
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 for
String getAttributeValue(QName qname)
qname
- the qualified name to search for
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 attributeName, String value, OMNamespace ns)
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.
attributeName
- The "local name" for the attribute.value
- The string value of the attribute.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
- OMXMLParserWrapper getBuilder()
void setFirstChild(OMNode node)
node
- OMElement getFirstElement()
XMLStreamReader getXMLStreamReader()
getXMLStreamReader(boolean)
with cache
set to
true
.
XMLStreamReader
representation of this elementXMLStreamReader getXMLStreamReaderWithoutCaching()
getXMLStreamReader(boolean)
with cache
set to
false
.
XMLStreamReader
representation of this elementXMLStreamReader getXMLStreamReader(boolean cache)
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:
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
.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.OMAttachmentAccessor
interface of the returned
reader to fetch attachments using OMAttachmentAccessor.getDataHandler(String)
. There
is no reason anymore to do so: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.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.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
).
cache
- indicates if caching should be enabled
XMLStreamReader
representation of this elementvoid setText(String text)
text
- void setText(QName text)
String 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 namespacevoid setNamespace(OMNamespace namespace)
namespace
- void setNamespaceWithNoFindInCurrentScope(OMNamespace namespace)
namespace
- QName getQName()
QName
for the element.String toString()
toString
in class Object
String toStringWithConsume() throws XMLStreamException
XMLStreamException
QName resolveQName(String qname)
qname
- prefixed qname string to resolve
OMElement cloneOMElement()
void setLineNumber(int lineNumber)
int getLineNumber()
void serialize(OutputStream output) throws XMLStreamException
serialize
in interface OMContainer
serialize
in interface OMNode
output
-
XMLStreamException
void serialize(Writer writer) throws XMLStreamException
serialize
in interface OMContainer
serialize
in interface OMNode
writer
-
XMLStreamException
void serialize(OutputStream output, OMOutputFormat format) throws XMLStreamException
serialize
in interface OMContainer
serialize
in interface OMNode
output
- format
-
XMLStreamException
void serialize(Writer writer, OMOutputFormat format) throws XMLStreamException
serialize
in interface OMContainer
serialize
in interface OMNode
writer
- format
-
XMLStreamException
void serializeAndConsume(OutputStream output) throws XMLStreamException
serializeAndConsume
in interface OMContainer
serializeAndConsume
in interface OMNode
output
-
XMLStreamException
void serializeAndConsume(Writer writer) throws XMLStreamException
serializeAndConsume
in interface OMContainer
serializeAndConsume
in interface OMNode
writer
-
XMLStreamException
void serializeAndConsume(OutputStream output, OMOutputFormat format) throws XMLStreamException
serializeAndConsume
in interface OMContainer
serializeAndConsume
in interface OMNode
output
- format
-
XMLStreamException
void serializeAndConsume(Writer writer, OMOutputFormat format) throws XMLStreamException
serializeAndConsume
in interface OMContainer
serializeAndConsume
in interface OMNode
writer
- format
-
XMLStreamException
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |