1. /*

  2.  * The Apache Software License, Version 1.1

  3.  *

  4.  *

  5.  * Copyright (c) 1999 The Apache Software Foundation.  All rights 

  6.  * reserved.

  7.  *

  8.  * Redistribution and use in source and binary forms, with or without

  9.  * modification, are permitted provided that the following conditions

  10.  * are met:

  11.  *

  12.  * 1. Redistributions of source code must retain the above copyright

  13.  *    notice, this list of conditions and the following disclaimer. 

  14.  *

  15.  * 2. Redistributions in binary form must reproduce the above copyright

  16.  *    notice, this list of conditions and the following disclaimer in

  17.  *    the documentation and/or other materials provided with the

  18.  *    distribution.

  19.  *

  20.  * 3. The end-user documentation included with the redistribution,

  21.  *    if any, must include the following acknowledgment:  

  22.  *       "This product includes software developed by the

  23.  *        Apache Software Foundation (http://www.apache.org/)."

  24.  *    Alternately, this acknowledgment may appear in the software itself,

  25.  *    if and wherever such third-party acknowledgments normally appear.

  26.  *

  27.  * 4. The names "Xalan" and "Apache Software Foundation" must

  28.  *    not be used to endorse or promote products derived from this

  29.  *    software without prior written permission. For written 

  30.  *    permission, please contact apache@apache.org.

  31.  *

  32.  * 5. Products derived from this software may not be called "Apache",

  33.  *    nor may "Apache" appear in their name, without prior written

  34.  *    permission of the Apache Software Foundation.

  35.  *

  36.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED

  37.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES

  38.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

  39.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR

  40.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

  41.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

  42.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF

  43.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND

  44.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

  45.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT

  46.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

  47.  * SUCH DAMAGE.

  48.  * ====================================================================

  49.  *

  50.  * This software consists of voluntary contributions made by many

  51.  * individuals on behalf of the Apache Software Foundation and was

  52.  * originally based on software copyright (c) 1999, Lotus

  53.  * Development Corporation., http://www.lotus.com.  For more

  54.  * information on the Apache Software Foundation, please see

  55.  * <http://www.apache.org/>.

  56.  */

  57. package org.apache.xml.dtm;

  58. 

  59. /**

  60.  * Simple filter for doing node tests.  Note the semantics of this are

  61.  * somewhat different that the DOM's NodeFilter.

  62.  */

  63. public interface DTMFilter

  64. {

  65. 

  66.   // Constants for whatToShow.  These are used to set the node type that will 

  67.   // be traversed. These values may be ORed together before being passed to

  68.   // the DTMIterator.

  69. 

  70.   /**

  71.    * Show all <code>Nodes</code>.

  72.    */

  73.   public static final int SHOW_ALL = 0xFFFFFFFF;

  74. 

  75.   /**

  76.    * Show <code>Element</code> nodes.

  77.    */

  78.   public static final int SHOW_ELEMENT = 0x00000001;

  79. 

  80.   /**

  81.    * Show <code>Attr</code> nodes. This is meaningful only when creating an

  82.    * iterator or tree-walker with an attribute node as its

  83.    * <code>root</code> in this case, it means that the attribute node

  84.    * will appear in the first position of the iteration or traversal.

  85.    * Since attributes are never children of other nodes, they do not

  86.    * appear when traversing over the main document tree.

  87.    */

  88.   public static final int SHOW_ATTRIBUTE = 0x00000002;

  89. 

  90.   /**

  91.    * Show <code>Text</code> nodes.

  92.    */

  93.   public static final int SHOW_TEXT = 0x00000004;

  94. 

  95.   /**

  96.    * Show <code>CDATASection</code> nodes.

  97.    */

  98.   public static final int SHOW_CDATA_SECTION = 0x00000008;

  99. 

  100.   /**

  101.    * Show <code>EntityReference</code> nodes. Note that if Entity References

  102.    * have been fully expanded while the tree was being constructed, these

  103.    * nodes will not appear and this mask has no effect.

  104.    */

  105.   public static final int SHOW_ENTITY_REFERENCE = 0x00000010;

  106. 

  107.   /**

  108.    * Show <code>Entity</code> nodes. This is meaningful only when creating

  109.    * an iterator or tree-walker with an<code> Entity</code> node as its

  110.    * <code>root</code> in this case, it means that the <code>Entity</code>

  111.    *  node will appear in the first position of the traversal. Since

  112.    * entities are not part of the document tree, they do not appear when

  113.    * traversing over the main document tree.

  114.    */

  115.   public static final int SHOW_ENTITY = 0x00000020;

  116. 

  117.   /**

  118.    * Show <code>ProcessingInstruction</code> nodes.

  119.    */

  120.   public static final int SHOW_PROCESSING_INSTRUCTION = 0x00000040;

  121. 

  122.   /**

  123.    * Show <code>Comment</code> nodes.

  124.    */

  125.   public static final int SHOW_COMMENT = 0x00000080;

  126. 

  127.   /**

  128.    * Show <code>Document</code> nodes. (Of course, as with Attributes

  129.    * and such, this is meaningful only when the iteration root is the

  130.    * Document itself, since Document has no parent.)

  131.    */

  132.   public static final int SHOW_DOCUMENT = 0x00000100;

  133. 

  134.   /**

  135.    * Show <code>DocumentType</code> nodes. 

  136.    */

  137.   public static final int SHOW_DOCUMENT_TYPE = 0x00000200;

  138. 

  139.   /**

  140.    * Show <code>DocumentFragment</code> nodes. (Of course, as with

  141.    * Attributes and such, this is meaningful only when the iteration

  142.    * root is the Document itself, since DocumentFragment has no parent.)

  143.    */

  144.   public static final int SHOW_DOCUMENT_FRAGMENT = 0x00000400;

  145. 

  146.   /**

  147.    * Show <code>Notation</code> nodes. This is meaningful only when creating

  148.    * an iterator or tree-walker with a <code>Notation</code> node as its

  149.    * <code>root</code> in this case, it means that the

  150.    * <code>Notation</code> node will appear in the first position of the

  151.    * traversal. Since notations are not part of the document tree, they do

  152.    * not appear when traversing over the main document tree.

  153.    */

  154.   public static final int SHOW_NOTATION = 0x00000800;

  155.   

  156.   /**

  157. 

  158.    * This bit instructs the iterator to show namespace nodes, which

  159.    * are modeled by DTM but not by the DOM.  Make sure this does not

  160.    * conflict with {@link org.w3c.dom.traversal.NodeFilter}.

  161.    * <p>

  162.    * %REVIEW% Might be safer to start from higher bits and work down,

  163.    * to leave room for the DOM to expand its set of constants... Or,

  164.    * possibly, to create a DTM-specific field for these additional bits.

  165.    */

  166.   public static final int SHOW_NAMESPACE = 0x00001000;

  167. 

  168.   /**

  169.    * Special bit for filters implementing match patterns starting with

  170.    * a function.  Make sure this does not conflict with

  171.    * {@link org.w3c.dom.traversal.NodeFilter}.

  172.    * <p>

  173.    * %REVIEW% Might be safer to start from higher bits and work down,

  174.    * to leave room for the DOM to expand its set of constants... Or,

  175.    * possibly, to create a DTM-specific field for these additional bits.

  176.    */

  177.   public static final int SHOW_BYFUNCTION = 0x00010000;

  178. 

  179.   /**

  180.    * Test whether a specified node is visible in the logical view of a

  181.    * <code>DTMIterator</code>. Normally, this function

  182.    * will be called by the implementation of <code>DTMIterator</code> 

  183.    * it is not normally called directly from

  184.    * user code.

  185.    * 

  186.    * @param nodeHandle int Handle of the node.

  187.    * @param whatToShow one of SHOW_XXX values.

  188.    * @return one of FILTER_ACCEPT, FILTER_REJECT, or FILTER_SKIP.

  189.    */

  190.   public short acceptNode(int nodeHandle, int whatToShow);

  191.   

  192.   /**

  193.    * Test whether a specified node is visible in the logical view of a

  194.    * <code>DTMIterator</code>. Normally, this function

  195.    * will be called by the implementation of <code>DTMIterator</code> 

  196.    * it is not normally called directly from

  197.    * user code.

  198.    * <p>

  199.    * TODO: Should this be setNameMatch(expandedName) followed by accept()?

  200.    * Or will we really be testing a different name at every invocation?

  201.    * 

  202.    * <p>%REVIEW% Under what circumstances will this be used? The cases

  203.    * I've considered are just as easy and just about as efficient if

  204.    * the name test is performed in the DTMIterator... -- Joe</p>

  205.    * 

  206.    * <p>%REVIEW% Should that 0xFFFF have a mnemonic assigned to it?

  207.    * Also: This representation is assuming the expanded name is indeed

  208.    * split into high/low 16-bit halfwords. If we ever change the

  209.    * balance between namespace and localname bits (eg because we

  210.    * decide there are many more localnames than namespaces, which is

  211.    * fairly likely), this is going to break. It might be safer to

  212.    * encapsulate the details with a makeExpandedName method and make

  213.    * that responsible for setting up the wildcard version as well.</p>

  214.    * 

  215.    * @param nodeHandle int Handle of the node.

  216.    * @param whatToShow one of SHOW_XXX values.

  217.    * @param expandedName a value defining the exanded name as defined in 

  218.    *                     the DTM interface.  Wild cards will be defined 

  219.    *                     by 0xFFFF in the namespace and/or localname

  220.    *			 portion of the expandedName.

  221.    * @return one of FILTER_ACCEPT, FILTER_REJECT, or FILTER_SKIP.  */

  222.   public short acceptNode(int nodeHandle, int whatToShow, int expandedName);

  223.  

  224. }