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