jkesselm 01/04/26 10:39:03
Modified: java/src/org/apache/xml/dtm Tag: DTM_EXP DTM.java
DTMFilter.java DTMIterator.java DTMManager.java
Log:
These were supposed to have been moved to ..\dtm\ directory.
Their package statements say they were. I'm not sure how CVS
wound up putting them back in utils.
Revision Changes Path
No revision
No revision
1.1.2.5 +301 -57 xml-xalan/java/src/org/apache/xml/dtm/Attic/DTM.java
Index: DTM.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xml/dtm/Attic/DTM.java,v
retrieving revision 1.1.2.4
retrieving revision 1.1.2.5
diff -u -r1.1.2.4 -r1.1.2.5
--- DTM.java 2001/04/17 15:55:56 1.1.2.4
+++ DTM.java 2001/04/26 17:39:01 1.1.2.5
@@ -59,13 +59,21 @@
/**
* <code>DTM</code> is an XML document model expressed as a table rather than
* an object tree. It attempts to provide an interface to a parse tree that
- * has very little object creation.
+ * has very little object creation, and to (invisibly) support incremental
+ * construction of the model.
*
* <p>Nodes in the DTM are identified by integer "handles". A handle must
+<<<<<<< DTM.java
* be unique within a process, and identifies a specific node and its
* specific document. It must be possible to compare two handles
* for node identity with "==".</p>
+=======
+ * 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 "==".</p>
+>>>>>>> 1.2.2.10
*
+<<<<<<< DTM.java
* <p>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
@@ -73,15 +81,29 @@
* 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
* either. </p>
+=======
+ * <p>Namespace URLs, local-names, and expanded-names can all be represented
+ * by integer ID values which index into string pools stored outside the
+ * main tree structure. An expanded name is made of a combination of the
URL
+ * ID, and the local-name ID.</p>
+>>>>>>> 1.2.2.10
*
+<<<<<<< DTM.java
* <p>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.</p>
+=======
+ * <p>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.</p>
+>>>>>>> 1.2.2.10
*
- * <p>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.</p>
+ * <p>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.</p>
+ *
* <p>State: In progress!!</p>
*/
public interface DTM
@@ -142,6 +164,7 @@
*/
public static final short NOTATION_NODE = 12;
+ // Node type(s) not shared with the DOM:
/**
* The node is a <code>namespace node</code>.
*/
@@ -184,18 +207,27 @@
/**
* Given a node handle, get the handle of the node's first child.
- * If not yet resolved, waits for more nodes to be added to the document
and
- * tries again.
*
+<<<<<<< DTM.java
* @param nodeHandle int Handle of the node.
* @return int DTM node-number of first child, or DTM.NULL to indicate
none exists.
+=======
+ * @param nodeHandle int Handle of the node.
+ * @return int DTM node-number of first child,
+ * or DTM.NULL to indicate none exists.
+>>>>>>> 1.2.2.10
*/
public int getFirstChild(int nodeHandle);
+<<<<<<< DTM.java
/**
* Given a node handle, advance to its last child.
* If not yet resolved, waits for more nodes to be added to the document
and
* tries again.
+=======
+ /**
+ * Given a node handle, get the handle of the node's last child.
+>>>>>>> 1.2.2.10
*
* @param nodeHandle int Handle of the node.
* @return int Node-number of last child,
@@ -204,18 +236,23 @@
public int getLastChild(int nodeHandle);
/**
- * Retrieves an attribute node by by qualified name and namespace URI.
+ * Retrieves an attribute node by name.
+ * <br>To retrieve an attribute node by qualified name and namespace URI,
+ * use the <code>getAttributeNodeNS</code> method.
+ *
+ * <p> %REVIEW% The API described here actually _is_
+ * <code>getAttributeNodeNS</code>, since it takes a
+ * namespaceURI. Fix the function name, or fix the parameters?</p>
*
- * @param nodeHandle int Handle of the node.
- * @param namespaceURI The namespace URI of the attribute to
+ * @param name The namespace URI of the attribute to
* retrieve, or null.
- * @param name The local name of the attribute to
+ * @param name The local name of the attribute to
* retrieve.
* @return The attribute node handle with the specified name (
- * <code>nodeName</code>) or <code>DTM.NULL</code> if there is no such
+ * <code>nodeName</code>) or <code>DTM.NULL</code> if there is no such
* attribute.
*/
- public int getAttributeNode(int nodeHandle, String namespaceURI, String
name);
+ public int getAttributeNode(String namespaceURI, String name);
/**
* Given a node handle, get the index of the node's first attribute.
@@ -226,25 +263,35 @@
public int getFirstAttribute(int nodeHandle);
/**
- * Given a node handle, get the index of the node's first child.
- * If not yet resolved, waits for more nodes to be added to the document
and
- * tries again
- *
+ * Given a node handle, get the index of the node's first namespace node.
+ *
* @param nodeHandle handle to node, which should probably be an element
* node, but need not be.
*
+<<<<<<< DTM.java
* @param inScope true if all namespaces in scope should be returned,
* false if only the namespace declarations should be
* returned.
* @return handle of first namespace, or DTM.NULL to indicate none exists.
+=======
+ * @param inScope true if all namespaces in scope should be
+ * returned, false if only the node's own
+ * namespace declarations should be returned.
+ * @return handle of first namespace,
+ * or DTM.NULL to indicate none exists.
+>>>>>>> 1.2.2.10
*/
public int getFirstNamespaceNode(int nodeHandle, boolean inScope);
/**
* Given a node handle, advance to its next sibling.
+<<<<<<< DTM.java
* If not yet resolved, waits for more nodes to be added to the document
and
* tries again.
* @param nodeHandle int Handle of the node.
+=======
+ * @param nodeHandle int Handle of the node.
+>>>>>>> 1.2.2.10
* @return int Node-number of next sibling,
* or DTM.NULL to indicate none exists.
*/
@@ -252,8 +299,13 @@
/**
* Given a node handle, find its preceeding sibling.
+<<<<<<< DTM.java
* WARNING: DTM is asymmetric; this operation is resolved by search, and is
* relatively expensive.
+=======
+ * WARNING: DTM implementations may be asymmetric; in some,
+ * this operation is resolved by search, and is relatively expensive.
+>>>>>>> 1.2.2.10
*
* @param nodeHandle the id of the node.
* @return int Node-number of the previous sib,
@@ -264,7 +316,7 @@
/**
* Given a node handle, advance to the next attribute. If an
* element, we advance to its first attribute; if an attr, we advance to
- * the next attr on the same node.
+ * the next attr of the same element.
*
* @param nodeHandle int Handle of the node.
* @return int DTM node-number of the resolved attr,
@@ -273,13 +325,22 @@
public int getNextAttribute(int nodeHandle);
/**
- * Given a namespace handle, advance to the next namespace.
+ * Given a namespace handle, advance to the next namespace in the same
scope
+ * (local or local-plus-inherited, as selected by getFirstNamespaceNode)
*
+<<<<<<< DTM.java
* @param namespaceHandle handle to node which must be of type
NAMESPACE_NODE.
* @return handle of next namespace, or DTM.NULL to indicate none exists.
+=======
+ * @param namespaceHandle handle to node which must be of type
+ * NAMESPACE_NODE.
+ * @return handle of next namespace,
+ * or DTM.NULL to indicate none exists.
+>>>>>>> 1.2.2.10
*/
public int getNextNamespaceNode(int namespaceHandle, boolean inScope);
+<<<<<<< DTM.java
/**
* Given a node handle, advance to its next descendant.
* If not yet resolved, waits for more nodes to be added to the document
and
@@ -290,25 +351,71 @@
* @return handle of next descendant,
* or DTM.NULL to indicate none exists.
*/
+=======
+ /** Lightweight subtree-walker. Given a node handle, find the next
+ * node in document order. (Preorder left-to-right traversal). The
+ * walk stops (returning DTM.NULL) when it would otherwise have to
+ * step out of the subtree of the node indicated by the
+ * subtreeRootHandle.
+ * <p>
+ * One application would be as a subroutine for DTMIterators.
+ * <p>
+ * TODO: Joe would like to rename this to walkNextDescendent
+ * to distinguish it more strongly from getFirstChild
+ *
+ * @param subtreeRootHandle int Handle of the root of the subtree
+ * being walked. Sets an outer limit that we will not walk past.
+ * @param nodeHandle int Handle of a node within the subtree.
+ * @return handle of the next node within the subtree, in document order.
+ * or DTM.NULL to indicate none exists. */
+>>>>>>> 1.2.2.10
public int getNextDescendant(int subtreeRootHandle, int nodeHandle);
- /**
- * Given a node handle, advance to the next node on the following axis.
+ /** Lightweight tree-walker. Given a node handle, find the next
+ * node in document order. The walk stops (returning DTM.NULL) when
+ * it would otherwise run off the end of the document.
+ * <p>
+ * Note that this is roughly equivalent to getNextDescendent() with
+ * subtreeRootHandle set to the Document node (or maybe the root element).
+ * <p>
+ * TODO: Joe would like to rename this to walkNextFollowing
+ * (or perhaps just walkFollowing?)
+ * to distinguish it more strongly from getNextSibling.
*
* @param axisContextHandle the start of the axis that is being traversed.
+<<<<<<< DTM.java
* @param nodeHandle
* @return handle of next sibling,
* or DTM.NULL to indicate none exists.
+=======
+ * TODO: As far as Joe can tell, this parameter is unnecessary...?
+ * @param nodeHandle the node whose successor we're looking for.
+ * @return handle of next node in the DTM tree
+ * or DTM.NULL to indicate none exists.
+>>>>>>> 1.2.2.10
*/
public int getNextFollowing(int axisContextHandle, int nodeHandle);
- /**
- * Given a node handle, advance to the next node on the preceding axis.
- *
+ /** Lightweight tree-walker. Given a node handle, find the next
+ * node in reverse document order. (Postorder right-to-left traversal).
The
+ * walk stops (returning DTM.NULL) when it would otherwise run off the
+ * beginning of the document.
+ * <p>
+ * TODO: Joe would like to rename this to walkNextPreceeding
+ * (or perhaps just walkPreceeding?)
+ * to distinguish it more strongly from getPreviousSibling.
+ *
* @param axisContextHandle the start of the axis that is being traversed.
+<<<<<<< DTM.java
* @param nodeHandle the id of the node.
* @return int Node-number of preceding sibling,
* or DTM.NULL to indicate none exists.
+=======
+ * TODO: As far as Joe can tell, this parameter is unnecessary...?
+ * @param nodeHandle the node whose predecessor we're looking for.
+ * @return handle of next node in the DTM tree
+ * or DTM.NULL to indicate none exists.
+>>>>>>> 1.2.2.10
*/
public int getNextPreceding(int axisContextHandle, int nodeHandle);
@@ -316,11 +423,17 @@
* Given a node handle, find its parent node.
*
* @param nodeHandle the id of the node.
+<<<<<<< DTM.java
* @return int Node-number of parent,
* or DTM.NULL to indicate none exists.
+=======
+ * @return int Node handle of parent,
+ * or DTM.NULL to indicate none exists.
+>>>>>>> 1.2.2.10
*/
public int getParent(int nodeHandle);
+<<<<<<< DTM.java
/**
* Given a node handle, find the owning document node.
*
@@ -346,6 +459,28 @@
/**
+=======
+ /**
+ * Given a node handle, find the owning document node.
+ *
+ * @param nodeHandle the id of the node.
+ * @return int Node handle of document, which should always be valid.
+ */
+ public int getDocument();
+
+ /**
+ * Given a node handle, find the owning document node. This has the exact
+ * same semantics as the DOM Document method of the same name, in that if
+ * the nodeHandle is a document node, it will return NULL.
+ *
+ * @param nodeHandle the id of the node.
+ * @return int Node handle of owning document,
+ * or DTM.NULL if the nodeHandle is a document.
+ */
+ public int getOwnerDocument(int nodeHandle);
+
+ /**
+>>>>>>> 1.2.2.10
* 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).
@@ -378,10 +513,10 @@
*
* @param nodeHandle The node ID.
* @param chunkIndex Which chunk to get.
- * @param startAndLen An array of 2 where the start position and length of
- * the chunk will be returned.
- *
- * @return The character array reference where the chunk occurs.
+ * @param startAndLen A two-integer array which, upon return, WILL
+ * BE FILLED with values representing the chunk's start position
+ * within the returned character buffer and the length of the chunk.
+ * @return The character array buffer within which the chunk occurs.
*/
public char[] getStringValueChunk(int nodeHandle, int chunkIndex,
int[] startAndLen);
@@ -455,9 +590,18 @@
public String getLocalName(int nodeHandle);
/**
+<<<<<<< DTM.java
* 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.
+=======
+ * 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.
+ * (As defined in Namespaces, this is the portion of the name before any
+ * colon character).
+ * @param postition int Handle of the node.
+>>>>>>> 1.2.2.10
*
* <p> %REVIEW% Are you sure you want "" for no prefix? </p>
*
@@ -471,6 +615,10 @@
* 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.)
+<<<<<<< DTM.java
+=======
+ * @param postition int Handle of the node.
+>>>>>>> 1.2.2.10
*
* @param nodeHandle the id of the node.
* @return String URI value of this node's namespace, or null if no
@@ -482,6 +630,10 @@
* Given a node handle, return its node value. This is mostly
* as defined by the DOM, but may ignore some conveniences.
* <p>
+<<<<<<< DTM.java
+=======
+ * @param postition int Handle of the node.
+>>>>>>> 1.2.2.10
*
* @param nodeHandle The node id.
* @return String Value of this node, or null if not
@@ -491,8 +643,12 @@
/**
* Given a node handle, return its DOM-style node type.
+<<<<<<< DTM.java
* <p>
* %REVIEW% Generally, returning short is false economy. Return int?
+=======
+ * @param postition int Handle of the node.
+>>>>>>> 1.2.2.10
*
* @param nodeHandle The node id.
* @return int Node type, as per the DOM's Node._NODE constants.
@@ -508,6 +664,7 @@
* @return the number of ancestors, plus one
*/
public short getLevel(int nodeHandle);
+<<<<<<< DTM.java
// ============== Document query functions ==============
@@ -524,21 +681,42 @@
* supported on this node, <code>false</code> otherwise.
*/
public boolean isSupported(String feature,
- String version);
+ String version);
+=======
+
/**
- * Return the base URI of the document entity. If it is not known
+ * Tests whether DTM DOM implementation implements a specific feature and
+ * that feature is supported by this node.
+ * @param feature The name of the feature to test.
+ * @param version This is the version number of the feature to test.
+ * If the version is not
+ * specified, supporting any version of the feature will cause the
+ * method to return <code>true</code>.
+ * @return Returns <code>true</code> if the specified feature is
+ * supported on this node, <code>false</code> otherwise.
+ */
+ public boolean isSupported(String feature,
+ String version);
+
+ // ============== Document query functions ==============
+
+>>>>>>> 1.2.2.10
+ /**
+ * Return the base URI of the specified node. If it is not known
* (because the document was parsed from a socket connection or from
- * standard input, for example), the value of this property is unknown.
+ * standard input, for example), the value of this property is null.
+ * If you need the document's base URI, you can retrieve the Document
+ * node and then ask it this question.
*
* @param nodeHandle The node id, which can be any valid node handle.
* @return the document base URI String object or null if unknown.
*/
- public String getDocumentBaseURI(int nodeHandle);
+ public String getNodeBaseURI(int nodeHandle);
/**
* Return the system identifier of the document entity. If
- * it is not known, the value of this property is unknown.
+ * it is not known, the value of this property is null.
*
* @param nodeHandle The node id, which can be any valid node handle.
* @return the system identifier String object or null if unknown.
@@ -610,7 +788,7 @@
*
* @return the public identifier String object, or null if there is none.
*/
- public String getDocumentTypeDeclarationPublicIdentifier();
+ public int getDocumentTypeDeclarationPublicIdentifier();
/**
* Returns the <code>Element</code> whose <code>ID</code> is given by
@@ -671,15 +849,24 @@
// ============== Boolean methods ================
/**
+<<<<<<< DTM.java
* Return true if the xsl:strip-space or xsl:preserve-space was processed
* during construction of the DTM document.
*
* <p>%REVEIW% Presumes a 1:1 mapping from DTM to Document, since
* we aren't saying which Document to query...?</p>
*/
- public boolean supportsPreStripping();
+ boolean supportsPreStripping();
/**
+=======
+ * Return true if the xsl:strip-space or xsl:preserve-space was processed
+ * at the construction level.
+ */
+ boolean supportsPreStripping();
+
+ /**
+>>>>>>> 1.2.2.10
* Figure out whether nodeHandle2 should be considered as being later
* in the document than nodeHandle1, in Document Order as defined
* by the XPath model. This may not agree with the ordering defined
@@ -687,33 +874,44 @@
* <p>
* There are some cases where ordering isn't defined, and neither are
* the results of this function -- though we'll generally return true.
- *
+ * <p>
* TODO: Make sure this does the right thing with attribute nodes!!!
+ * <p>
+ * TODO: Consider renaming for clarity. Perhaps isDocumentOrder(a,b)?
*
- * @param node1 DOM Node to perform position comparison on.
- * @param node2 DOM Node to perform position comparison on .
+ * @param firstNodeHandle DOM Node to perform position comparison on.
+ * @param secondNodeHandle DOM Node to perform position comparison on.
*
- * @return false if node2 comes before node1, otherwise return true.
+ * @return false if secondNode comes before firstNode, otherwise return
true.
* You can think of this as
- * <code>(node1.documentOrderPosition <=
node2.documentOrderPosition)</code>.
- */
- public boolean isNodeAfter(int nodeHandle1, int nodeHandle2);
+ * <code>(firstNode.documentOrderPosition <=
secondNode.documentOrderPosition)</code>. */
+ public boolean isNodeAfter(int firstNodeHandle,int secondNodeHandle);
- /**
- * 2. [element content whitespace] A boolean indicating whether the
- * character is white space appearing within element content (see
[XML],
- * 2.10 "White Space Handling"). Note that validating XML
processors are
- * required by XML 1.0 to provide this information. If there is no
- * declaration for the containing element, this property has no
value for
- * white space characters. 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 unknown for white space characters. It is always
false for
- * characters that are not white space.
+ /** 2. [element content whitespace] A boolean indicating whether a
+ * text node represents white space appearing within element content
+ * (see [XML], 2.10 "White Space Handling"). Note that validating
+ * XML processors are required by XML 1.0 to provide this
+ * information... but that DOM Level 2 did not support it, since it
+ * depends on knowledge of the DTD which DOM2 could not guarantee
+ * would be available.
+ * <p>
+ * 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.
+ * <p>
+ * Note too that it always returns false for non-Text nodes.
+ * <p>
+ * TODO: Joe wants to rename this isWhitespaceInElementContent() for
clarity
*
* @param nodeHandle the node ID.
- * @return <code>true</code> if the character data is whitespace;
- * <code>false</code> otherwise.
+ * @return <code>true</code> if the node definitely represents whitespace
in
+ * element content; <code>false</code> otherwise.
*/
public boolean isCharacterElementContentWhitespace(int nodeHandle);
@@ -724,6 +922,7 @@
* boolean. If it is false, then certain properties (indicated in
their
* descriptions below) may be unknown. If it is true, those
properties
* are never unknown.
+
*
* @param the document handle
*
@@ -736,13 +935,14 @@
/**
* 5. [specified] A flag indicating whether this attribute was actually
* specified in the start-tag of its element, or was defaulted from
the
- * DTD.
+ * DTD (or schema).
*
* @param the attribute handle
*
* NEEDSDOC @param attributeHandle
* @return <code>true</code> if the attribute was specified;
- * <code>false</code> if it was defaulted.
+ * <code>false</code> if it was defaulted or the handle doesn't
+ * refer to an attribute node.
*/
public boolean isAttributeSpecified(int attributeHandle);
@@ -766,7 +966,8 @@
throws org.xml.sax.SAXException;
/**
- * Directly create SAX parser events from a subtree.
+ * Directly create SAX parser events representing the XML content of
+ * a DTM subtree. This is a "serialize" operation.
*
* @param nodeHandle The node ID.
* @param ch A non-null reference to a ContentHandler.
@@ -776,6 +977,7 @@
public void dispatchToEvents(
int nodeHandle, org.xml.sax.ContentHandler ch)
+<<<<<<< DTM.java
throws org.xml.sax.SAXException;
// ==== Construction methods (may not be supported by some
implementations!) =====
@@ -805,6 +1007,48 @@
* @param str Non-null reverence to a string.
*/
public void appendTextChild(String str);
+=======
+ throws org.xml.sax.SAXException;
+
+ // ==== Construction methods (may not be supported by some
implementations!) =====
+ // TODO: What response occurs if not supported?
+ // TODO: I suspect we need element and attribute factories, maybe
others.
+
+ /**
+ * Append a child to the end of the document. Please note that the node
+ * is always cloned if it is owned by another document.
+ * <p>
+ * TODO: "End of the document" needs to be defined better. I believe the
+ * intent is equivalent to the DOM sequence
+ * document.getRootElement().appendChild(document.importNode(newChild)))
+ * but we need to nail that down more explicitly.
+ * <p>
+ * TODO: ISSUE -- In DTM, I believe we must ALWAYS clone the node, since
+ * the base DTM is immutable and nodes never exist in isolation.
+ *
+ * @param newChild Must be a valid new node handle.
+ * @param clone true if the child should be cloned into the document.
+ * @param cloneDepth if the clone argument is true, specifies that the
+ * clone should include all it's children.
+ */
+ public void appendChild(int newChild, boolean clone, boolean cloneDepth);
+
+ /**
+ * Append a text node child that will be constructed from a string,
+ * to the end of the document. Behavior is otherwise like appendChild().
+ *
+ * @param str Non-null reverence to a string.
+ */
+ public void appendTextChild(String str);
+
+>>>>>>> 1.2.2.10
}
+<<<<<<< DTM.java
+=======
+
+
+
+
+>>>>>>> 1.2.2.10
1.1.2.3 +46 -12
xml-xalan/java/src/org/apache/xml/dtm/Attic/DTMFilter.java
Index: DTMFilter.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xml/dtm/Attic/DTMFilter.java,v
retrieving revision 1.1.2.2
retrieving revision 1.1.2.3
diff -u -r1.1.2.2 -r1.1.2.3
--- DTMFilter.java 2001/04/11 23:04:32 1.1.2.2
+++ DTMFilter.java 2001/04/26 17:39:02 1.1.2.3
@@ -57,14 +57,15 @@
package org.apache.xml.dtm;
/**
- * Simple filter for doing node tests. Note the semantics of this are
somewhat
- * different that the DOM's NodeFilter.
+ * Simple filter for doing node tests. Note the semantics of this are
+ * somewhat different that the DOM's NodeFilter.
*/
public interface DTMFilter
{
// Constants for whatToShow. These are used to set the node type that
will
- // be traversed.
+ // be traversed. These values may be ORed together before being passed to
+ // the DTMIterator.
/**
* Show all <code>Nodes</code>.
@@ -82,7 +83,7 @@
* <code>root</code>; in this case, it means that the attribute node
* will appear in the first position of the iteration or traversal.
* Since attributes are never children of other nodes, they do not
- * appear when traversing over the document tree.
+ * appear when traversing over the main document tree.
*/
public static final int SHOW_ATTRIBUTE = 0x00000002;
@@ -97,7 +98,9 @@
public static final int SHOW_CDATA_SECTION = 0x00000008;
/**
- * Show <code>EntityReference</code> nodes.
+ * Show <code>EntityReference</code> nodes. Note that if Entity References
+ * have been fully expanded while the tree was being constructed, these
+ * nodes will not appear and this mask has no effect.
*/
public static final int SHOW_ENTITY_REFERENCE = 0x00000010;
@@ -107,7 +110,7 @@
* <code>root</code>; in this case, it means that the <code>Entity</code>
* node will appear in the first position of the traversal. Since
* entities are not part of the document tree, they do not appear when
- * traversing over the document tree.
+ * traversing over the main document tree.
*/
public static final int SHOW_ENTITY = 0x00000020;
@@ -122,17 +125,21 @@
public static final int SHOW_COMMENT = 0x00000080;
/**
- * Show <code>Document</code> nodes.
+ * Show <code>Document</code> nodes. (Of course, as with Attributes
+ * and such, this is meaningful only when the iteration root is the
+ * Document itself, since Document has no parent.)
*/
public static final int SHOW_DOCUMENT = 0x00000100;
/**
- * Show <code>DocumentType</code> nodes.
+ * Show <code>DocumentType</code> nodes.
*/
public static final int SHOW_DOCUMENT_TYPE = 0x00000200;
/**
- * Show <code>DocumentFragment</code> nodes.
+ * Show <code>DocumentFragment</code> nodes. (Of course, as with
+ * Attributes and such, this is meaningful only when the iteration
+ * root is the Document itself, since DocumentFragment has no parent.)
*/
public static final int SHOW_DOCUMENT_FRAGMENT = 0x00000400;
@@ -142,22 +149,45 @@
* <code>root</code>; in this case, it means that the
* <code>Notation</code> node will appear in the first position of the
* traversal. Since notations are not part of the document tree, they do
- * not appear when traversing over the document tree.
+ * not appear when traversing over the main document tree.
*/
public static final int SHOW_NOTATION = 0x00000800;
+<<<<<<< DTMFilter.java
/**
* This bit specifies a namespace, and extends the SHOW_XXX stuff
* in [EMAIL PROTECTED] org.w3c.dom.traversal.NodeFilter}.
* Make sure this does not conflict with those values.
*/
+=======
+ /**
+
+ * This bit instructs the iterator to show namespace nodes, which
+ * are modeled by DTM but not by the DOM. Make sure this does not
+ * conflict with [EMAIL PROTECTED] org.w3c.dom.traversal.NodeFilter}.
+ * <p>
+ * ISSUE: Might be safer to start from higher bits and work down,
+ * to leave room for the DOM to expand its set of constants... Or,
+ * possibly, to create a DTM-specific field for these additional bits.
+ */
+>>>>>>> 1.1.2.3
public static final int SHOW_NAMESPACE = 0x00001000;
/**
+<<<<<<< DTMFilter.java
* Special bitmap for match patterns starting with a function.
* This extends the SHOW_XXX stuff
* in [EMAIL PROTECTED] org.w3c.dom.traversal.NodeFilter}.
* Make sure this does not conflict with those values.
+=======
+ * Special bit for filters implementing match patterns starting with
+ * a function. Make sure this does not conflict with
+ * [EMAIL PROTECTED] org.w3c.dom.traversal.NodeFilter}.
+ * <p>
+ * ISSUE: Might be safer to start from higher bits and work down,
+ * to leave room for the DOM to expand its set of constants... Or,
+ * possibly, to create a DTM-specific field for these additional bits.
+>>>>>>> 1.1.2.3
*/
public static final int SHOW_BYFUNCTION = 0x00010000;
@@ -180,6 +210,11 @@
* will be called by the implementation of <code>DTMIterator</code>;
* it is not normally called directly from
* user code.
+ * <p>
+ * TODO: Is 0xFFFF really better than '*'?
+ * <p>
+ * TODO: Should this be setNameMatch(expandedName) followed by accept()?
+ * Or will we really be testing a different name at every invocation?
*
* <p>%REVIEW% Under what circumstances will this be used? The cases
* I've considered are just as easy and just about as efficient if
@@ -199,8 +234,7 @@
* @param expandedName a value defining the exanded name as defined in
* the DTM interface. Wild cards will be defined
* by 0xFFFF in the high word and/or in the low word.
- * @return one of FILTER_ACCEPT, FILTER_REJECT, or FILTER_SKIP.
- */
+ * @return one of FILTER_ACCEPT, FILTER_REJECT, or FILTER_SKIP. */
public short acceptNode(int nodeHandle, int whatToShow, int expandedName);
}
1.1.2.3 +94 -35
xml-xalan/java/src/org/apache/xml/dtm/Attic/DTMIterator.java
Index: DTMIterator.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xml/dtm/Attic/DTMIterator.java,v
retrieving revision 1.1.2.2
retrieving revision 1.1.2.3
diff -u -r1.1.2.2 -r1.1.2.3
--- DTMIterator.java 2001/04/11 23:04:33 1.1.2.2
+++ DTMIterator.java 2001/04/26 17:39:02 1.1.2.3
@@ -57,8 +57,10 @@
package org.apache.xml.dtm;
/**
- * <code>Iterators</code> are used to step through a set of nodes.
- * It is modeled largely after the DOM NodeIterator.
+
+ * <code>DTMIterators</code> are used to step through a (possibly
+ * filtered) set of nodes. Their API is modeled largely after the DOM
+ * NodeIterator.
*
* <p>A DTMIterator is a somewhat unusual type of iterator, in that it
* can serve both single node iteration and random access.</p>
@@ -71,12 +73,19 @@
* <p>A DTMIterator is meant to be created once as a master static object,
and
* then cloned many times for runtime use. Or the master object itself may
* be used for simpler use cases.</p>
- * <p>State: In progress!!</p>
- */
+ *
+ * <p>At this time, we do not expect DTMIterator to emulate
+ * NodeIterator's "maintain relative position" semantics under
+ * document mutation. It's likely to respond more like the
+ * TreeWalker's "current node" semantics. However, since the base DTM
+ * is immutable, this issue currently makes no practical
+ * difference.</p>
+ *
+ * <p>State: In progress!!</p> */
public interface DTMIterator
{
- // Constants returned by acceptNode
+ // Constants returned by acceptNode, borrowed from the DOM Traversal
chapter
/**
* Accept the node.
@@ -84,7 +93,9 @@
public static final short FILTER_ACCEPT = 1;
/**
- * Reject the node. (same as FILTER_SKIP).
+ * Reject the node. Same behavior as FILTER_SKIP. (In the DOM these
+ * differ when applied to a TreeWalker but have the same result when
+ * applied to a NodeIterator).
*/
public static final short FILTER_REJECT = 2;
@@ -95,11 +106,13 @@
/**
* Set the environment in which this iterator operates, which should
provide:
- * a node (the context node... same value as "root" defined below)
- * a pair of non-zero positive integers (the context position and the
context size)
- * a set of variable bindings
- * a function library
- * the set of namespace declarations in scope for the expression.
+ * <ul>
+ * <li>a node (the context node... same value as "root" defined below)
</li>
+ * <li>a pair of non-zero positive integers (the context position and the
context size) </li>
+ * <li>a set of variable bindings </li>
+ * <li>a function library </li>
+ * <li>the set of namespace declarations in scope for the expression.</li>
+ * <ul>
*
* <p>At this time the exact implementation of this environment is
application
* dependent. Probably a proper interface will be created fairly soon.</p>
@@ -107,6 +120,7 @@
* @param environment The environment object.
*/
public void setEnvironment(Object environment);
+<<<<<<< DTMIterator.java
/**
* Get an instance of a DTM that "owns" a node handle. Since a node
@@ -128,28 +142,56 @@
*/
public DTMManager getDTMManager();
+=======
+
+ /**
+ * Get an instance of a DTM that "owns" a node handle. Since a node
+ * iterator may be passed without a DTMManager, this allows the
+ * caller to easily get the DTM using just the iterator.
+ *
+ * TODO: Do we really need this, given getDTMManager()?
+ *
+ * @param nodeHandle the nodeHandle.
+ *
+ * @return a non-null DTM reference.
+ */
+ public DTM getDTM(int nodeHandle);
+
/**
+ * Get an instance of the DTMManager. Since a node
+ * iterator may be passed without a DTMManager, this allows the
+ * caller to easily get the DTMManager using just the iterator.
+ *
+ * @return a non-null DTMManager reference.
+ */
+ public DTMManager getDTMManager();
+
+
+>>>>>>> 1.1.2.3
+ /**
* The root node of the <code>DTMIterator</code>, as specified when it
* was created. Note the root node is not the root node of the
- * document tree, but the context node from where the itteration
- * begins.
+ * document tree, but the context node from where the iteration
+ * begins and ends.
*
* @return nodeHandle int Handle of the context node.
*/
public int getRoot();
/**
- * The root node of the <code>DTMIterator</code>, as specified when it
- * was created. Note the root node is not the root node of the
- * document tree, but the context node from where the itteration
- * begins.
+ * Reset the root node of the <code>DTMIterator</code>, overriding
+ * the value specified when it was created. Note the root node is
+ * not the root node of the document tree, but the context node from
+ * where the itteration begins.
*
* @param nodeHandle int Handle of the context node.
*/
public void setRoot(int nodeHandle);
/**
- * Reset the iterator to the start.
+ * Reset the iterator to the start. After resetting, the next node returned
+ * will be the root node -- or, if that's filtered out, the first node
+ * within the root's subtree which is _not_ skipped by the filters.
*/
public void reset();
@@ -160,24 +202,27 @@
* <code>whatToShow</code> will be skipped, but their children may still
* be considered.
*
- * @return one of the SHOW_XXX constants.
+ * @return one of the SHOW_XXX constants, or several ORed together.
*/
public int getWhatToShow();
/**
- * The value of this flag determines whether the children of entity
+ * <p>The value of this flag determines whether the children of entity
* reference nodes are visible to the iterator. If false, they and
* their descendants will be rejected. Note that this rejection takes
- * precedence over <code>whatToShow</code> and the filter.
- * <br>
- * <br> To produce a view of the document that has entity references
+ * precedence over <code>whatToShow</code> and the filter. </p>
+ *
+ * <p> To produce a view of the document that has entity references
* expanded and does not expose the entity reference node itself, use
* the <code>whatToShow</code> flags to hide the entity reference node
* and set <code>expandEntityReferences</code> to true when creating the
* iterator. To produce a view of the document that has entity reference
* nodes but no entity expansion, use the <code>whatToShow</code> flags
* to show the entity reference node and set
- * <code>expandEntityReferences</code> to false.
+ * <code>expandEntityReferences</code> to false.</p>
+ *
+ * NOTE: In DTM we will generally have fully expanded entity references
+ * when the document tree was built, and thus this flag will have no
effect.
*
* @return true if entity references will be expanded.
*/
@@ -186,8 +231,9 @@
/**
* Returns the next node in the set and advances the position of the
* iterator in the set. After a <code>DTMIterator</code> has setRoot
called,
- * the first call to <code>nextNode()</code> returns the first node in
- * the set.
+ * the first call to <code>nextNode()</code> returns that root or (if it
+ * is rejected by the filters) the first node within its subtree which is
+ * not filtered out.
* @return The next node handle in the set being iterated over, or
* -1 if there are no more members in that set.
*/
@@ -207,11 +253,20 @@
* in the INVALID state. After <code>detach</code> has been invoked,
* calls to <code>nextNode</code> or <code>previousNode</code> will
* raise a runtime exception.
+ *
+ * TODO: This method may not be required in DTMIterator.
+ * It was needed in DOMIterator because data linkages were
+ * established to support the "maintain relative position" semantic
+ * under document mutation... but if DTM decides it doesn't need
+ * that semantic, we probably don't need to worry about this
+ * cleanup. On the other hand, at worst it's a harmless no-op...
*/
public void detach();
/**
- * Get the current node in the iterator.</a>.
+ * Get the current node in the iterator. Note that this differs from
+ * the DOM's NodeIterator, where the current position lies between two
+ * nodes (as part of the maintain-relative-position semantic).
*
* @return The current node handle, or -1.
*/
@@ -233,17 +288,19 @@
* be cached, enabling random access, and giving the ability to do
* sorts and the like. They are not cached by default.
*
+ * TODO: Shouldn't the other random-access methods throw an exception
+ * if they're called on a DTMIterator with this flag set false?
+ *
* @param b true if the nodes should be cached.
*/
public void setShouldCacheNodes(boolean b);
- /**
- * Get the current position, which is one less than
- * the next nextNode() call will retrieve. i.e. if
- * you call getCurrentPos() and the return is 0, the next
- * fetch will take place at index 1.
+ /** Get the current position within the cached list, which is one
+ * less than the next nextNode() call will retrieve. i.e. if you
+ * call getCurrentPos() and the return is 0, the next fetch will
+ * take place at index 1.
*
- * @return The position of the iteration.</a>.
+ * @return The position of the iteration.
*/
public int getCurrentPos();
@@ -251,7 +308,8 @@
* If an index is requested, NodeSet will call this method
* to run the iterator to the index. By default this sets
* m_next to the index. If the index argument is -1, this
- * signals that the iterator should be run to the end.
+ * signals that the iterator should be run to the end and
+ * completely fill the cache.
*
* @param index The index to run to, or -1 if the iterator should be run
* to the end.
@@ -279,7 +337,8 @@
/**
* The number of nodes in the list. The range of valid child node indices
- * is 0 to <code>length-1</code> inclusive.
+ * is 0 to <code>length-1</code> inclusive. Note that this requires running
+ * the iterator to completion, and presumably filling the cache.
*
* @return The number of nodes in the list.
*/
1.1.2.6 +47 -249
xml-xalan/java/src/org/apache/xml/dtm/Attic/DTMManager.java
Index: DTMManager.java
===================================================================
RCS file:
/home/cvs/xml-xalan/java/src/org/apache/xml/dtm/Attic/DTMManager.java,v
retrieving revision 1.1.2.5
retrieving revision 1.1.2.6
diff -u -r1.1.2.5 -r1.1.2.6
--- DTMManager.java 2001/04/17 15:58:12 1.1.2.5
+++ DTMManager.java 2001/04/26 17:39:03 1.1.2.6
@@ -56,16 +56,6 @@
*/
package org.apache.xml.dtm;
-import java.io.IOException;
-import java.io.File;
-import java.io.FileInputStream;
-import java.io.InputStream;
-import java.io.InputStreamReader;
-import java.io.BufferedReader;
-
-import java.util.Properties;
-import java.util.Enumeration;
-
import org.apache.xml.utils.PrefixResolver;
/**
@@ -83,93 +73,18 @@
* of DTMs across multiple processes.</p>
*
* <p>Note: this class is incomplete right now. It will be pretty much
- * modeled after org.apache.xml.dtm.DTMManager in terms of its
+ * modeled after javax.xml.transform.TransformerFactory in terms of its
* factory support.</p>
*
* <p>State: In progress!!</p>
*/
public abstract class DTMManager
{
- /** The default property name according to the JAXP spec. */
- private static final String defaultPropName =
- "org.apache.xml.dtm.DTMManager";
-
- /**
- * The default table for exandedNameID lookups.
- */
- private static ExpandedNameTable m_expandedNameTable = new
ExpandedNameTable();
/**
* Default constructor is protected on purpose.
*/
protected DTMManager(){}
-
- /**
- * Obtain a new instance of a <code>DTMManager</code>.
- * This static method creates a new factory instance
- * This method uses the following ordered lookup procedure to determine
- * the <code>DTMManager</code> implementation class to
- * load:
- * <ul>
- * <li>
- * Use the <code>javax.xml.parsers.DocumentBuilderFactory</code> system
- * property.
- * </li>
- * <li>
- * Use the JAVA_HOME(the parent directory where jdk is
- * installed)/lib/jaxp.properties for a property file that contains the
- * name of the implementation class keyed on the same value as the
- * system property defined above.
- * </li>
- * <li>
- * Use the Services API (as detailed in teh JAR specification), if
- * available, to determine the classname. The Services API will look
- * for a classname in the file
- * <code>META-INF/services/javax.xml.parsers.DTMManager</code>
- * in jars available to the runtime.
- * </li>
- * <li>
- * Platform default <code>DTMManager</code> instance.
- * </li>
- * </ul>
- *
- * Once an application has obtained a reference to a <code>
- * DTMManager</code> it can use the factory to configure
- * and obtain parser instances.
- *
- * @return new DTMManager instance, never null.
- *
- * @throws DTMConfigurationException
- * if the implmentation is not available or cannot be instantiated.
- */
- public static DTMManager newInstance()
- throws DTMConfigurationException {
-
- String classname =
- findFactory(defaultPropName,
- "org.apache.xml.dtm.DTMManagerDefault");
-
- if (classname == null) {
- throw new DTMConfigurationException(
- "No default implementation found");
- }
-
- DTMManager factoryImpl;
-
- try {
- Class clazz = Class.forName(classname);
-
- factoryImpl = (DTMManager) clazz.newInstance();
- } catch (ClassNotFoundException cnfe) {
- throw new DTMConfigurationException(cnfe);
- } catch (IllegalAccessException iae) {
- throw new DTMConfigurationException(iae);
- } catch (InstantiationException ie) {
- throw new DTMConfigurationException(ie);
- }
-
- return factoryImpl;
- }
/**
* Get an instance of a DTM, loaded with the content from the
@@ -197,6 +112,7 @@
* @return a non-null DTM reference.
*/
public abstract DTM getDTM(int nodeHandle);
+<<<<<<< DTMManager.java
/**
* Creates a DTM representing an empty <code>DocumentFragment</code>
object.
@@ -218,6 +134,26 @@
+=======
+
+ /**
+ * Creates an empty <code>DocumentFragment</code> object.
+ * @return a non-null DTM reference.
+ */
+ public abstract DTM createDocumentFragment();
+
+ /**
+ * Release a DTM either to a lru pool, or completely remove reference.
+ * DTMs without system IDs are always hard deleted.
+ * State: experimental.
+ *
+ * @param dtm The DTM to be released.
+ * @param shouldHardDelete True if the DTM should be removed no matter
what.
+ * @return true if the DTM was removed, false if it was put back in a lru
pool.
+ */
+ public abstract boolean release(DTM dtm, boolean shouldHardDelete);
+
+>>>>>>> 1.1.2.3
/**
* Create a new <code>DTMIterator</code> based on an XPath
@@ -251,9 +187,14 @@
PrefixResolver presolver);
/**
- * Create a new <code>DTMIterator</code> based only on a whatToShow and
- * a DTMFilter. The traversal semantics are defined as the descendant
- * access.
+ * Create a new <code>DTMIterator</code> based only on a whatToShow
+ * and a DTMFilter. The traversal semantics are defined as the
+ * descendant access.
+ * <p>
+ * Note that DTMIterators may not be an exact match to DOM *
+ * NodeIterators. They are initialized and used in much the same way
+ * as a NodeIterator, but their response to document mutation is not
+ * currently defined.
*
* @param whatToShow This flag specifies which node types may appear in
* the logical view of the tree presented by the iterator. See the
@@ -261,14 +202,19 @@
* <code>SHOW_</code> values.These flags can be combined using
* <code>OR</code>.
* @param filter The <code>NodeFilter</code> to be used with this
- * <code>TreeWalker</code>, or <code>null</code> to indicate no filter.
+ * <code>DTMFilter</code>, or <code>null</code> to indicate no filter.
* @param entityReferenceExpansion The value of this flag determines
* whether entity reference nodes are expanded.
*
+<<<<<<< DTMManager.java
* @return The newly created <code>DTMIterator</code>.
*/
+=======
+ * @return The newly created <code>DTMIterator</code>. */
+>>>>>>> 1.1.2.3
public abstract DTMIterator createDTMIterator(int whatToShow,
DTMFilter filter, boolean entityReferenceExpansion);
+<<<<<<< DTMManager.java
/**
* Create a new <code>DTMIterator</code> that holds exactly one node.
@@ -278,165 +224,17 @@
* @return The newly created <code>DTMIterator</code>.
*/
public abstract DTMIterator createDTMIterator(int node);
-
- // -------------------- private methods --------------------
- /**
- * Avoid reading all the files when the findFactory
- * method is called the second time (cache the result of
- * finding the default impl).
- */
- private static String foundFactory = null;
-
- /**
- * Temp debug code - this will be removed after we test everything
- */
- private static boolean debug;
- static {
- try {
- debug = System.getProperty("dtm.debug") != null;
- } catch( SecurityException ex ) {}
- }
-
- /**
- * Private implementation method - will find the implementation
- * class in the specified order.
- *
- * @param factoryId Name of the factory interface.
- * @param xmlProperties Name of the properties file based on JAVA/lib.
- * @param defaultFactory Default implementation, if nothing else is
found.
- *
- * @return The factory class name.
- */
- private static String findFactory(String factoryId,
- String defaultFactory) {
-
- // Use the system property first
- try {
- String systemProp = null;
- try {
- systemProp = System.getProperty(factoryId);
- } catch( SecurityException se ) {}
-
- if (systemProp != null) {
- if (debug) {
- System.err.println("DTM: found system property"
- + systemProp);
- }
-
- return systemProp;
- }
- } catch (SecurityException se) {}
-
- if (foundFactory != null) {
- return foundFactory;
- }
-
- // try to read from $java.home/lib/jaxp.properties
- try {
- String javah = System.getProperty("java.home");
- String configFile = javah + File.separator + "lib"
- + File.separator + "jaxp.properties";
- File f = new File(configFile);
-
- if (f.exists()) {
- Properties props = new Properties();
-
- props.load(new FileInputStream(f));
-
- foundFactory = props.getProperty(factoryId);
-
- if (debug) {
- System.err.println("DTM: found java.home property "
- + foundFactory);
- }
-
- if (foundFactory != null) {
- return foundFactory;
- }
- }
- } catch (Exception ex) {
- if (debug) {
- ex.printStackTrace();
- }
- }
-
- String serviceId = "META-INF/services/" + factoryId;
-
- // try to find services in CLASSPATH
- try {
- ClassLoader cl = DTMManager.class.getClassLoader();
- InputStream is = null;
-
- if (cl == null) {
- is = ClassLoader.getSystemResourceAsStream(serviceId);
- } else {
- is = cl.getResourceAsStream(serviceId);
- }
-
- if (is != null) {
- if (debug) {
- System.err.println("DTM: found " + serviceId);
- }
-
- BufferedReader rd =
- new BufferedReader(new InputStreamReader(is));
-
- foundFactory = rd.readLine();
-
- rd.close();
-
- if (debug) {
- System.err.println("DTM: loaded from services: "
- + foundFactory);
- }
-
- if ((foundFactory != null) &&!"".equals(foundFactory)) {
- return foundFactory;
- }
- }
- } catch (Exception ex) {
- if (debug) {
- ex.printStackTrace();
- }
- }
-
- return defaultFactory;
- }
-
- /** %TBD% Doc */
- static final int IDENT_DTM_DEFAULT = 0xFFF00000;
-
- /** %TBD% Doc */
- static final int IDENT_NODE_DEFAULT = 0x000FFFFF;
-
- /**
- * %TBD% Doc
- */
- public abstract int getDTMIdentity(DTM dtm);
-
- /**
- * %TBD% Doc
- */
- public int getDTMIdentityMask()
- {
- return IDENT_DTM_DEFAULT;
- }
-
- /**
- * %TBD% Doc
- */
- public int getNodeIdentityMask()
- {
- return IDENT_NODE_DEFAULT;
- }
-
- /**
- * return the expanded name table.
- */
- public ExpandedNameTable getExpandedNameTable(DTM dtm)
- {
- return m_expandedNameTable;
- }
+=======
+
+ /**
+ * Create a new <code>DTMIterator</code> that holds exactly one node.
+ *
+ * @param node The node handle that the DTMIterator will iterate to.
+ *
+ * @return The newly created <code>DTMIterator</code>.
+ */
+ public abstract DTMIterator createDTMIterator(int node);
+>>>>>>> 1.1.2.3
}
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
