com.sun.org.apache.xml.internal.dtm.DTMFilter Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*
*
* This file incorporates work covered by the following copyright and
* permission notice:
*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
* $Id: DTMFilter.java,v 1.8 2010-11-01 04:34:34 joehw Exp $
*/
package com.sun.org.apache.xml.internal.dtm;
/**
* Simple filter for doing node tests. Note the semantics of this are
* somewhat different that the DOM's NodeFilter.
*/
public interface DTMFilter
{
// Constants for whatToShow. These are used to set the node type that will
// be traversed. These values may be ORed together before being passed to
// the DTMIterator.
/**
* Show all Nodes.
*/
public static final int SHOW_ALL = 0xFFFFFFFF;
/**
* Show Element nodes.
*/
public static final int SHOW_ELEMENT = 0x00000001;
/**
* Show Attr nodes. This is meaningful only when creating an
* iterator or tree-walker with an attribute node as its
* root; in this case, it means that the attribute node
* will appear in the first position of the iteration or traversal.
* Since attributes are never children of other nodes, they do not
* appear when traversing over the main document tree.
*/
public static final int SHOW_ATTRIBUTE = 0x00000002;
/**
* Show Text nodes.
*/
public static final int SHOW_TEXT = 0x00000004;
/**
* Show CDATASection nodes.
*/
public static final int SHOW_CDATA_SECTION = 0x00000008;
/**
* Show EntityReference nodes. Note that if Entity References
* have been fully expanded while the tree was being constructed, these
* nodes will not appear and this mask has no effect.
*/
public static final int SHOW_ENTITY_REFERENCE = 0x00000010;
/**
* Show Entity nodes. This is meaningful only when creating
* an iterator or tree-walker with an Entity node as its
* root; in this case, it means that the Entity
* node will appear in the first position of the traversal. Since
* entities are not part of the document tree, they do not appear when
* traversing over the main document tree.
*/
public static final int SHOW_ENTITY = 0x00000020;
/**
* Show ProcessingInstruction nodes.
*/
public static final int SHOW_PROCESSING_INSTRUCTION = 0x00000040;
/**
* Show Comment nodes.
*/
public static final int SHOW_COMMENT = 0x00000080;
/**
* Show Document nodes. (Of course, as with Attributes
* and such, this is meaningful only when the iteration root is the
* Document itself, since Document has no parent.)
*/
public static final int SHOW_DOCUMENT = 0x00000100;
/**
* Show DocumentType nodes.
*/
public static final int SHOW_DOCUMENT_TYPE = 0x00000200;
/**
* Show DocumentFragment nodes. (Of course, as with
* Attributes and such, this is meaningful only when the iteration
* root is the Document itself, since DocumentFragment has no parent.)
*/
public static final int SHOW_DOCUMENT_FRAGMENT = 0x00000400;
/**
* Show Notation nodes. This is meaningful only when creating
* an iterator or tree-walker with a Notation node as its
* root; in this case, it means that the
* Notation node will appear in the first position of the
* traversal. Since notations are not part of the document tree, they do
* not appear when traversing over the main document tree.
*/
public static final int SHOW_NOTATION = 0x00000800;
/**
* This bit instructs the iterator to show namespace nodes, which
* are modeled by DTM but not by the DOM. Make sure this does not
* conflict with {@link org.w3c.dom.traversal.NodeFilter}.
*
* %REVIEW% Might be safer to start from higher bits and work down,
* to leave room for the DOM to expand its set of constants... Or,
* possibly, to create a DTM-specific field for these additional bits.
*/
public static final int SHOW_NAMESPACE = 0x00001000;
/**
* Special bit for filters implementing match patterns starting with
* a function. Make sure this does not conflict with
* {@link org.w3c.dom.traversal.NodeFilter}.
*
* %REVIEW% Might be safer to start from higher bits and work down,
* to leave room for the DOM to expand its set of constants... Or,
* possibly, to create a DTM-specific field for these additional bits.
*/
public static final int SHOW_BYFUNCTION = 0x00010000;
/**
* Test whether a specified node is visible in the logical view of a
* DTMIterator. Normally, this function
* will be called by the implementation of DTMIterator;
* it is not normally called directly from
* user code.
*
* @param nodeHandle int Handle of the node.
* @param whatToShow one of SHOW_XXX values.
* @return one of FILTER_ACCEPT, FILTER_REJECT, or FILTER_SKIP.
*/
public short acceptNode(int nodeHandle, int whatToShow);
/**
* Test whether a specified node is visible in the logical view of a
* DTMIterator. Normally, this function
* will be called by the implementation of DTMIterator;
* it is not normally called directly from
* user code.
*
* TODO: Should this be setNameMatch(expandedName) followed by accept()?
* Or will we really be testing a different name at every invocation?
*
*
%REVIEW% Under what circumstances will this be used? The cases
* I've considered are just as easy and just about as efficient if
* the name test is performed in the DTMIterator... -- Joe
*
* %REVIEW% Should that 0xFFFF have a mnemonic assigned to it?
* Also: This representation is assuming the expanded name is indeed
* split into high/low 16-bit halfwords. If we ever change the
* balance between namespace and localname bits (eg because we
* decide there are many more localnames than namespaces, which is
* fairly likely), this is going to break. It might be safer to
* encapsulate the details with a makeExpandedName method and make
* that responsible for setting up the wildcard version as well.
*
* @param nodeHandle int Handle of the node.
* @param whatToShow one of SHOW_XXX values.
* @param expandedName a value defining the exanded name as defined in
* the DTM interface. Wild cards will be defined
* by 0xFFFF in the namespace and/or localname
* portion of the expandedName.
* @return one of FILTER_ACCEPT, FILTER_REJECT, or FILTER_SKIP. */
public short acceptNode(int nodeHandle, int whatToShow, int expandedName);
}