XPathContext


1   package net.sf.saxon.expr;
2   import net.sf.saxon.Controller;
3   import net.sf.saxon.ConversionContext;
4   import net.sf.saxon.event.SequenceReceiver;
5   import net.sf.saxon.instruct.*;
6   import net.sf.saxon.om.Item;
7   import net.sf.saxon.om.SequenceIterator;
8   import net.sf.saxon.om.ValueRepresentation;
9   import net.sf.saxon.sort.GroupIterator;
10  import net.sf.saxon.trace.InstructionInfoProvider;
11  import net.sf.saxon.trans.DynamicError;
12  import net.sf.saxon.trans.Mode;
13  import net.sf.saxon.trans.XPathException;
14  import net.sf.saxon.type.SchemaType;
15  
16  import javax.xml.transform.Result  ;
17  import java.util.Comparator  ;
18  import java.util.Properties  ;
19  
20  /**
21  * This class represents a context in which an XPath expression is evaluated.
22  */
23  
24  public interface XPathContext extends ConversionContext {
25  
26  
27      /**
28      * Construct a new context as a copy of another. The new context is effectively added
29      * to the top of a stack, and contains a pointer to the previous context
30      */
31  
32      public XPathContextMajor newContext();
33  
34      /**
35      * Construct a new context without copying (used for the context in a function call)
36      */
37  
38      public XPathContextMajor newCleanContext();
39  
40      /**
41       * Construct a new minor context. A minor context can only hold new values of the focus
42       * (currentIterator) and current output destination.
43       */
44  
45      public XPathContextMinor newMinorContext();
46  
47      /**
48       * Get the XSLT-specific part of the context
49       */
50  
51      public XPathContextMajor.XSLTContext getXSLTContext();
52  
53      /**
54       * Get the local (non-tunnel) parameters that were passed to the current function or template
55       * @return a ParameterSet containing the local parameters
56       */
57  
58      public ParameterSet getLocalParameters();
59  
60      /**
61       * Get the tunnel parameters that were passed to the current function or template. This includes all
62       * active tunnel parameters whether the current template uses them or not.
63       * @return a ParameterSet containing the tunnel parameters
64       */
65  
66      public ParameterSet getTunnelParameters();
67  
68      /**
69       * Set the creating expression (for use in diagnostics). The origin is generally set to "this" by the
70       * object that creates the new context. It's up to the debugger to determine whether this information
71       * is useful. Where possible, the object will be an {@link InstructionInfoProvider}, allowing information
72       * about the calling instruction to be obtained.
73       */
74  
75      public void setOrigin(InstructionInfoProvider expr);
76  
77      /**
78       * Set the type of creating expression (for use in diagnostics). When a new context is created, either
79       * this method or {@link #setOrigin} should be called.
80       * @param loc The originating location: the argument must be one of the integer constants in class
81       * {@link net.sf.saxon.trace.Location}
82       */
83  
84      public void setOriginatingConstructType(int loc);
85  
86      /**
87       * Get information about the creating expression or other construct.
88       */
89  
90      public InstructionInfoProvider getOrigin();
91  
92      /**
93       * Get the type of location from which this context was created.
94       */
95  
96      public int getOriginatingConstructType();
97  
98      /**
99      * Get the Controller. May return null when running outside XSLT or XQuery
100     */
101 
102     public Controller getController();
103 
104     /**
105      * Set the calling XPathContext
106      */
107 
108     public void setCaller(XPathContext caller);
109 
110     /**
111      * Get the calling XPathContext (the next one down the stack). This will be null if unknown, or
112      * if the bottom of the stack has been reached.
113      */
114 
115     public XPathContext getCaller();
116 
117     /**
118     * Set a new sequence iterator.
119     */
120 
121     public void setCurrentIterator(SequenceIterator iter);
122 
123      /**
124      * Get the current iterator.
125      * This encapsulates the context item, context position, and context size.
126      * @return the current iterator, or null if there is no current iterator
127      * (which means the context item, position, and size are undefined).
128     */
129 
130     public SequenceIterator getCurrentIterator();
131 
132     /**
133      * Get the context position (the position of the context item)
134      * @return the context position (starting at one)
135      * @throws DynamicError if the context position is undefined
136     */
137 
138     public int getContextPosition() throws DynamicError;
139 
140     /**
141     * Get the context item
142      * @return the context item, or null if the context item is undefined
143     */
144 
145     public Item getContextItem();
146     /**
147      * Get the context size (the position of the last item in the current node list)
148      * @return the context size
149      * @throws XPathException if the context position is undefined
150      */
151 
152     public int getLast() throws XPathException;
153     /**
154     * Determine whether the context position is the same as the context size
155     * that is, whether position()=last()
156     */
157 
158     public boolean isAtLast() throws XPathException;
159 
160     /**
161     * Get a named collation
162     */
163 
164     public Comparator   getCollation(String   name) throws XPathException;
165 
166     /**
167     * Get the default collation
168     */
169 
170     public Comparator   getDefaultCollation();
171 
172     /**
173     * Use local parameter. This is called when a local xsl:param element is processed.
174     * If a parameter of the relevant name was supplied, it is bound to the xsl:param element.
175     * Otherwise the method returns false, so the xsl:param default will be evaluated
176     * @param fingerprint    The fingerprint of the parameter name
177     * @param binding        The XSLParam element to bind its value to
178     * @param isTunnel      True if a tunnel parameter is required, else false
179     * @return true if a parameter of this name was supplied, false if not
180     */
181 
182     public boolean useLocalParameter(int fingerprint,
183                                      LocalParam binding,
184                                      boolean isTunnel) throws XPathException;
185 
186     /**
187      * Get a reference to the local stack frame for variables. Note that it's
188      * the caller's job to make a local copy of this. This is used for creating
189      * a Closure containing a retained copy of the variables for delayed evaluation.
190      * @return array of variables.
191      */
192 
193     public StackFrame getStackFrame();
194 
195      /**
196      * Get the value of a local variable, identified by its slot number
197      */
198 
199     public ValueRepresentation evaluateLocalVariable(int slotnumber);
200 
201     /**
202      * Set the value of a local variable, identified by its slot number
203      */
204 
205     public void setLocalVariable(int slotnumber, ValueRepresentation value);
206 
207     /**
208      * Set a new output destination, supplying the output format details. <BR>
209      * Note that it is the caller's responsibility to close the Writer after use.
210      *
211      * @exception XPathException if any dynamic error occurs; and
212      *     specifically, if an attempt is made to switch to a final output
213      *     destination while writing a temporary tree or sequence
214      * @param props properties defining the output format
215      * @param result Details of the new output destination
216      * @param isFinal true if the destination is a final result tree
217      *     (either the principal output or a secondary result tree); false if
218      *     it is a temporary tree, xsl:attribute, etc.
219      */
220 
221     public void changeOutputDestination(Properties   props,
222                                         Result   result,
223                                         boolean isFinal,
224                                         int validation,
225                                         SchemaType schemaType) throws XPathException;
226 
227     /**
228      * Set the receiver to which output is to be written, marking it as a temporary (non-final)
229      * output destination.
230      * @param out The SequenceOutputter to be used
231      */
232 
233     public void setTemporaryReceiver(SequenceReceiver out);
234 
235     /**
236      * Change the Receiver to which output is written
237      */
238 
239     public void setReceiver(SequenceReceiver receiver);
240 
241     /**
242      * Get the Receiver to which output is currently being written.
243      *
244      * @return the current Receiver
245      */
246     public SequenceReceiver getReceiver();
247 
248     /**
249      * Get the current mode.
250      * @return the current mode
251      */
252 
253     public Mode getCurrentMode();
254 
255     /**
256      * Get the current template. This is used to support xsl:apply-imports
257      *
258      * @return the current template
259      */
260 
261     public Template getCurrentTemplate();
262 
263     /**
264      * Get the current group iterator. This supports the current-group() and
265      * current-grouping-key() functions in XSLT 2.0
266      * @return the current grouped collection
267      */
268 
269     public GroupIterator getCurrentGroupIterator();
270 
271     /**
272      * Get the current regex iterator. This supports the functionality of the regex-group()
273      * function in XSLT 2.0.
274      * @return the current regular expressions iterator
275      */
276 
277     public RegexIterator getCurrentRegexIterator();
278 
279 }
280 
281 //
282 // The contents of this file are subject to the Mozilla Public License Version 1.0 (the "License");
283 // you may not use this file except in compliance with the License. You may obtain a copy of the
284 // License at http://www.mozilla.org/MPL/
285 //
286 // Software distributed under the License is distributed on an "AS IS" basis,
287 // WITHOUT WARRANTY OF ANY KIND, either express or implied.
288 // See the License for the specific language governing rights and limitations under the License.
289 //
290 // The Original Code is: all this file.
291 //
292 // The Initial Developer of the Original Code is Michael H. Kay.
293 //
294 // Portions created by (your name) are Copyright (C) (your legal entity). All Rights Reserved.
295 //
296 // Contributor(s): none.
297 //
298
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags