NodeTest


1   package net.sf.saxon.pattern;
2   import net.sf.saxon.om.Item;
3   import net.sf.saxon.om.NamePool;
4   import net.sf.saxon.om.NodeInfo;
5   import net.sf.saxon.type.*;
6   import net.sf.saxon.tinytree.TinyTree;
7   
8   import java.io.Serializable  ;
9   import java.util.Set  ;
10  
11  /**
12    * A NodeTest is a simple kind of pattern that enables a context-free test of whether
13    * a node has a particular
14    * name. There are several kinds of node test: a full name test, a prefix test, and an
15    * "any node of a given type" test, an "any node of any type" test, a "no nodes"
16    * test (used, e.g. for "@comment()").
17    *
18    * <p>As well as being used to support XSLT pattern matching, NodeTests act as predicates in
19    * axis steps, and also act as item types for type matching.</p>
20    *
21    * @author Michael H. Kay
22    */
23  
24  public abstract class NodeTest implements ItemType, Serializable   {
25  
26      /**
27       * Test whether a given item conforms to this type. This implements a method of the ItemType interface.
28       * @param item The item to be tested
29       * @return true if the item is an instance of this type; false otherwise
30      */
31  
32      public boolean matchesItem(Item item) {
33          if (item instanceof NodeInfo) {
34              return matches((NodeInfo)item);
35          } else {
36              return false;
37          }
38      }
39  
40      /**
41       * Get the type from which this item type is derived by restriction. This
42       * is the supertype in the XPath type heirarchy, as distinct from the Schema
43       * base type: this means that the supertype of xs:boolean is xdt:anyAtomicType,
44       * whose supertype is item() (rather than xs:anySimpleType).
45       * <p>
46       * In fact the concept of "supertype" is not really well-defined, because the types
47       * form a lattice rather than a hierarchy. The only real requirement on this function
48       * is that it returns a type that strictly subsumes this type, ideally as narrowly
49       * as possible.
50       * @return the supertype, or null if this type is item()
51       */
52  
53      public ItemType getSuperType() {
54          return AnyNodeTest.getInstance();
55          // overridden for AnyNodeTest itself
56      }
57  
58      /**
59      * Determine the default priority of this node test when used on its own as a Pattern
60      */
61  
62      public abstract double getDefaultPriority();
63  
64      /**
65       * Get the primitive item type corresponding to this item type. For item(),
66       * this is Type.ITEM. For node(), it is Type.NODE. For specific node kinds,
67       * it is the value representing the node kind, for example Type.ELEMENT.
68       * For anyAtomicValue it is Type.ATOMIC_VALUE. For numeric it is Type.NUMBER.
69       * For other atomic types it is the primitive type as defined in XML Schema,
70       * except that INTEGER is considered to be a primitive type.
71       */
72  
73      public ItemType getPrimitiveItemType() {
74          int p = getPrimitiveType();
75          if (p == Type.NODE) {
76              return AnyNodeTest.getInstance();
77          } else {
78              return NodeKindTest.makeNodeKindTest(p);
79          }
80      }
81  
82      /**
83       * Get the basic kind of object that this ItemType matches: for a NodeTest, this is the kind of node,
84       * or Type.Node if it matches different kinds of nodes.
85       * @return the node kind matched by this node test
86       */
87  
88      public int getPrimitiveType() {
89          return Type.NODE;
90      }
91  
92      /**
93       * Get the name of the nodes matched by this nodetest, if it matches a specific name.
94       * Return -1 if the node test matches nodes of more than one name
95       */
96  
97      public int getFingerprint() {
98          return -1;
99      }
100 
101     /**
102      * Get the item type of the atomic values that will be produced when an item
103      * of this type is atomized (assuming that atomization succeeds)
104      */
105 
106     public AtomicType getAtomizedItemType() {
107         // This is overridden for a ContentTypeTest
108         return Type.ANY_ATOMIC_TYPE;
109     }
110 
111     /**
112      * Test whether this node test is satisfied by a given node on a TinyTree. The node
113      * must be a document, element, text, comment, or processing instruction node.
114      * This method is provided
115      * so that when navigating a TinyTree a node can be rejected without
116      * actually instantiating a NodeInfo object.
117      * @param tree the TinyTree containing the node
118      * @param nodeNr the number of the node within the TinyTree
119      * @return true if the node matches the NodeTest, otherwise false
120      *
121     */
122 
123     public abstract boolean matches(TinyTree tree, int nodeNr);
124 
125     /**
126      * Test whether this node test is satisfied by a given node. This method is only
127      * fully supported for a subset of NodeTests, because it doesn't provide all the information
128      * needed to evaluate all node tests. In particular (a) it can't be used to evaluate a node
129      * test of the form element(N,T) or schema-element(E) where it is necessary to know whether the
130      * node is nilled, and (b) it can't be used to evaluate a node test of the form
131      * document-node(element(X)). This in practice means that it is used (a) to evaluate the
132      * simple node tests found in the XPath 1.0 subset used in XML Schema, and (b) to evaluate
133      * node tests where the node kind is known to be an attribute.
134      * @param nodeKind The kind of node to be matched
135      * @param fingerprint identifies the expanded name of the node to be matched.
136      *  The value should be -1 for a node with no name.
137      * @param annotation The actual content type of the node
138      *
139     */
140 
141     public abstract boolean matches(int nodeKind, int fingerprint, int annotation);
142 
143     /**
144      * Test whether this node test is satisfied by a given node. This alternative
145      * method is used in the case of nodes where calculating the fingerprint is expensive,
146      * for example DOM or JDOM nodes.
147      * @param node the node to be matched
148      */
149 
150     public abstract boolean matches(NodeInfo node);
151 
152     /**
153      * Get a mask indicating which kinds of nodes this NodeTest can match. This is a combination
154      * of bits: 1<<Type.ELEMENT for element nodes, 1<<Type.TEXT for text nodes, and so on.
155      */
156 
157     public abstract int getNodeKindMask();
158 
159     /**
160      * Get the content type allowed by this NodeTest (that is, the type annotation of the matched nodes).
161      * Return AnyType if there are no restrictions. The default implementation returns AnyType.
162      */
163 
164     public SchemaType getContentType() {
165         return AnyType.getInstance();
166     }
167 
168     /**
169      * Get the set of node names allowed by this NodeTest. This is returned as a set of Integer fingerprints.
170      * A null value indicates that all names are permitted (i.e. that there are no constraints on the node name.
171      * The default implementation returns null.
172      */
173 
174     public Set   getRequiredNodeNames() {
175         return null;
176     }
177 
178 
179     /**
180      * Display the type descriptor for diagnostics
181      */
182 
183     public String   toString(NamePool pool) {
184         return toString();
185     }
186 
187 }
188 
189 //
190 // The contents of this file are subject to the Mozilla Public License Version 1.0 (the "License");
191 // you may not use this file except in compliance with the License. You may obtain a copy of the
192 // License at http://www.mozilla.org/MPL/
193 //
194 // Software distributed under the License is distributed on an "AS IS" basis,
195 // WITHOUT WARRANTY OF ANY KIND, either express or implied.
196 // See the License for the specific language governing rights and limitations under the License.
197 //
198 // The Original Code is: all this file.
199 //
200 // The Initial Developer of the Original Code is Michael H. Kay.
201 //
202 // Portions created by (your name) are Copyright (C) (your legal entity). All Rights Reserved.
203 //
204 // Contributor(s): none.
205 //
206
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags