Java Doc for DTM.java in  » XML » xalan » org » apache » xml » dtm » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Nodes in the DTM are identified by integer "handles". A handle must be unique within a process, and carries both node identification and document identification. It must be possible to compare two handles (and thus their nodes) for identity with "==".

Namespace URLs, local-names, and expanded-names can all be represented by and tested as integer ID values. An expanded name represents (and may or may not directly contain) a combination of the URL ID, and the local-name ID. Note that the namespace URL id can be 0, which should have the meaning that the namespace is null. For consistancy, zero should not be used for a local-name index.

Text content of a node is represented by an index and length, permitting efficient storage such as a shared FastStringBuffer.

The model of the tree, as well as the general navigation model, is that of XPath 1.0, for the moment. The model will eventually be adapted to match the XPath 2.0 data model, XML Schema, and InfoSet.

DTM does _not_ directly support the W3C's Document Object Model. However, it attempts to come close enough that an implementation of DTM can be created that wraps a DOM and vice versa.

Please Note: The DTM API is still Subject To Change. This wouldn't affect most users, but might require updating some extensions.

The largest change being contemplated is a reconsideration of the Node Handle representation. We are still not entirely sure that an integer packed with two numeric subfields is really the best solution. It has been suggested that we move up to a Long, to permit more nodes per document without having to reduce the number of slots in the DTMManager. There's even been a proposal that we replace these integers with "cursor" objects containing the internal node id and a pointer to the actual DTM object; this might reduce the need to continuously consult the DTMManager to retrieve the latter, and might provide a useful "hook" back into normal Java heap management. But changing this datatype would have huge impact on Xalan's internals -- especially given Java's lack of C-style typedefs -- so we won't cut over unless we're convinced the new solution really would be an improvement!

%REVIEW% Generally, returning short is false economy.

%REVIEW% Are you sure you want "" for no prefix?

%REVIEW% This is obviously useful at the DOM layer, where it would permit testing this without having to create a proxy node.

%REVIEW% DTM maintains an insertion cursor which performs a depth-first tree walk as nodes come in, and this operation is really equivalent to: insertionCursor.appendChild(document.importNode(newChild))) where the insert point is the last element that was appended (or the last one popped back to by an end-element operation).

%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.

%REVIEW% Generally, returning short is false economy. Return int?

Parameters:
  nodeHandle - The node id. String Value of this node, or null if notmeaningful for this node type.

%REVIEW% Are you sure you want "" for no prefix?

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. %REVIEW% 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.) %REVIEW% 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.)
Parameters:
  name - A string containing the Entity Name of the unparsedentity. String containing the URI of the Unparsed Entity, or anempty string if no such entity exists.

%REVIEW% This is obviously useful at the DOM layer, where it would permit testing this without having to create a proxy node. It's less useful in the DTM API, where (dtm.getFirstChild(nodeHandle)!=DTM.NULL) is just as fast and almost as self-evident. But it's a convenience, and eases porting of DOM code to DTM.

If there is no declaration for the containing element, an XML processor must assume that the whitespace could be meaningful and return false. If no declaration has been read, but the [all declarations processed] property of the document information item is false (so there may be an unread declaration), then the value of this property is indeterminate for white space characters and should probably be reported as false. It is always false for text nodes that contain anything other than (or in addition to) white space.

Note too that it always returns false for non-Text nodes.

%REVIEW% Joe wants to rename this isWhitespaceInElementContent() for clarity
Parameters:
  nodeHandle - the node ID. true if the node definitely represents whitespace inelement content; false otherwise.

There are some cases where ordering isn't defined, and neither are the results of this function -- though we'll generally return true.

%REVIEW% Make sure this does the right thing with attribute nodes!!!

%REVIEW% Consider renaming for clarity. Perhaps isDocumentOrder(a,b)?
Parameters:
  firstNodeHandle - DOM Node to perform position comparison on.
Parameters:
  secondNodeHandle - DOM Node to perform position comparison on. false if secondNode comes before firstNode, otherwise return true.You can think of this as(firstNode.documentOrderPosition <= secondNode.documentOrderPosition).

%REVIEW% Do we really expect to set features on DTMs?
Parameters:
  featureId - A feature URL.
Parameters:
  state - true if this feature should be on, false otherwise.