001: package net.sf.saxon.expr;
002:
003: import net.sf.saxon.Configuration;
004: import net.sf.saxon.Controller;
005: import net.sf.saxon.event.SequenceReceiver;
006: import net.sf.saxon.instruct.LocalParam;
007: import net.sf.saxon.instruct.ParameterSet;
008: import net.sf.saxon.instruct.RegexIterator;
009: import net.sf.saxon.instruct.Template;
010: import net.sf.saxon.om.Item;
011: import net.sf.saxon.om.NamePool;
012: import net.sf.saxon.om.SequenceIterator;
013: import net.sf.saxon.om.ValueRepresentation;
014: import net.sf.saxon.sort.GroupIterator;
015: import net.sf.saxon.trace.InstructionInfoProvider;
016: import net.sf.saxon.trans.DynamicError;
017: import net.sf.saxon.trans.Mode;
018: import net.sf.saxon.trans.XPathException;
019: import net.sf.saxon.type.SchemaType;
020:
021: import javax.xml.transform.Result;
022: import java.util.Comparator;
023: import java.util.Properties;
024:
025: /**
026: * This class represents a context in which an XPath expression is evaluated.
027: */
028:
029: public interface XPathContext {
030:
031: /**
032: * Construct a new context as a copy of another. The new context is effectively added
033: * to the top of a stack, and contains a pointer to the previous context
034: */
035:
036: public XPathContextMajor newContext();
037:
038: /**
039: * Construct a new context without copying (used for the context in a function call)
040: */
041:
042: public XPathContextMajor newCleanContext();
043:
044: /**
045: * Construct a new minor context. A minor context can only hold new values of the focus
046: * (currentIterator) and current output destination.
047: */
048:
049: public XPathContextMinor newMinorContext();
050:
051: /**
052: * Get the XSLT-specific part of the context
053: */
054:
055: public XPathContextMajor.XSLTContext getXSLTContext();
056:
057: /**
058: * Get the local (non-tunnel) parameters that were passed to the current function or template
059: * @return a ParameterSet containing the local parameters
060: */
061:
062: public ParameterSet getLocalParameters();
063:
064: /**
065: * Get the tunnel parameters that were passed to the current function or template. This includes all
066: * active tunnel parameters whether the current template uses them or not.
067: * @return a ParameterSet containing the tunnel parameters
068: */
069:
070: public ParameterSet getTunnelParameters();
071:
072: /**
073: * Set the creating expression (for use in diagnostics). The origin is generally set to "this" by the
074: * object that creates the new context. It's up to the debugger to determine whether this information
075: * is useful. Where possible, the object will be an {@link InstructionInfoProvider}, allowing information
076: * about the calling instruction to be obtained.
077: */
078:
079: public void setOrigin(InstructionInfoProvider expr);
080:
081: /**
082: * Set the type of creating expression (for use in diagnostics). When a new context is created, either
083: * this method or {@link #setOrigin} should be called.
084: * @param loc The originating location: the argument must be one of the integer constants in class
085: * {@link net.sf.saxon.trace.Location}
086: */
087:
088: public void setOriginatingConstructType(int loc);
089:
090: /**
091: * Get information about the creating expression or other construct.
092: */
093:
094: public InstructionInfoProvider getOrigin();
095:
096: /**
097: * Get the type of location from which this context was created.
098: */
099:
100: public int getOriginatingConstructType();
101:
102: /**
103: * Get the Controller. May return null when running outside XSLT or XQuery
104: */
105:
106: public Controller getController();
107:
108: /**
109: * Get the Configuration
110: */
111:
112: public Configuration getConfiguration();
113:
114: /**
115: * Get the Name Pool
116: */
117:
118: public NamePool getNamePool();
119:
120: /**
121: * Set the calling XPathContext
122: */
123:
124: public void setCaller(XPathContext caller);
125:
126: /**
127: * Get the calling XPathContext (the next one down the stack). This will be null if unknown, or
128: * if the bottom of the stack has been reached.
129: */
130:
131: public XPathContext getCaller();
132:
133: /**
134: * Set a new sequence iterator.
135: */
136:
137: public void setCurrentIterator(SequenceIterator iter);
138:
139: /**
140: * Get the current iterator.
141: * This encapsulates the context item, context position, and context size.
142: * @return the current iterator, or null if there is no current iterator
143: * (which means the context item, position, and size are undefined).
144: */
145:
146: public SequenceIterator getCurrentIterator();
147:
148: /**
149: * Get the context position (the position of the context item)
150: * @return the context position (starting at one)
151: * @throws DynamicError if the context position is undefined
152: */
153:
154: public int getContextPosition() throws DynamicError;
155:
156: /**
157: * Get the context item
158: * @return the context item, or null if the context item is undefined
159: */
160:
161: public Item getContextItem();
162:
163: /**
164: * Get the context size (the position of the last item in the current node list)
165: * @return the context size
166: * @throws XPathException if the context position is undefined
167: */
168:
169: public int getLast() throws XPathException;
170:
171: /**
172: * Determine whether the context position is the same as the context size
173: * that is, whether position()=last()
174: */
175:
176: public boolean isAtLast() throws XPathException;
177:
178: /**
179: * Get a named collation
180: */
181:
182: public Comparator getCollation(String name) throws XPathException;
183:
184: /**
185: * Get the default collation
186: */
187:
188: public Comparator getDefaultCollation();
189:
190: /**
191: * Use local parameter. This is called when a local xsl:param element is processed.
192: * If a parameter of the relevant name was supplied, it is bound to the xsl:param element.
193: * Otherwise the method returns false, so the xsl:param default will be evaluated
194: * @param fingerprint The fingerprint of the parameter name
195: * @param binding The XSLParam element to bind its value to
196: * @param isTunnel True if a tunnel parameter is required, else false
197: * @return true if a parameter of this name was supplied, false if not
198: */
199:
200: public boolean useLocalParameter(int fingerprint,
201: LocalParam binding, boolean isTunnel) throws XPathException;
202:
203: /**
204: * Get a reference to the local stack frame for variables. Note that it's
205: * the caller's job to make a local copy of this. This is used for creating
206: * a Closure containing a retained copy of the variables for delayed evaluation.
207: * @return array of variables.
208: */
209:
210: public StackFrame getStackFrame();
211:
212: /**
213: * Get the value of a local variable, identified by its slot number
214: */
215:
216: public ValueRepresentation evaluateLocalVariable(int slotnumber);
217:
218: /**
219: * Set the value of a local variable, identified by its slot number
220: */
221:
222: public void setLocalVariable(int slotnumber,
223: ValueRepresentation value);
224:
225: /**
226: * Set a new output destination, supplying the output format details. <BR>
227: * Note that it is the caller's responsibility to close the Writer after use.
228: *
229: * @exception XPathException if any dynamic error occurs; and
230: * specifically, if an attempt is made to switch to a final output
231: * destination while writing a temporary tree or sequence
232: * @param props properties defining the output format
233: * @param result Details of the new output destination
234: * @param isFinal true if the destination is a final result tree
235: * (either the principal output or a secondary result tree); false if
236: * it is a temporary tree, xsl:attribute, etc.
237: */
238:
239: public void changeOutputDestination(Properties props,
240: Result result, boolean isFinal, int validation,
241: SchemaType schemaType) throws XPathException;
242:
243: /**
244: * Set the receiver to which output is to be written, marking it as a temporary (non-final)
245: * output destination.
246: * @param out The SequenceOutputter to be used
247: */
248:
249: public void setTemporaryReceiver(SequenceReceiver out);
250:
251: /**
252: * Change the Receiver to which output is written
253: */
254:
255: public void setReceiver(SequenceReceiver receiver);
256:
257: /**
258: * Get the Receiver to which output is currently being written.
259: *
260: * @return the current Receiver
261: */
262: public SequenceReceiver getReceiver();
263:
264: /**
265: * Get the current mode.
266: * @return the current mode
267: */
268:
269: public Mode getCurrentMode();
270:
271: /**
272: * Get the current template. This is used to support xsl:apply-imports
273: *
274: * @return the current template
275: */
276:
277: public Template getCurrentTemplate();
278:
279: /**
280: * Get the current group iterator. This supports the current-group() and
281: * current-grouping-key() functions in XSLT 2.0
282: * @return the current grouped collection
283: */
284:
285: public GroupIterator getCurrentGroupIterator();
286:
287: /**
288: * Get the current regex iterator. This supports the functionality of the regex-group()
289: * function in XSLT 2.0.
290: * @return the current regular expressions iterator
291: */
292:
293: public RegexIterator getCurrentRegexIterator();
294:
295: }
296:
297: //
298: // The contents of this file are subject to the Mozilla Public License Version 1.0 (the "License");
299: // you may not use this file except in compliance with the License. You may obtain a copy of the
300: // License at http://www.mozilla.org/MPL/
301: //
302: // Software distributed under the License is distributed on an "AS IS" basis,
303: // WITHOUT WARRANTY OF ANY KIND, either express or implied.
304: // See the License for the specific language governing rights and limitations under the License.
305: //
306: // The Original Code is: all this file.
307: //
308: // The Initial Developer of the Original Code is Michael H. Kay.
309: //
310: // Portions created by (your name) are Copyright (C) (your legal entity). All Rights Reserved.
311: //
312: // Contributor(s): none.
313: //
|