001: /*
002: * Copyright 1999-2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: /*
017: * $Id: DTMFilter.java,v 1.4 2004/02/16 23:03:44 minchau Exp $
018: */
019: package org.apache.xml.dtm;
020:
021: /**
022: * Simple filter for doing node tests. Note the semantics of this are
023: * somewhat different that the DOM's NodeFilter.
024: */
025: public interface DTMFilter {
026:
027: // Constants for whatToShow. These are used to set the node type that will
028: // be traversed. These values may be ORed together before being passed to
029: // the DTMIterator.
030:
031: /**
032: * Show all <code>Nodes</code>.
033: */
034: public static final int SHOW_ALL = 0xFFFFFFFF;
035:
036: /**
037: * Show <code>Element</code> nodes.
038: */
039: public static final int SHOW_ELEMENT = 0x00000001;
040:
041: /**
042: * Show <code>Attr</code> nodes. This is meaningful only when creating an
043: * iterator or tree-walker with an attribute node as its
044: * <code>root</code>; in this case, it means that the attribute node
045: * will appear in the first position of the iteration or traversal.
046: * Since attributes are never children of other nodes, they do not
047: * appear when traversing over the main document tree.
048: */
049: public static final int SHOW_ATTRIBUTE = 0x00000002;
050:
051: /**
052: * Show <code>Text</code> nodes.
053: */
054: public static final int SHOW_TEXT = 0x00000004;
055:
056: /**
057: * Show <code>CDATASection</code> nodes.
058: */
059: public static final int SHOW_CDATA_SECTION = 0x00000008;
060:
061: /**
062: * Show <code>EntityReference</code> nodes. Note that if Entity References
063: * have been fully expanded while the tree was being constructed, these
064: * nodes will not appear and this mask has no effect.
065: */
066: public static final int SHOW_ENTITY_REFERENCE = 0x00000010;
067:
068: /**
069: * Show <code>Entity</code> nodes. This is meaningful only when creating
070: * an iterator or tree-walker with an<code> Entity</code> node as its
071: * <code>root</code>; in this case, it means that the <code>Entity</code>
072: * node will appear in the first position of the traversal. Since
073: * entities are not part of the document tree, they do not appear when
074: * traversing over the main document tree.
075: */
076: public static final int SHOW_ENTITY = 0x00000020;
077:
078: /**
079: * Show <code>ProcessingInstruction</code> nodes.
080: */
081: public static final int SHOW_PROCESSING_INSTRUCTION = 0x00000040;
082:
083: /**
084: * Show <code>Comment</code> nodes.
085: */
086: public static final int SHOW_COMMENT = 0x00000080;
087:
088: /**
089: * Show <code>Document</code> nodes. (Of course, as with Attributes
090: * and such, this is meaningful only when the iteration root is the
091: * Document itself, since Document has no parent.)
092: */
093: public static final int SHOW_DOCUMENT = 0x00000100;
094:
095: /**
096: * Show <code>DocumentType</code> nodes.
097: */
098: public static final int SHOW_DOCUMENT_TYPE = 0x00000200;
099:
100: /**
101: * Show <code>DocumentFragment</code> nodes. (Of course, as with
102: * Attributes and such, this is meaningful only when the iteration
103: * root is the Document itself, since DocumentFragment has no parent.)
104: */
105: public static final int SHOW_DOCUMENT_FRAGMENT = 0x00000400;
106:
107: /**
108: * Show <code>Notation</code> nodes. This is meaningful only when creating
109: * an iterator or tree-walker with a <code>Notation</code> node as its
110: * <code>root</code>; in this case, it means that the
111: * <code>Notation</code> node will appear in the first position of the
112: * traversal. Since notations are not part of the document tree, they do
113: * not appear when traversing over the main document tree.
114: */
115: public static final int SHOW_NOTATION = 0x00000800;
116:
117: /**
118:
119: * This bit instructs the iterator to show namespace nodes, which
120: * are modeled by DTM but not by the DOM. Make sure this does not
121: * conflict with {@link org.w3c.dom.traversal.NodeFilter}.
122: * <p>
123: * %REVIEW% Might be safer to start from higher bits and work down,
124: * to leave room for the DOM to expand its set of constants... Or,
125: * possibly, to create a DTM-specific field for these additional bits.
126: */
127: public static final int SHOW_NAMESPACE = 0x00001000;
128:
129: /**
130: * Special bit for filters implementing match patterns starting with
131: * a function. Make sure this does not conflict with
132: * {@link org.w3c.dom.traversal.NodeFilter}.
133: * <p>
134: * %REVIEW% Might be safer to start from higher bits and work down,
135: * to leave room for the DOM to expand its set of constants... Or,
136: * possibly, to create a DTM-specific field for these additional bits.
137: */
138: public static final int SHOW_BYFUNCTION = 0x00010000;
139:
140: /**
141: * Test whether a specified node is visible in the logical view of a
142: * <code>DTMIterator</code>. Normally, this function
143: * will be called by the implementation of <code>DTMIterator</code>;
144: * it is not normally called directly from
145: * user code.
146: *
147: * @param nodeHandle int Handle of the node.
148: * @param whatToShow one of SHOW_XXX values.
149: * @return one of FILTER_ACCEPT, FILTER_REJECT, or FILTER_SKIP.
150: */
151: public short acceptNode(int nodeHandle, int whatToShow);
152:
153: /**
154: * Test whether a specified node is visible in the logical view of a
155: * <code>DTMIterator</code>. Normally, this function
156: * will be called by the implementation of <code>DTMIterator</code>;
157: * it is not normally called directly from
158: * user code.
159: * <p>
160: * TODO: Should this be setNameMatch(expandedName) followed by accept()?
161: * Or will we really be testing a different name at every invocation?
162: *
163: * <p>%REVIEW% Under what circumstances will this be used? The cases
164: * I've considered are just as easy and just about as efficient if
165: * the name test is performed in the DTMIterator... -- Joe</p>
166: *
167: * <p>%REVIEW% Should that 0xFFFF have a mnemonic assigned to it?
168: * Also: This representation is assuming the expanded name is indeed
169: * split into high/low 16-bit halfwords. If we ever change the
170: * balance between namespace and localname bits (eg because we
171: * decide there are many more localnames than namespaces, which is
172: * fairly likely), this is going to break. It might be safer to
173: * encapsulate the details with a makeExpandedName method and make
174: * that responsible for setting up the wildcard version as well.</p>
175: *
176: * @param nodeHandle int Handle of the node.
177: * @param whatToShow one of SHOW_XXX values.
178: * @param expandedName a value defining the exanded name as defined in
179: * the DTM interface. Wild cards will be defined
180: * by 0xFFFF in the namespace and/or localname
181: * portion of the expandedName.
182: * @return one of FILTER_ACCEPT, FILTER_REJECT, or FILTER_SKIP. */
183: public short acceptNode(int nodeHandle, int whatToShow,
184: int expandedName);
185:
186: }
|