org.apache.axiom.om
Interface OMEntityReference
- All Superinterfaces:
- OMInformationItem, OMNode, OMSerializable
public interface OMEntityReference
- extends OMNode
Represents an unexpanded entity reference in an XML document.
Different XML APIs and object models handle entity references fairly differently:
- In DOM, the way entity references in an XML document are processed depends on the setting for
expandEntityReferences
. If this
property is set to true
(default), then the parser will expand entity references and
the resulting DOM tree simply contains the nodes resulting from this expansion. If this property
is set to false
, then the parser will still expand entity references, but the
resulting DOM tree will contain EntityReference
nodes, the children of which represent
the nodes resulting from this expansion. Note that since an entity declaration may contain
markup, the children of an EntityReference
node may have a type other than
Node.TEXT_NODE
. Application code not interested in entity references will generally set
expandEntityReferences
to
true
in order to avoid the additional programming logic required to process
EntityReference
nodes.
- In SAX, the parser will always expand entity references and report the events resulting from
this expansion to the
ContentHandler
. In addition to that, if a LexicalHandler
is
registered, then the parser will report the start and end of the expansion using
LexicalHandler.startEntity(String)
and LexicalHandler.endEntity(String)
. This
means that the processing of entity references in SAX is similar to DOM with
expandEntityReferences
set to
false
. Note that in SAX there is no corresponding configuration property. This makes
sense because an application not interested in entity references can simply ignore the
LexicalHandler.startEntity(String)
and LexicalHandler.endEntity(String)
events or
not register a LexicalHandler
at all.
- In StAX, the way entity references are processed depends on the setting for the
XMLInputFactory.IS_REPLACING_ENTITY_REFERENCES
property. If this property is set to true
(default), then the parser will expand entity references and report only the events resulting
from that expansion. If the property is set to false, then the parser no longer expands entity
references. Instead, it will report each entity reference using a single
XMLStreamConstants.ENTITY_REFERENCE
event. XMLStreamReader.getText()
can then be
used to get the replacement value for the entity. Note that this replacement value may contain
unparsed markup. One can see that the way StAX reports entity references is significantly
different than DOM or SAX.
Axiom models entity references in the same way as StAX: the node corresponding to an (unexpanded)
entity reference only stores the name of the entity as well as the replacement value.
Methods inherited from interface org.apache.axiom.om.OMNode |
buildWithAttachments, detach, discard, getNextOMSibling, getParent, getPreviousOMSibling, getType, insertSiblingAfter, insertSiblingBefore, serialize, serialize, serialize, serialize, serializeAndConsume, serializeAndConsume, serializeAndConsume, serializeAndConsume |
getName
String getName()
- Get the name of the referenced entity.
- Returns:
- the name of the entity
getReplacementText
String getReplacementText()
- Get the replacement value for this entity reference. Note that the replacement value is a
simple string and may therefore contain unparsed markup.
- Returns:
- the replacement value, or
null
if the replacement value is not available
Copyright © 2004-2012 The Apache Software Foundation. All Rights Reserved.