DTMFilter


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