Expression


1   package net.sf.saxon.expr;
2   import net.sf.saxon.om.Item;
3   import net.sf.saxon.om.NamePool;
4   import net.sf.saxon.om.SequenceIterator;
5   import net.sf.saxon.trans.XPathException;
6   import net.sf.saxon.type.ItemType;
7   import net.sf.saxon.type.SchemaType;
8   
9   import java.io.PrintStream  ;
10  import java.io.Serializable  ;
11  import java.util.Iterator  ;
12  
13  /**
14   * Interface supported by an XPath expression. This includes both compile-time
15   * and run-time methods.
16   */
17  
18  public interface Expression extends Serializable   {
19  
20      public static final int EVALUATE_METHOD = 1;
21      public static final int ITERATE_METHOD = 2;
22      public static final int PROCESS_METHOD = 4;
23  
24      /**
25       * An implementation of Expression must provide at least one of the methods evaluateItem(), iterate(), or process().
26       * This method indicates which of these methods is provided directly. The other methods will always be available
27       * indirectly, using an implementation that relies on one of the other methods.
28       */
29  
30      public int getImplementationMethod();
31  
32      /**
33       * Simplify an expression. This performs any static optimization (by rewriting the expression
34       * as a different expression). The default implementation does nothing.
35       *
36       * @exception net.sf.saxon.trans.StaticError if an error is discovered during expression
37       *     rewriting
38       * @return the simplified expression
39       */
40  
41      Expression simplify(StaticContext env) throws XPathException;
42  
43      /**
44       * Perform type checking of an expression and its subexpressions.
45       *
46       * <p>This checks statically that the operands of the expression have
47       * the correct type; if necessary it generates code to do run-time type checking or type
48       * conversion. A static type error is reported only if execution cannot possibly succeed, that
49       * is, if a run-time type error is inevitable. The call may return a modified form of the expression.</p>
50       *
51       * <p>This method is called after all references to functions and variables have been resolved
52       * to the declaration of the function or variable. However, the types of such functions and
53       * variables may not be accurately known if they have not been explicitly declared.</p>
54       *
55       * @param env the static context of the expression
56       * @param contextItemType the static type of "." at the point where this expression is invoked.
57       * The parameter is set to null if it is known statically that the context item will be undefined.
58       * If the type of the context item is not known statically, the argument is set to
59       * {@link net.sf.saxon.type.Type#ITEM_TYPE}
60       * @exception net.sf.saxon.trans.StaticError if an error is discovered during this phase
61       *     (typically a type error)
62       * @return the original expression, rewritten to perform necessary
63       *     run-time type checks, and to perform other type-related
64       *     optimizations
65       */
66  
67      Expression typeCheck(StaticContext env, ItemType contextItemType) throws XPathException;
68  
69  
70      /**
71       * Perform optimisation of an expression and its subexpressions.
72       *
73       * <p>This method is called after all references to functions and variables have been resolved
74       * to the declaration of the function or variable, and after all type checking has been done.</p>
75       * @param opt the optimizer in use. This provides access to supporting functions; it also allows
76       * different optimization strategies to be used in different circumstances.
77       * @param env the static context of the expression
78       * @param contextItemType the static type of "." at the point where this expression is invoked.
79       * The parameter is set to null if it is known statically that the context item will be undefined.
80       * If the type of the context item is not known statically, the argument is set to
81       * {@link net.sf.saxon.type.Type#ITEM_TYPE}
82       * @exception net.sf.saxon.trans.StaticError if an error is discovered during this phase
83       *     (typically a type error)
84       * @return the original expression, rewritten if appropriate to optimize execution
85       */
86  
87      Expression optimize(Optimizer opt, StaticContext env, ItemType contextItemType) throws XPathException;
88  
89  
90      /**
91       * Offer promotion for this subexpression. The offer will be accepted if the subexpression
92       * is not dependent on the factors (e.g. the context item) identified in the PromotionOffer.
93       * By default the offer is not accepted - this is appropriate in the case of simple expressions
94       * such as constant values and variable references where promotion would give no performance
95       * advantage. This method is always called at compile time.
96       *
97       * @param offer details of the offer, for example the offer to move
98       *     expressions that don't depend on the context to an outer level in
99       *     the containing expression
100      * @exception net.sf.saxon.trans.XPathException if any error is detected
101      * @return if the offer is not accepted, return this expression unchanged.
102      *      Otherwise return the result of rewriting the expression to promote
103      *      this subexpression
104      */
105 
106     Expression promote(PromotionOffer offer) throws XPathException;
107 
108     /**
109      * Get the static properties of this expression (other than its type). The result is
110      * bit-signficant. These properties are used for optimizations. In general, if
111      * property bit is set, it is true, but if it is unset, the value is unknown.
112      *
113      * @return a set of flags indicating static properties of this expression
114      */
115 
116     int getSpecialProperties();
117 
118     /**
119      * <p>Determine the static cardinality of the expression. This establishes how many items
120      * there will be in the result of the expression, at compile time (i.e., without
121      * actually evaluating the result.</p>
122      *
123      * <p>This method should always return a result, though it may be the best approximation
124      * that is available at the time.</p>
125      *
126      * @return one of the values {@link StaticProperty#ALLOWS_ONE},
127      *     {@link StaticProperty#ALLOWS_ZERO_OR_MORE}, {@link StaticProperty#ALLOWS_ZERO_OR_ONE},
128      *     {@link StaticProperty#ALLOWS_ONE_OR_MORE}, {@link StaticProperty#EMPTY}. This default
129      *     implementation returns ZERO_OR_MORE (which effectively gives no
130      *     information).
131      */
132 
133     int getCardinality();
134 
135     /**
136      * Determine the data type of the expression, if possible. All expression return
137      * sequences, in general; this method determines the type of the items within the
138      * sequence, assuming that (a) this is known in advance, and (b) it is the same for
139      * all items in the sequence.
140      *
141      * <p>This method should always return a result, though it may be the best approximation
142      * that is available at the time.</p>
143      *
144      * @return a value such as Type.STRING, Type.BOOLEAN, Type.NUMBER,
145      *     Type.NODE, or Type.ITEM (meaning not known at compile time)
146      */
147 
148     ItemType getItemType();
149 
150     /**
151      * Determine which aspects of the context the expression depends on. The result is
152      * a bitwise-or'ed value composed from constants such as {@link StaticProperty#DEPENDS_ON_CONTEXT_ITEM} and
153      * {@link StaticProperty#DEPENDS_ON_CURRENT_ITEM}. The default implementation combines the intrinsic
154      * dependencies of this expression with the dependencies of the subexpressions,
155      * computed recursively. This is overridden for expressions such as FilterExpression
156      * where a subexpression's dependencies are not necessarily inherited by the parent
157      * expression.
158      *
159      * @return a set of bit-significant flags identifying the dependencies of
160      *     the expression
161      */
162 
163     int getDependencies();
164 
165     /**
166      * Get the immediate sub-expressions of this expression. Default implementation
167      * returns a zero-length array, appropriate for an expression that has no
168      * sub-expressions.
169      * @return an iterator containing the sub-expressions of this expression
170      */
171 
172     Iterator iterateSubExpressions();
173 
174     /**
175      * Get the container that immediately contains this expression. This method
176      * returns null for an outermost expression; it also return null in the case
177      * of literal values. For an XPath expression occurring within an XSLT stylesheet,
178      * this method returns the XSLT instruction containing the XPath expression.
179      * @return the expression that contains this expression, if known; return null
180      * if there is no containing expression or if the containing expression is unknown.
181      */
182 
183     Container getParentExpression();
184 
185     /**
186      * Test if this expression is the same as another expression.
187      * (Note, returns false to indicate "don't know": our tests are rather limited)
188      *
189      * @param other the expression to be compared with this one
190      * @return true if this expression is known to be equivalent to the other
191      *     expression (that is, to deliver the same result in all
192      *     circumstances, assuming the context is the same)
193      */
194 
195     //boolean equals(Object other);
196 
197 
198     /**
199      * Evaluate an expression as a single item. This always returns either a single Item or
200      * null (denoting the empty sequence). No conversion is done. This method should not be
201      * used unless the static type of the expression is a subtype of "item" or "item?": that is,
202      * it should not be called if the expression may return a sequence. There is no guarantee that
203      * this condition will be detected.
204      *
205      * @param context The context in which the expression is to be evaluated
206      * @exception XPathException if any dynamic error occurs evaluating the
207      *     expression
208      * @return the node or atomic value that results from evaluating the
209      *     expression; or null to indicate that the result is an empty
210      *     sequence
211      */
212 
213     Item evaluateItem(XPathContext context) throws XPathException;
214 
215     /**
216      * Return an Iterator to iterate over the values of a sequence. The value of every
217      * expression can be regarded as a sequence, so this method is supported for all
218      * expressions. This default implementation handles iteration for expressions that
219      * return singleton values: for non-singleton expressions, the subclass must
220      * provide its own implementation.
221      *
222      * @exception net.sf.saxon.trans.XPathException if any dynamic error occurs evaluating the
223      *     expression
224      * @param context supplies the context for evaluation
225      * @return a SequenceIterator that can be used to iterate over the result
226      *     of the expression
227      */
228 
229     SequenceIterator iterate(XPathContext context) throws XPathException;
230 
231     /**
232      * Get the effective boolean value of the expression. This returns false if the value
233      * is the empty sequence, a zero-length string, a number equal to zero, or the boolean
234      * false. Otherwise it returns true.
235      *
236      * @param context The context in which the expression is to be evaluated
237      * @exception net.sf.saxon.trans.XPathException if any dynamic error occurs evaluating the
238      *     expression
239      * @return the effective boolean value
240      */
241 
242     boolean effectiveBooleanValue(XPathContext context) throws XPathException;
243 
244    /**
245      * Evaluate an expression as a String. This function must only be called in contexts
246      * where it is known that the expression will return a single string (or where an empty sequence
247      * is to be treated as a zero-length string). Implementations should not attempt to convert
248      * the result to a string, other than converting () to "". This method is used mainly to
249      * evaluate expressions produced by compiling an attribute value template.
250      *
251      * @exception XPathException if any dynamic error occurs evaluating the
252      *     expression
253      * @exception ClassCastException if the result type of the
254      *     expression is not xs:string?
255      * @param context The context in which the expression is to be evaluated
256      * @return the value of the expression, evaluated in the current context.
257      *     The expression must return a string or (); if the value of the
258      *     expression is (), this method returns "".
259      */
260 
261     public String   evaluateAsString(XPathContext context) throws XPathException;
262 
263     /**
264     * Process the instruction, without returning any tail calls
265     * @param context The dynamic context, giving access to the current node,
266     * the current variables, etc.
267     */
268 
269     public void process(XPathContext context) throws XPathException;
270 
271     /**
272      * Diagnostic print of expression structure. The expression is written to the System.err
273      * output stream
274      *
275      * @param level indentation level for this expression
276      * @param pool NamePool used to expand any names appearing in the expression
277      * @param out Output destination
278      */
279 
280     public void display(int level, NamePool pool, PrintStream   out);
281 
282     /**
283      * Check statically that the results of the expression are capable of constructing the content
284      * of a given schema type.
285      * @param parentType The schema type
286      * @param env the static context
287      * @param whole true if this expression is expected to make the whole content of the type, false
288      * if it is expected to make up only a part
289      * @throws XPathException if the expression doesn't match the required content type
290      */
291 
292     public void checkPermittedContents(SchemaType parentType, StaticContext env, boolean whole) throws XPathException;
293 }
294 //
295 // The contents of this file are subject to the Mozilla Public License Version 1.0 (the "License");
296 // you may not use this file except in compliance with the License. You may obtain a copy of the
297 // License at http://www.mozilla.org/MPL/
298 //
299 // Software distributed under the License is distributed on an "AS IS" basis,
300 // WITHOUT WARRANTY OF ANY KIND, either express or implied.
301 // See the License for the specific language governing rights and limitations under the License.
302 //
303 // The Original Code is: all this file.
304 //
305 // The Initial Developer of the Original Code is Michael H. Kay.
306 //
307 // Portions created by (your name) are Copyright (C) (your legal entity). All Rights Reserved.
308 //
309 // Contributor(s): none.
310 //
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags