View Javadoc
1   /*
2    * reserved comment block
3    * DO NOT REMOVE OR ALTER!
4    */
5   /*
6    * Copyright 1999-2004 The Apache Software Foundation.
7    *
8    * Licensed under the Apache License, Version 2.0 (the "License");
9    * you may not use this file except in compliance with the License.
10   * You may obtain a copy of the License at
11   *
12   *     http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing, software
15   * distributed under the License is distributed on an "AS IS" BASIS,
16   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17   * See the License for the specific language governing permissions and
18   * limitations under the License.
19   */
20  /*
21   * $Id: DTMFilter.java,v 1.2.4.1 2005/09/15 08:14:53 suresh_emailid Exp $
22   */
23  package com.sun.org.apache.xml.internal.dtm;
24  
25  /**
26   * Simple filter for doing node tests.  Note the semantics of this are
27   * somewhat different that the DOM's NodeFilter.
28   */
29  public interface DTMFilter
30  {
31  
32    // Constants for whatToShow.  These are used to set the node type that will
33    // be traversed. These values may be ORed together before being passed to
34    // the DTMIterator.
35  
36    /**
37     * Show all <code>Nodes</code>.
38     */
39    public static final int SHOW_ALL = 0xFFFFFFFF;
40  
41    /**
42     * Show <code>Element</code> nodes.
43     */
44    public static final int SHOW_ELEMENT = 0x00000001;
45  
46    /**
47     * Show <code>Attr</code> nodes. This is meaningful only when creating an
48     * iterator or tree-walker with an attribute node as its
49     * <code>root</code>; in this case, it means that the attribute node
50     * will appear in the first position of the iteration or traversal.
51     * Since attributes are never children of other nodes, they do not
52     * appear when traversing over the main document tree.
53     */
54    public static final int SHOW_ATTRIBUTE = 0x00000002;
55  
56    /**
57     * Show <code>Text</code> nodes.
58     */
59    public static final int SHOW_TEXT = 0x00000004;
60  
61    /**
62     * Show <code>CDATASection</code> nodes.
63     */
64    public static final int SHOW_CDATA_SECTION = 0x00000008;
65  
66    /**
67     * Show <code>EntityReference</code> nodes. Note that if Entity References
68     * have been fully expanded while the tree was being constructed, these
69     * nodes will not appear and this mask has no effect.
70     */
71    public static final int SHOW_ENTITY_REFERENCE = 0x00000010;
72  
73    /**
74     * Show <code>Entity</code> nodes. This is meaningful only when creating
75     * an iterator or tree-walker with an<code> Entity</code> node as its
76     * <code>root</code>; in this case, it means that the <code>Entity</code>
77     *  node will appear in the first position of the traversal. Since
78     * entities are not part of the document tree, they do not appear when
79     * traversing over the main document tree.
80     */
81    public static final int SHOW_ENTITY = 0x00000020;
82  
83    /**
84     * Show <code>ProcessingInstruction</code> nodes.
85     */
86    public static final int SHOW_PROCESSING_INSTRUCTION = 0x00000040;
87  
88    /**
89     * Show <code>Comment</code> nodes.
90     */
91    public static final int SHOW_COMMENT = 0x00000080;
92  
93    /**
94     * Show <code>Document</code> nodes. (Of course, as with Attributes
95     * and such, this is meaningful only when the iteration root is the
96     * Document itself, since Document has no parent.)
97     */
98    public static final int SHOW_DOCUMENT = 0x00000100;
99  
100   /**
101    * Show <code>DocumentType</code> nodes.
102    */
103   public static final int SHOW_DOCUMENT_TYPE = 0x00000200;
104 
105   /**
106    * Show <code>DocumentFragment</code> nodes. (Of course, as with
107    * Attributes and such, this is meaningful only when the iteration
108    * root is the Document itself, since DocumentFragment has no parent.)
109    */
110   public static final int SHOW_DOCUMENT_FRAGMENT = 0x00000400;
111 
112   /**
113    * Show <code>Notation</code> nodes. This is meaningful only when creating
114    * an iterator or tree-walker with a <code>Notation</code> node as its
115    * <code>root</code>; in this case, it means that the
116    * <code>Notation</code> node will appear in the first position of the
117    * traversal. Since notations are not part of the document tree, they do
118    * not appear when traversing over the main document tree.
119    */
120   public static final int SHOW_NOTATION = 0x00000800;
121 
122   /**
123 
124    * This bit instructs the iterator to show namespace nodes, which
125    * are modeled by DTM but not by the DOM.  Make sure this does not
126    * conflict with {@link org.w3c.dom.traversal.NodeFilter}.
127    * <p>
128    * %REVIEW% Might be safer to start from higher bits and work down,
129    * to leave room for the DOM to expand its set of constants... Or,
130    * possibly, to create a DTM-specific field for these additional bits.
131    */
132   public static final int SHOW_NAMESPACE = 0x00001000;
133 
134   /**
135    * Special bit for filters implementing match patterns starting with
136    * a function.  Make sure this does not conflict with
137    * {@link org.w3c.dom.traversal.NodeFilter}.
138    * <p>
139    * %REVIEW% Might be safer to start from higher bits and work down,
140    * to leave room for the DOM to expand its set of constants... Or,
141    * possibly, to create a DTM-specific field for these additional bits.
142    */
143   public static final int SHOW_BYFUNCTION = 0x00010000;
144 
145   /**
146    * Test whether a specified node is visible in the logical view of a
147    * <code>DTMIterator</code>. Normally, this function
148    * will be called by the implementation of <code>DTMIterator</code>;
149    * it is not normally called directly from
150    * user code.
151    *
152    * @param nodeHandle int Handle of the node.
153    * @param whatToShow one of SHOW_XXX values.
154    * @return one of FILTER_ACCEPT, FILTER_REJECT, or FILTER_SKIP.
155    */
156   public short acceptNode(int nodeHandle, int whatToShow);
157 
158   /**
159    * Test whether a specified node is visible in the logical view of a
160    * <code>DTMIterator</code>. Normally, this function
161    * will be called by the implementation of <code>DTMIterator</code>;
162    * it is not normally called directly from
163    * user code.
164    * <p>
165    * TODO: Should this be setNameMatch(expandedName) followed by accept()?
166    * Or will we really be testing a different name at every invocation?
167    *
168    * <p>%REVIEW% Under what circumstances will this be used? The cases
169    * I've considered are just as easy and just about as efficient if
170    * the name test is performed in the DTMIterator... -- Joe</p>
171    *
172    * <p>%REVIEW% Should that 0xFFFF have a mnemonic assigned to it?
173    * Also: This representation is assuming the expanded name is indeed
174    * split into high/low 16-bit halfwords. If we ever change the
175    * balance between namespace and localname bits (eg because we
176    * decide there are many more localnames than namespaces, which is
177    * fairly likely), this is going to break. It might be safer to
178    * encapsulate the details with a makeExpandedName method and make
179    * that responsible for setting up the wildcard version as well.</p>
180    *
181    * @param nodeHandle int Handle of the node.
182    * @param whatToShow one of SHOW_XXX values.
183    * @param expandedName a value defining the exanded name as defined in
184    *                     the DTM interface.  Wild cards will be defined
185    *                     by 0xFFFF in the namespace and/or localname
186    *                     portion of the expandedName.
187    * @return one of FILTER_ACCEPT, FILTER_REJECT, or FILTER_SKIP.  */
188   public short acceptNode(int nodeHandle, int whatToShow, int expandedName);
189 
190 }