This class implements a DTM that tends to be optimized more for speed than
for compactness, that is constructed via SAX2 ContentHandler events.
attributeDecl
public void attributeDecl(String eName,
String aName,
String type,
String valueDefault,
String value)
throws SAXException
Report an attribute type declaration.
Only the effective (first) declaration for an attribute will
be reported. The type will be one of the strings "CDATA",
"ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY",
"ENTITIES", or "NOTATION", or a parenthesized token group with
the separator "|" and all whitespace removed.
eName
- The name of the associated element.aName
- The name of the attribute.type
- A string representing the attribute type.valueDefault
- A string representing the attribute default
("#IMPLIED", "#REQUIRED", or "#FIXED") or null if
none of these applies.value
- A string representing the attribute's default value,
or null if there is none.
characters
public void characters(ch[] ,
int start,
int length)
throws SAXException
Receive notification of character data inside an element.
By default, do nothing. Application writers may override this
method to take specific actions for each chunk of character data
(such as adding the data to a node or buffer, or printing it to
a file).
start
- The start position in the character array.length
- The number of characters to use from the
character array.
org.xml.sax.ContentHandler.characters
clearCoRoutine
public void clearCoRoutine()
Ask the CoRoutine parser to doTerminate and clear the reference.
clearCoRoutine
public void clearCoRoutine(boolean callDoTerminate)
Ask the CoRoutine parser to doTerminate and clear the reference. If
the CoRoutine parser has already been cleared, this will have no effect.
callDoTerminate
- true of doTerminate should be called on the
coRoutine parser.
comment
public void comment(ch[] ,
int start,
int length)
throws SAXException
Report an XML comment anywhere in the document.
This callback will be used for comments inside or outside the
document element, including comments in the external DTD
subset (if read).
start
- The starting position in the array.length
- The number of characters to use from the array.
dispatchCharactersEvents
public void dispatchCharactersEvents(int nodeHandle,
ContentHandler ch,
boolean normalize)
throws SAXException
Directly call the
characters method on the passed ContentHandler for the
string-value of the given node (see http://www.w3.org/TR/xpath#data-model
for the definition of a node's string-value). Multiple calls to the
ContentHandler's characters methods may well occur for a single call to
this method.
nodeHandle
- The node ID.ch
- A non-null reference to a ContentHandler.normalize
- true if the content should be normalized according to
the rules for the XPath
normalize-space
function.
dispatchToEvents
public void dispatchToEvents(int nodeHandle,
org.xml.sax.ContentHandler ch)
throws org.xml.sax.SAXException
Directly create SAX parser events from a subtree.
- dispatchToEvents in interface DTM
- dispatchToEvents in interface DTMDefaultBase
nodeHandle
- The node ID.ch
- A non-null reference to a ContentHandler.
elementDecl
public void elementDecl(String name,
String model)
throws SAXException
Report an element type declaration.
The content model will consist of the string "EMPTY", the
string "ANY", or a parenthesised group, optionally followed
by an occurrence indicator. The model will be normalized so
that all whitespace is removed,and will include the enclosing
parentheses.
name
- The element type name.model
- The content model as a normalized string.
endCDATA
public void endCDATA()
throws SAXException
Report the end of a CDATA section.
endDTD
public void endDTD()
throws SAXException
Report the end of DTD declarations.
endDocument
public void endDocument()
throws SAXException
Receive notification of the end of the document.
org.xml.sax.ContentHandler.endDocument
endElement
public void endElement(String uri,
String localName,
String qName)
throws SAXException
Receive notification of the end of an element.
By default, do nothing. Application writers may override this
method in a subclass to take specific actions at the end of
each element (such as finalising a tree node or writing
output to a file).
uri
- The Namespace URI, or the empty string if the
element has no Namespace URI or if Namespace
processing is not being performed.localName
- The local name (without prefix), or the
empty string if Namespace processing is not being
performed.qName
- The qualified XML 1.0 name (with prefix), or the
empty string if qualified names are not available.
org.xml.sax.ContentHandler.endElement
endEntity
public void endEntity(String name)
throws SAXException
Report the end of an entity.
name
- The name of the entity that is ending.
endPrefixMapping
public void endPrefixMapping(String prefix)
throws SAXException
Receive notification of the end of a Namespace mapping.
By default, do nothing. Application writers may override this
method in a subclass to take specific actions at the end of
each prefix mapping.
prefix
- The Namespace prefix being declared.
org.xml.sax.ContentHandler.endPrefixMapping
error
public void error(SAXParseException e)
throws SAXException
Receive notification of a recoverable parser error.
The default implementation does nothing. Application writers
may override this method in a subclass to take specific actions
for each error, such as inserting the message in a log file or
printing it to the console.
e
- The warning information encoded as an exception.
org.xml.sax.ErrorHandler.warning
, org.xml.sax.SAXParseException
externalEntityDecl
public void externalEntityDecl(String name,
String publicId,
String systemId)
throws SAXException
Report a parsed external entity declaration.
Only the effective (first) declaration for each entity
will be reported.
name
- The name of the entity. If it is a parameter
entity, the name will begin with '%'.publicId
- The declared public identifier of the entity, or
null if none was declared.systemId
- The declared system identifier of the entity.
fatalError
public void fatalError(SAXParseException e)
throws SAXException
Report a fatal XML parsing error.
The default implementation throws a SAXParseException.
Application writers may override this method in a subclass if
they need to take specific actions for each fatal error (such as
collecting all of the errors into a single report): in any case,
the application must stop all regular processing when this
method is invoked, since the document is no longer reliable, and
the parser may no longer report parsing events.
e
- The error information encoded as an exception.
org.xml.sax.ErrorHandler.fatalError
, org.xml.sax.SAXParseException
getAttributeNode
public int getAttributeNode(int nodeHandle,
String namespaceURI,
String name)
Retrieves an attribute node by by qualified name and namespace URI.
- getAttributeNode in interface DTM
- getAttributeNode in interface DTMDefaultBase
nodeHandle
- int Handle of the node upon which to look up this attribute..namespaceURI
- The namespace URI of the attribute to
retrieve, or null.name
- The local name of the attribute to
retrieve.
- The attribute node handle with the specified name (
nodeName
) or DTM.NULL
if there is no such
attribute.
getContentHandler
public ContentHandler getContentHandler()
getContentHandler returns "our SAX builder" -- the thing that
someone else should send SAX events to in order to extend this
DTM model.
%REVIEW% Should this return null if constrution already done/begun?
- getContentHandler in interface DTM
- null if this model doesn't respond to SAX events,
"this" if the DTM object has a built-in SAX ContentHandler,
the IncrementalSAXSource if we're bound to one and should receive
the SAX stream via it for incremental build purposes...
getDTDHandler
public DTDHandler getDTDHandler()
Return this DTM's DTDHandler.
- getDTDHandler in interface DTM
- null if this model doesn't respond to SAX dtd events.
getDeclHandler
public DeclHandler getDeclHandler()
Return this DTM's DeclHandler.
- getDeclHandler in interface DTM
- null if this model doesn't respond to SAX Decl events.
getElementById
public int getElementById(String elementId)
Returns the
Element
whose
ID
is given by
elementId
. If no such element exists, returns
DTM.NULL
. Behavior is not defined if more than one element
has this
ID
. Attributes (including those
with the name "ID") are not of type ID unless so defined by DTD/Schema
information available to the DTM implementation.
Implementations that do not know whether attributes are of type ID or
not are expected to return
DTM.NULL
.
%REVIEW% Presumably IDs are still scoped to a single document,
and this operation searches only within a single document, right?
Wouldn't want collisions between DTMs in the same process.
- getElementById in interface DTM
- getElementById in interface DTMDefaultBase
elementId
- The unique id
value for an element.
- The handle of the matching element.
getEntityResolver
public EntityResolver getEntityResolver()
Return this DTM's EntityResolver.
- getEntityResolver in interface DTM
- null if this model doesn't respond to SAX entity ref events.
getErrorHandler
public ErrorHandler getErrorHandler()
Return this DTM's ErrorHandler.
- getErrorHandler in interface DTM
- null if this model doesn't respond to SAX error events.
getFixedNames
public String getFixedNames(int type)
getIdForNamespace
public int getIdForNamespace(String uri)
Get a prefix either from the uri mapping, or just make
one up!
uri
- The namespace URI, which may be null.
- The prefix if there is one, or null.
getLexicalHandler
public LexicalHandler getLexicalHandler()
Return this DTM's lexical handler.
%REVIEW% Should this return null if constrution already done/begun?
- getLexicalHandler in interface DTM
- null if this model doesn't respond to lexical SAX events,
"this" if the DTM object has a built-in SAX ContentHandler,
the IncrementalSAXSource if we're bound to one and should receive
the SAX stream via it for incremental build purposes...
getLocalName
public String getLocalName(int nodeHandle)
Given a node handle, return its XPath-style localname.
(As defined in Namespaces, this is the portion of the name after any
colon character).
- getLocalName in interface DTM
- getLocalName in interface DTMDefaultBase
nodeHandle
- the id of the node.
- String Local name of this node.
getNamespaceURI
public String getNamespaceURI(String prefix)
Get a prefix either from the qname or from the uri mapping, or just make
one up!
- The prefix if there is one, or null.
getNamespaceURI
public String getNamespaceURI(int nodeHandle)
Given a node handle, return its DOM-style namespace URI
(As defined in Namespaces, this is the declared URI which this node's
prefix -- or default in lieu thereof -- was mapped to.)
%REVIEW% Null or ""? -sb
- getNamespaceURI in interface DTM
- getNamespaceURI in interface DTMDefaultBase
nodeHandle
- the id of the node.
- String URI value of this node's namespace, or null if no
namespace was resolved.
getNodeName
public String getNodeName(int nodeHandle)
Given a node handle, return its DOM-style node name. This will
include names such as #text or #document.
- getNodeName in interface DTM
- getNodeName in interface DTMDefaultBase
nodeHandle
- the id of the node.
- String Name of this node, which may be an empty string.
%REVIEW% Document when empty string is possible...
%REVIEW-COMMENT% It should never be empty, should it?
getNodeNameX
public String getNodeNameX(int nodeHandle)
Given a node handle, return the XPath node name. This should be
the name as described by the XPath data model, NOT the DOM-style
name.
- getNodeNameX in interface DTM
- getNodeNameX in interface DTMDefaultBase
nodeHandle
- the id of the node.
- String Name of this node, which may be an empty string.
getNodeValue
public String getNodeValue(int nodeHandle)
Given a node handle, return its node value. This is mostly
as defined by the DOM, but may ignore some conveniences.
- getNodeValue in interface DTM
- getNodeValue in interface DTMDefaultBase
nodeHandle
- The node id.
- String Value of this node, or null if not
meaningful for this node type.
getNumberOfNodes
public int getNumberOfNodes()
Get the number of nodes that have been added.
- The number of that are currently in the tree.
getPrefix
public String getPrefix(String qname,
String uri)
Get a prefix either from the qname or from the uri mapping, or just make
one up!
qname
- The qualified name, which may be null.uri
- The namespace URI, which may be null.
- The prefix if there is one, or null.
getPrefix
public String getPrefix(int nodeHandle)
Given a namespace handle, return the prefix that the namespace decl is
mapping.
Given a node handle, return the prefix used to map to the namespace.
%REVIEW% Are you sure you want "" for no prefix?
%REVIEW-COMMENT% I think so... not totally sure. -sb
- getPrefix in interface DTM
- getPrefix in interface DTMDefaultBase
nodeHandle
- the id of the node.
- String prefix of this node's name, or "" if no explicit
namespace prefix was given.
getSourceLocatorFor
public SourceLocator getSourceLocatorFor(int node)
Retrieve the SourceLocator associated with a specific node.
This is only meaningful if the XalanProperties.SOURCE_LOCATION flag was
set True using setProperty; if it was never set, or was set false, we
will return null.
(We _could_ return a locator with the document's base URI and bogus
line/column information. Trying that; see the else clause.)
- getSourceLocatorFor in interface DTM
getStringValue
public XMLString getStringValue(int nodeHandle)
Get the string-value of a node as a String object
(see http://www.w3.org/TR/xpath#data-model
for the definition of a node's string-value).
- getStringValue in interface DTM
- getStringValue in interface DTMDefaultBase
nodeHandle
- The node ID.
- A string object that represents the string-value of the given node.
getUnparsedEntityURI
public String getUnparsedEntityURI(String name)
The getUnparsedEntityURI function returns the URI of the unparsed
entity with the specified name in the same document as the context
node (see [3.3 Unparsed Entities]). It returns the empty string if
there is no such entity.
XML processors may choose to use the System Identifier (if one
is provided) to resolve the entity, rather than the URI in the
Public Identifier. The details are dependent on the processor, and
we would have to support some form of plug-in resolver to handle
this properly. Currently, we simply return the System Identifier if
present, and hope that it a usable URI or that our caller can
map it to one.
TODO: Resolve Public Identifiers... or consider changing function name.
If we find a relative URI
reference, XML expects it to be resolved in terms of the base URI
of the document. The DOM doesn't do that for us, and it isn't
entirely clear whether that should be done here; currently that's
pushed up to a higher level of our application. (Note that DOM Level
1 didn't store the document's base URI.)
TODO: Consider resolving Relative URIs.
(The DOM's statement that "An XML processor may choose to
completely expand entities before the structure model is passed
to the DOM" refers only to parsed entities, not unparsed, and hence
doesn't affect this function.)
- getUnparsedEntityURI in interface DTM
- getUnparsedEntityURI in interface DTMDefaultBase
name
- A string containing the Entity Name of the unparsed
entity.
- String containing the URI of the Unparsed Entity, or an
empty string if no such entity exists.
ignorableWhitespace
public void ignorableWhitespace(ch[] ,
int start,
int length)
throws SAXException
Receive notification of ignorable whitespace in element content.
By default, do nothing. Application writers may override this
method to take specific actions for each chunk of ignorable
whitespace (such as adding data to a node or buffer, or printing
it to a file).
start
- The start position in the character array.length
- The number of characters to use from the
character array.
org.xml.sax.ContentHandler.ignorableWhitespace
internalEntityDecl
public void internalEntityDecl(String name,
String value)
throws SAXException
Report an internal entity declaration.
Only the effective (first) declaration for each entity
will be reported.
name
- The name of the entity. If it is a parameter
entity, the name will begin with '%'.value
- The replacement text of the entity.
isAttributeSpecified
public boolean isAttributeSpecified(int attributeHandle)
5. [specified] A flag indicating whether this attribute was actually
specified in the start-tag of its element, or was defaulted from the
DTD.
- isAttributeSpecified in interface DTM
- isAttributeSpecified in interface DTMDefaultBase
attributeHandle
- Must be a valid handle to an attribute node.
true
if the attribute was specified;
false
if it was defaulted.
isWhitespace
public boolean isWhitespace(int nodeHandle)
Determine if the string-value of a node is whitespace
nodeHandle
- The node Handle.
- Return true if the given node is whitespace.
migrateTo
public void migrateTo(DTMManager manager)
Migrate a DTM built with an old DTMManager to a new DTMManager.
After the migration, the new DTMManager will treat the DTM as
one that is built by itself.
This is used to support DTM sharing between multiple transformations.
- migrateTo in interface DTM
- migrateTo in interface DTMDefaultBase
needsTwoThreads
public boolean needsTwoThreads()
- needsTwoThreads in interface DTM
- true iff we're building this model incrementally (eg
we're partnered with a IncrementalSAXSource) and thus require that the
transformation and the parse run simultaneously. Guidance to the
DTMManager.
notationDecl
public void notationDecl(String name,
String publicId,
String systemId)
throws SAXException
Receive notification of a notation declaration.
By default, do nothing. Application writers may override this
method in a subclass if they wish to keep track of the notations
declared in a document.
name
- The notation name.publicId
- The notation public identifier, or null if not
available.systemId
- The notation system identifier.
org.xml.sax.DTDHandler.notationDecl
processingInstruction
public void processingInstruction(String target,
String data)
throws SAXException
Receive notification of a processing instruction.
By default, do nothing. Application writers may override this
method in a subclass to take specific actions for each
processing instruction, such as setting status variables or
invoking other methods.
target
- The processing instruction target.data
- The processing instruction data, or null if
none is supplied.
org.xml.sax.ContentHandler.processingInstruction
resolveEntity
public InputSource resolveEntity(String publicId,
String systemId)
throws SAXException
Resolve an external entity.
Always return null, so that the parser will use the system
identifier provided in the XML document. This method implements
the SAX default behaviour: application writers can override it
in a subclass to do special translations such as catalog lookups
or URI redirection.
publicId
- The public identifer, or null if none is
available.systemId
- The system identifier provided in the XML
document.
- The new input source, or null to require the
default behaviour.
org.xml.sax.EntityResolver.resolveEntity
setDocumentLocator
public void setDocumentLocator(Locator locator)
Receive a Locator object for document events.
By default, do nothing. Application writers may override this
method in a subclass if they wish to store the locator for use
with other document events.
locator
- A locator for all SAX document events.
org.xml.sax.ContentHandler.setDocumentLocator
, org.xml.sax.Locator
setIDAttribute
public void setIDAttribute(String id,
int elem)
Set an ID string to node association in the ID table.
id
- The ID string.elem
- The associated element handle.
setIncrementalSAXSource
public void setIncrementalSAXSource(IncrementalSAXSource incrementalSAXSource)
Bind a IncrementalSAXSource to this DTM. If we discover we need nodes
that have not yet been built, we will ask this object to send us more
events, and it will manage interactions with its data sources.
Note that we do not actually build the IncrementalSAXSource, since we don't
know what source it's reading from, what thread that source will run in,
or when it will run.
incrementalSAXSource
- The parser that we want to recieve events from
on demand.
setProperty
public void setProperty(String property,
Object value)
Set a run time property for this DTM instance.
%REVIEW% Now that we no longer use this method to support
getSourceLocatorFor, can we remove it?
- setProperty in interface DTM
property
- a String
valuevalue
- an Object
value
setUseSourceLocation
public void setUseSourceLocation(boolean useSourceLocation)
Set whether information about document source location
should be maintained or not.
skippedEntity
public void skippedEntity(String name)
throws SAXException
Receive notification of a skipped entity.
By default, do nothing. Application writers may override this
method in a subclass to take specific actions for each
processing instruction, such as setting status variables or
invoking other methods.
name
- The name of the skipped entity.
org.xml.sax.ContentHandler.processingInstruction
startCDATA
public void startCDATA()
throws SAXException
Report the start of a CDATA section.
The contents of the CDATA section will be reported through
the regular
characters
event.
startDTD
public void startDTD(String name,
String publicId,
String systemId)
throws SAXException
Report the start of DTD declarations, if any.
Any declarations are assumed to be in the internal subset
unless otherwise indicated by a
startEntity
event.
Note that the start/endDTD events will appear within
the start/endDocument events from ContentHandler and
before the first startElement event.
name
- The document type name.publicId
- The declared public identifier for the
external DTD subset, or null if none was declared.systemId
- The declared system identifier for the
external DTD subset, or null if none was declared.
startDocument
public void startDocument()
throws SAXException
Receive notification of the beginning of the document.
org.xml.sax.ContentHandler.startDocument
startElement
public void startElement(String uri,
String localName,
String qName,
Attributes attributes)
throws SAXException
Receive notification of the start of an element.
By default, do nothing. Application writers may override this
method in a subclass to take specific actions at the start of
each element (such as allocating a new tree node or writing
output to a file).
uri
- The Namespace URI, or the empty string if the
element has no Namespace URI or if Namespace
processing is not being performed.localName
- The local name (without prefix), or the
empty string if Namespace processing is not being
performed.qName
- The qualified name (with prefix), or the
empty string if qualified names are not available.attributes
- The specified or defaulted attributes.
org.xml.sax.ContentHandler.startElement
startEntity
public void startEntity(String name)
throws SAXException
Report the beginning of an entity in content.
NOTE: entity references in attribute
values -- and the start and end of the document entity --
are never reported.
The start and end of the external DTD subset are reported
using the pseudo-name "[dtd]". All other events must be
properly nested within start/end entity events.
Note that skipped entities will be reported through the
skippedEntity
event, which is part of the ContentHandler interface.
name
- The name of the entity. If it is a parameter
entity, the name will begin with '%'.
endEntity(String)
, org.xml.sax.ext.DeclHandler.internalEntityDecl
, org.xml.sax.ext.DeclHandler.externalEntityDecl
startPrefixMapping
public void startPrefixMapping(String prefix,
String uri)
throws SAXException
Receive notification of the start of a Namespace mapping.
By default, do nothing. Application writers may override this
method in a subclass to take specific actions at the start of
each Namespace prefix scope (such as storing the prefix mapping).
prefix
- The Namespace prefix being declared.uri
- The Namespace URI mapped to the prefix.
org.xml.sax.ContentHandler.startPrefixMapping
unparsedEntityDecl
public void unparsedEntityDecl(String name,
String publicId,
String systemId,
String notationName)
throws SAXException
Receive notification of an unparsed entity declaration.
By default, do nothing. Application writers may override this
method in a subclass to keep track of the unparsed entities
declared in a document.
name
- The entity name.publicId
- The entity public identifier, or null if not
available.systemId
- The entity system identifier.notationName
- The name of the associated notation.
org.xml.sax.DTDHandler.unparsedEntityDecl
warning
public void warning(SAXParseException e)
throws SAXException
Receive notification of a parser warning.
The default implementation does nothing. Application writers
may override this method in a subclass to take specific actions
for each warning, such as inserting the message in a log file or
printing it to the console.
e
- The warning information encoded as an exception.
org.xml.sax.ErrorHandler.warning
, org.xml.sax.SAXParseException