001: package net.sf.saxon.expr;
002:
003: import net.sf.saxon.om.Item;
004: import net.sf.saxon.om.NamePool;
005: import net.sf.saxon.om.SequenceIterator;
006: import net.sf.saxon.trans.XPathException;
007: import net.sf.saxon.type.ItemType;
008: import net.sf.saxon.type.SchemaType;
009: import net.sf.saxon.type.TypeHierarchy;
010:
011: import java.io.PrintStream;
012: import java.io.Serializable;
013: import java.util.Iterator;
014:
015: /**
016: * Interface supported by an XPath expression. This includes both compile-time
017: * and run-time methods.
018: */
019:
020: public interface Expression extends Serializable {
021:
022: public static final int EVALUATE_METHOD = 1;
023: public static final int ITERATE_METHOD = 2;
024: public static final int PROCESS_METHOD = 4;
025:
026: /**
027: * An implementation of Expression must provide at least one of the methods evaluateItem(), iterate(), or process().
028: * This method indicates which of these methods is provided directly. The other methods will always be available
029: * indirectly, using an implementation that relies on one of the other methods.
030: */
031:
032: public int getImplementationMethod();
033:
034: /**
035: * Simplify an expression. This performs any static optimization (by rewriting the expression
036: * as a different expression). The default implementation does nothing.
037: *
038: * @exception net.sf.saxon.trans.StaticError if an error is discovered during expression
039: * rewriting
040: * @return the simplified expression
041: */
042:
043: Expression simplify(StaticContext env) throws XPathException;
044:
045: /**
046: * Perform type checking of an expression and its subexpressions.
047: *
048: * <p>This checks statically that the operands of the expression have
049: * the correct type; if necessary it generates code to do run-time type checking or type
050: * conversion. A static type error is reported only if execution cannot possibly succeed, that
051: * is, if a run-time type error is inevitable. The call may return a modified form of the expression.</p>
052: *
053: * <p>This method is called after all references to functions and variables have been resolved
054: * to the declaration of the function or variable. However, the types of such functions and
055: * variables may not be accurately known if they have not been explicitly declared.</p>
056: *
057: * @param env the static context of the expression
058: * @param contextItemType the static type of "." at the point where this expression is invoked.
059: * The parameter is set to null if it is known statically that the context item will be undefined.
060: * If the type of the context item is not known statically, the argument is set to
061: * {@link net.sf.saxon.type.Type#ITEM_TYPE}
062: * @exception net.sf.saxon.trans.StaticError if an error is discovered during this phase
063: * (typically a type error)
064: * @return the original expression, rewritten to perform necessary
065: * run-time type checks, and to perform other type-related
066: * optimizations
067: */
068:
069: Expression typeCheck(StaticContext env, ItemType contextItemType)
070: throws XPathException;
071:
072: /**
073: * Perform optimisation of an expression and its subexpressions.
074: *
075: * <p>This method is called after all references to functions and variables have been resolved
076: * to the declaration of the function or variable, and after all type checking has been done.</p>
077: * @param opt the optimizer in use. This provides access to supporting functions; it also allows
078: * different optimization strategies to be used in different circumstances.
079: * @param env the static context of the expression
080: * @param contextItemType the static type of "." at the point where this expression is invoked.
081: * The parameter is set to null if it is known statically that the context item will be undefined.
082: * If the type of the context item is not known statically, the argument is set to
083: * {@link net.sf.saxon.type.Type#ITEM_TYPE}
084: * @exception net.sf.saxon.trans.StaticError if an error is discovered during this phase
085: * (typically a type error)
086: * @return the original expression, rewritten if appropriate to optimize execution
087: */
088:
089: Expression optimize(Optimizer opt, StaticContext env,
090: ItemType contextItemType) throws XPathException;
091:
092: /**
093: * Offer promotion for this subexpression. The offer will be accepted if the subexpression
094: * is not dependent on the factors (e.g. the context item) identified in the PromotionOffer.
095: * By default the offer is not accepted - this is appropriate in the case of simple expressions
096: * such as constant values and variable references where promotion would give no performance
097: * advantage. This method is always called at compile time.
098: *
099: * @param offer details of the offer, for example the offer to move
100: * expressions that don't depend on the context to an outer level in
101: * the containing expression
102: * @exception net.sf.saxon.trans.XPathException if any error is detected
103: * @return if the offer is not accepted, return this expression unchanged.
104: * Otherwise return the result of rewriting the expression to promote
105: * this subexpression
106: */
107:
108: Expression promote(PromotionOffer offer) throws XPathException;
109:
110: /**
111: * Get the static properties of this expression (other than its type). The result is
112: * bit-signficant. These properties are used for optimizations. In general, if
113: * property bit is set, it is true, but if it is unset, the value is unknown.
114: *
115: * @return a set of flags indicating static properties of this expression
116: */
117:
118: int getSpecialProperties();
119:
120: /**
121: * <p>Determine the static cardinality of the expression. This establishes how many items
122: * there will be in the result of the expression, at compile time (i.e., without
123: * actually evaluating the result.</p>
124: *
125: * <p>This method should always return a result, though it may be the best approximation
126: * that is available at the time.</p>
127: *
128: * @return one of the values {@link StaticProperty#ALLOWS_ONE},
129: * {@link StaticProperty#ALLOWS_ZERO_OR_MORE}, {@link StaticProperty#ALLOWS_ZERO_OR_ONE},
130: * {@link StaticProperty#ALLOWS_ONE_OR_MORE}, {@link StaticProperty#EMPTY}. This default
131: * implementation returns ZERO_OR_MORE (which effectively gives no
132: * information).
133: */
134:
135: int getCardinality();
136:
137: /**
138: * Determine the data type of the expression, if possible. All expression return
139: * sequences, in general; this method determines the type of the items within the
140: * sequence, assuming that (a) this is known in advance, and (b) it is the same for
141: * all items in the sequence.
142: *
143: * <p>This method should always return a result, though it may be the best approximation
144: * that is available at the time.</p>
145: *
146: * @return a value such as Type.STRING, Type.BOOLEAN, Type.NUMBER,
147: * Type.NODE, or Type.ITEM (meaning not known at compile time)
148: * @param th
149: */
150:
151: ItemType getItemType(TypeHierarchy th);
152:
153: /**
154: * Determine which aspects of the context the expression depends on. The result is
155: * a bitwise-or'ed value composed from constants such as {@link StaticProperty#DEPENDS_ON_CONTEXT_ITEM} and
156: * {@link StaticProperty#DEPENDS_ON_CURRENT_ITEM}. The default implementation combines the intrinsic
157: * dependencies of this expression with the dependencies of the subexpressions,
158: * computed recursively. This is overridden for expressions such as FilterExpression
159: * where a subexpression's dependencies are not necessarily inherited by the parent
160: * expression.
161: *
162: * @return a set of bit-significant flags identifying the dependencies of
163: * the expression
164: */
165:
166: int getDependencies();
167:
168: /**
169: * Get the immediate sub-expressions of this expression. Default implementation
170: * returns a zero-length array, appropriate for an expression that has no
171: * sub-expressions.
172: * @return an iterator containing the sub-expressions of this expression
173: */
174:
175: Iterator iterateSubExpressions();
176:
177: /**
178: * Get the container that immediately contains this expression. This method
179: * returns null for an outermost expression; it also return null in the case
180: * of literal values. For an XPath expression occurring within an XSLT stylesheet,
181: * this method returns the XSLT instruction containing the XPath expression.
182: * @return the expression that contains this expression, if known; return null
183: * if there is no containing expression or if the containing expression is unknown.
184: */
185:
186: Container getParentExpression();
187:
188: /**
189: * Test if this expression is the same as another expression.
190: * (Note, returns false to indicate "don't know": our tests are rather limited)
191: *
192: * @param other the expression to be compared with this one
193: * @return true if this expression is known to be equivalent to the other
194: * expression (that is, to deliver the same result in all
195: * circumstances, assuming the context is the same)
196: */
197:
198: //boolean equals(Object other);
199:
200: /**
201: * Evaluate an expression as a single item. This always returns either a single Item or
202: * null (denoting the empty sequence). No conversion is done. This method should not be
203: * used unless the static type of the expression is a subtype of "item" or "item?": that is,
204: * it should not be called if the expression may return a sequence. There is no guarantee that
205: * this condition will be detected.
206: *
207: * @param context The context in which the expression is to be evaluated
208: * @exception XPathException if any dynamic error occurs evaluating the
209: * expression
210: * @return the node or atomic value that results from evaluating the
211: * expression; or null to indicate that the result is an empty
212: * sequence
213: */
214:
215: Item evaluateItem(XPathContext context) throws XPathException;
216:
217: /**
218: * Return an Iterator to iterate over the values of a sequence. The value of every
219: * expression can be regarded as a sequence, so this method is supported for all
220: * expressions. This default implementation handles iteration for expressions that
221: * return singleton values: for non-singleton expressions, the subclass must
222: * provide its own implementation.
223: *
224: * @exception net.sf.saxon.trans.XPathException if any dynamic error occurs evaluating the
225: * expression
226: * @param context supplies the context for evaluation
227: * @return a SequenceIterator that can be used to iterate over the result
228: * of the expression
229: */
230:
231: SequenceIterator iterate(XPathContext context)
232: throws XPathException;
233:
234: /**
235: * Get the effective boolean value of the expression. This returns false if the value
236: * is the empty sequence, a zero-length string, a number equal to zero, or the boolean
237: * false. Otherwise it returns true.
238: *
239: * @param context The context in which the expression is to be evaluated
240: * @exception net.sf.saxon.trans.XPathException if any dynamic error occurs evaluating the
241: * expression
242: * @return the effective boolean value
243: */
244:
245: boolean effectiveBooleanValue(XPathContext context)
246: throws XPathException;
247:
248: /**
249: * Evaluate an expression as a String. This function must only be called in contexts
250: * where it is known that the expression will return a single string (or where an empty sequence
251: * is to be treated as a zero-length string). Implementations should not attempt to convert
252: * the result to a string, other than converting () to "". This method is used mainly to
253: * evaluate expressions produced by compiling an attribute value template.
254: *
255: * @exception XPathException if any dynamic error occurs evaluating the
256: * expression
257: * @exception ClassCastException if the result type of the
258: * expression is not xs:string?
259: * @param context The context in which the expression is to be evaluated
260: * @return the value of the expression, evaluated in the current context.
261: * The expression must return a string or (); if the value of the
262: * expression is (), this method returns "".
263: */
264:
265: public String evaluateAsString(XPathContext context)
266: throws XPathException;
267:
268: /**
269: * Process the instruction, without returning any tail calls
270: * @param context The dynamic context, giving access to the current node,
271: * the current variables, etc.
272: */
273:
274: public void process(XPathContext context) throws XPathException;
275:
276: /**
277: * Diagnostic print of expression structure. The expression is written to the System.err
278: * output stream
279: *
280: * @param level indentation level for this expression
281: * @param pool NamePool used to expand any names appearing in the expression
282: * @param out Output destination
283: */
284:
285: public void display(int level, NamePool pool, PrintStream out);
286:
287: /**
288: * Check statically that the results of the expression are capable of constructing the content
289: * of a given schema type.
290: * @param parentType The schema type
291: * @param env the static context
292: * @param whole true if this expression is expected to make the whole content of the type, false
293: * if it is expected to make up only a part
294: * @throws XPathException if the expression doesn't match the required content type
295: */
296:
297: public void checkPermittedContents(SchemaType parentType,
298: StaticContext env, boolean whole) throws XPathException;
299: }
300: //
301: // The contents of this file are subject to the Mozilla Public License Version 1.0 (the "License");
302: // you may not use this file except in compliance with the License. You may obtain a copy of the
303: // License at http://www.mozilla.org/MPL/
304: //
305: // Software distributed under the License is distributed on an "AS IS" basis,
306: // WITHOUT WARRANTY OF ANY KIND, either express or implied.
307: // See the License for the specific language governing rights and limitations under the License.
308: //
309: // The Original Code is: all this file.
310: //
311: // The Initial Developer of the Original Code is Michael H. Kay.
312: //
313: // Portions created by (your name) are Copyright (C) (your legal entity). All Rights Reserved.
314: //
315: // Contributor(s): none.
316: //
|