You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xerces.apache.org by rp...@locus.apache.org on 2000/01/07 00:41:04 UTC
cvs commit: xml-xerces/java/src/org/w3c/dom/traversal DocumentTraversal.java NodeFilter.java NodeIterator.java TreeWalker.java
rpfeiffe 00/01/06 15:41:04
Added: java/src/org/w3c/dom/traversal DocumentTraversal.java
NodeFilter.java NodeIterator.java TreeWalker.java
Log:
DOM Level 2 - upgraded org.w3c.dom Interfaces to:
W3C Candidate Recommendation 10 December, 1999
Placed them in their proper place, and changed referring
imports.
-rip
Revision Changes Path
1.1 xml-xerces/java/src/org/w3c/dom/traversal/DocumentTraversal.java
Index: DocumentTraversal.java
===================================================================
/*
* Copyright (c) 1999 World Wide Web Consortium,
* (Massachusetts Institute of Technology, Institut National de
* Recherche en Informatique et en Automatique, Keio University). All
* Rights Reserved. This program is distributed under the W3C's Software
* Intellectual Property License. This program is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY; without even
* the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE. See W3C License http://www.w3.org/Consortium/Legal/ for more
* details.
*/
package org.w3c.dom.traversal;
import org.w3c.dom.DOMException;
import org.w3c.dom.Node;
/**
* <code>DocumentTraversal</code> contains methods that create iterators and
* tree-walkers to traverse a node and its children in document order (depth
* first, pre-order traversal, which is equivalent to the order in which the
* start tags occur in the text representation of the document).
* @since DOM Level 2
*/
public interface DocumentTraversal {
/**
* Create a new NodeIterator over the subtree rooted at the specified node.
* @param root The node which will be iterated together with its children.
* The iterator is initially positioned just before this node. The
* whatToShow flags and the filter, if any, are not considered when
* setting this position.
* @param whatToShow This flag specifies which node types may appear in the
* logical view of the tree presented by the iterator. See the
* description of iterator for the set of possible values.These flags
* can be combined using <code>OR</code>.
* @param filter The Filter to be used with this TreeWalker, or null to
* indicate no filter.
* @param entityReferenceExpansion The value of this flag determines
* whether entity reference nodes are expanded.
* @return The newly created <code>NodeIterator</code>.
*/
public NodeIterator createNodeIterator(Node root,
int whatToShow,
NodeFilter filter,
boolean entityReferenceExpansion);
/**
* Create a new TreeWalker over the subtree rooted at the specified node.
* @param root The node which will serve as the root for the
* <code>TreeWalker</code>. The whatToShow flags and the NodeFilter are
* not considered when setting this value; any node type will be
* accepted as the root. The currentNode of the TreeWalker is
* initialized to this node, whether or not it is visible. The root
* functions as a stopping point for traversal methods that look upward
* in the document structure, such as parentNode and nextNode. The root
* must not be null.
* @param whatToShow This flag specifies which node types may appear in the
* logical view of the tree presented by the iterator. See the
* description of TreeWalker for the set of possible values.These flags
* can be combined using <code>OR</code>.
* @param filter The Filter to be used with this TreeWalker, or null to
* indicate no filter.
* @param entityReferenceExpansion The value of this flag determines
* whether entity reference nodes are expanded.
* @return The newly created <code>TreeWalker</code>.
* @exception DOMException
* Raises the exception NOT_SUPPORTED_ERR if the specified root node
* is null.
*/
public TreeWalker createTreeWalker(Node root,
int whatToShow,
NodeFilter filter,
boolean entityReferenceExpansion)
throws DOMException;
}
1.1 xml-xerces/java/src/org/w3c/dom/traversal/NodeFilter.java
Index: NodeFilter.java
===================================================================
/*
* Copyright (c) 1999 World Wide Web Consortium,
* (Massachusetts Institute of Technology, Institut National de
* Recherche en Informatique et en Automatique, Keio University). All
* Rights Reserved. This program is distributed under the W3C's Software
* Intellectual Property License. This program is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY; without even
* the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE. See W3C License http://www.w3.org/Consortium/Legal/ for more
* details.
*/
package org.w3c.dom.traversal;
import org.w3c.dom.Node;
/**
* Filters are objects that know how to "filter out" nodes. If a
* <code>NodeIterator</code> or <code>TreeWalker</code> is given a filter, it
* applies the filter before it returns the next node. If the filter says to
* accept the node, the iterator returns it; otherwise, the iterator looks
* for the next node and pretends that the node that was rejected was not
* there.
* <p>The DOM does not provide any filters. Filter is just an interface that
* users can implement to provide their own filters.
* <p>Filters do not need to know how to iterate, nor do they need to know
* anything about the data structure that is being iterated. This makes it
* very easy to write filters, since the only thing they have to know how to
* do is evaluate a single node. One filter may be used with a number of
* different kinds of iterators, encouraging code reuse. This is an
* ECMAScript function reference. This method returns a <code>short</code>.
* The parameter is of type <code>Node</code>.
*/
public interface NodeFilter {
// Constants returned by acceptNode
public static final short FILTER_ACCEPT = 1;
public static final short FILTER_REJECT = 2;
public static final short FILTER_SKIP = 3;
// Constants for whatToShow
public static final int SHOW_ALL = 0x0000FFFF;
public static final int SHOW_ELEMENT = 0x00000001;
public static final int SHOW_ATTRIBUTE = 0x00000002;
public static final int SHOW_TEXT = 0x00000004;
public static final int SHOW_CDATA_SECTION = 0x00000008;
public static final int SHOW_ENTITY_REFERENCE = 0x00000010;
public static final int SHOW_ENTITY = 0x00000020;
public static final int SHOW_PROCESSING_INSTRUCTION = 0x00000040;
public static final int SHOW_COMMENT = 0x00000080;
public static final int SHOW_DOCUMENT = 0x00000100;
public static final int SHOW_DOCUMENT_TYPE = 0x00000200;
public static final int SHOW_DOCUMENT_FRAGMENT = 0x00000400;
public static final int SHOW_NOTATION = 0x00000800;
/**
* Test whether a specified node is visible in the logical view of a
* TreeWalker or NodeIterator. This function will be called by the
* implementation of TreeWalker and NodeIterator; it is not intended to
* be called directly from user code.
* @param n The node to check to see if it passes the filter or not.
* @return a constant to determine whether the node is accepted, rejected,
* or skipped, as defined above.
*/
public short acceptNode(Node n);
}
1.1 xml-xerces/java/src/org/w3c/dom/traversal/NodeIterator.java
Index: NodeIterator.java
===================================================================
/*
* Copyright (c) 1999 World Wide Web Consortium,
* (Massachusetts Institute of Technology, Institut National de
* Recherche en Informatique et en Automatique, Keio University). All
* Rights Reserved. This program is distributed under the W3C's Software
* Intellectual Property License. This program is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY; without even
* the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE. See W3C License http://www.w3.org/Consortium/Legal/ for more
* details.
*/
package org.w3c.dom.traversal;
import org.w3c.dom.DOMException;
import org.w3c.dom.Node;
/**
* NodeIterators are used to step through a set of nodes, e.g. the set of
* nodes in a NodeList, the document subtree governed by a particular node,
* the results of a query, or any other set of nodes. The set of nodes to be
* iterated is determined by the implementation of the NodeIterator. DOM
* Level 2 specifies a single NodeIterator implementation for document-order
* traversal of a document subtree. Instances of these iterators are created
* by calling DocumentTraversal.createNodeIterator().
* @since DOM Level 2
*/
public interface NodeIterator {
/**
* This attribute determines which node types are presented via the
* iterator. The available set of constants is defined in the Filters
* interface.
*/
public int getWhatToShow();
/**
* The filter used to screen nodes.
*/
public NodeFilter getFilter();
/**
* The value of this flag determines whether the children of entity
* reference nodes are visible to the iterator. If false, they will be
* skipped over.
* <br> To produce a view of the document that has entity references
* expanded and does not expose the entity reference node itself, use the
* whatToShow flags to hide the entity reference node and set
* expandEntityReferences to true when creating the iterator. To produce
* a view of the document that has entity reference nodes but no entity
* expansion, use the whatToShow flags to show the entity reference node
* and set expandEntityReferences to false.
*/
public boolean getExpandEntityReferences();
/**
* Returns the next node in the set and advances the position of the
* iterator in the set. After a NodeIterator is created, the first call
* to nextNode() returns the first node in the set.
* @return The next <code>Node</code> in the set being iterated over, or
* <code>null</code> if there are no more members in that set.
* @exception DOMException
* INVALID_STATE_ERR: Raised if this method is called after the
* <code>detach</code> method was invoked.
*/
public Node nextNode()
throws DOMException;
/**
* Returns the previous node in the set and moves the position of the
* iterator backwards in the set.
* @return The previous <code>Node</code> in the set being iterated over,
* or <code>null</code> if there are no more members in that set.
* @exception DOMException
* INVALID_STATE_ERR: Raised if this method is called after the
* <code>detach</code> method was invoked.
*/
public Node previousNode()
throws DOMException;
/**
* Detaches the iterator from the set which it iterated over, releasing
* any computational resources and placing the iterator in the INVALID
* state. After <code>detach</code> has been invoked, calls to
* <code>nextNode</code> or <code>previousNode</code> will raise the
* exception INVALID_STATE_ERR.
*/
public void detach();
}
1.1 xml-xerces/java/src/org/w3c/dom/traversal/TreeWalker.java
Index: TreeWalker.java
===================================================================
/*
* Copyright (c) 1999 World Wide Web Consortium,
* (Massachusetts Institute of Technology, Institut National de
* Recherche en Informatique et en Automatique, Keio University). All
* Rights Reserved. This program is distributed under the W3C's Software
* Intellectual Property License. This program is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY; without even
* the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE. See W3C License http://www.w3.org/Consortium/Legal/ for more
* details.
*/
package org.w3c.dom.traversal;
import org.w3c.dom.DOMException;
import org.w3c.dom.Node;
/**
* <code>TreeWalker</code> objects are used to navigate a document tree or
* subtree using the view of the document defined by its
* <code>whatToShow</code> flags and any filters that are defined for the
* <code>TreeWalker</code>. Any function which performs navigation using a
* <code>TreeWalker</code> will automatically support any view defined by a
* <code>TreeWalker</code>.
* <p>Omitting nodes from the logical view of a subtree can result in a
* structure that is substantially different from the same subtree in the
* complete, unfiltered document. Nodes that are siblings in the TreeWalker
* view may be children of different, widely separated nodes in the original
* view. For instance, consider a Filter that skips all nodes except for Text
* nodes and the root node of a document. In the logical view that results,
* all text nodes will be siblings and appear as direct children of the root
* node, no matter how deeply nested the structure of the original document.
* @since DOM Level 2
*/
public interface TreeWalker {
/**
* This attribute determines which node types are presented via the
* TreeWalker. These constants are defined in the NodeFilter interface.
*/
public int getWhatToShow();
/**
* The filter used to screen nodes.
*/
public NodeFilter getFilter();
/**
* The value of this flag determines whether the children of entity
* reference nodes are visible to the TreeWalker. If false, they will be
* skipped over.
* <br> To produce a view of the document that has entity references
* expanded and does not expose the entity reference node itself, use the
* whatToShow flags to hide the entity reference node and set
* expandEntityReferences to true when creating the TreeWalker. To
* produce a view of the document that has entity reference nodes but no
* entity expansion, use the whatToShow flags to show the entity
* reference node and set expandEntityReferences to false.
*/
public boolean getExpandEntityReferences();
/**
* The node at which the TreeWalker is currently positioned.
* <br>The value must not be null. Alterations to the DOM tree may cause
* the current node to no longer be accepted by the TreeWalker's
* associated filter. currentNode may also be explicitly set to any node,
* whether or not it is within the subtree specified by the root node or
* would be accepted by the filter and whatToShow flags. Further
* traversal occurs relative to currentNode even if it is not part of the
* current view by applying the filters in the requested direction (not
* changing currentNode where no traversal is possible).
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised if the specified <code>currentNode</code>
* is <code>null</code>.
*/
public Node getCurrentNode();
public void setCurrentNode(Node currentNode)
throws DOMException;
/**
* Moves to and returns the closest visible ancestor node of the current
* node. If the search for parentNode attempts to step upward from the
* TreeWalker's root node, or if it fails to find a visible ancestor
* node, this method retains the current position and returns null.
* @return The new parent node, or null if the current node has no parent
* in the TreeWalker's logical view.
*/
public Node parentNode();
/**
* Moves the <code>TreeWalker</code> to the first child of the current
* node, and returns the new node. If the current node has no children,
* returns <code>null</code>, and retains the current node.
* @return The new node, or <code>null</code> if the current node has no
* children.
*/
public Node firstChild();
/**
* Moves the <code>TreeWalker</code> to the last child of the current
* node, and returns the new node. If the current node has no children,
* returns <code>null</code>, and retains the current node.
* @return The new node, or <code>null</code> if the current node has no
* children.
*/
public Node lastChild();
/**
* Moves the <code>TreeWalker</code> to the previous sibling of the
* current node, and returns the new node. If the current node has no
* previous sibling, returns <code>null</code>, and retains the current
* node.
* @return The new node, or <code>null</code> if the current node has no
* previous sibling.
*/
public Node previousSibling();
/**
* Moves the <code>TreeWalker</code> to the next sibling of the current
* node, and returns the new node. If the current node has no next
* sibling, returns <code>null</code>, and retains the current node.
* @return The new node, or <code>null</code> if the current node has no
* next sibling.
*/
public Node nextSibling();
/**
* Moves the <code>TreeWalker</code> to the previous visible node in
* document order relative to the current node, and returns the new node.
* If the current node has no previous node, or if the search for
* previousNode attempts to step upward from the TreeWalker's root node,
* returns <code>null</code>, and retains the current node.
* @return The new node, or <code>null</code> if the current node has no
* previous node.
*/
public Node previousNode();
/**
* Moves the <code>TreeWalker</code> to the next visible node in document
* order relative to the current node, and returns the new node. If the
* current node has no next node, or if the search for nextNode attempts
* to step upward from the TreeWalker's root node, returns
* <code>null</code>, and retains the current node.
* @return The new node, or <code>null</code> if the current node has no
* next node.
*/
public Node nextNode();
}