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 com.sun.org.apache.xml.internal.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. }