com.saxonica.deploy
Class CompiledUserQuery

java.lang.Object
  extended by com.saxonica.deploy.CompiledUserQuery

public abstract class CompiledUserQuery
extends Object

This abstract class acts as a superclass for every compiled query generated by the Saxon code generator, other than queries compiled in servlet mode.

Queries compiled to use this superclass are not thread-safe: a new instance of the class must be created each time a query is run in a new thread. The class is, however, serially reusable.

The class supports two mechanisms for running a compiled query. The query can be run directly from the command line, or it can be integrated into an application and invoked via a Java API.

The class contains two kinds of method: methods (many of them abstract) that form the API to the query, enabling a client application to invoke the query and process the results; and concrete methods that provide run-time services to the compiled query itself.


Field Summary
protected  Configuration config
           
protected  DynamicQueryContext dqc
           
protected  Executable exec
           
protected  NamePool namePool
           
protected  TypeHierarchy th
           
 
Constructor Summary
CompiledUserQuery()
           
 
Method Summary
protected  void dynamicError(String message, String code, XPathContext context)
           
protected  boolean generalCompare(SequenceIterator iter1, SequenceIterator iter2, SimpleAtomicComparer comparer, XPathContext context)
          Helper method to implement a general comparison
 Configuration getConfiguration()
          Get the Configuration
protected  NodeInfo getContextNode(Item item)
          Helper method to get the context node, throwing appropriate exceptions if there isn't one
 Executable getExecutable()
          Get the Executable
protected  SlotManager getStackFrameMap()
          Get a StackFrameMap for the first local stackframe (that is, for the main query body).
abstract  void importSchemata(Configuration config)
          Load the schema documents that were imported into the query source code.
abstract  void initializeGlobals(XPathContext context)
          Run the query-specific initialization code.
 void mainCommand(String[] args)
          Run the query from the command line
abstract  void process(XPathContext context)
          Run the query, sending the results to the current output destination
 void run(Result result, Properties outputProperties)
          Run the query, sending the results directly to a JAXP Result object.
 void setConfiguration(Configuration config)
          Supply the configuration in which the query will be executed.
 void setDynamicContext(DynamicQueryContext context)
          Supply the dynamic context for the query.
abstract  void setExternalVariable(String clarkName, ValueRepresentation value)
          Supply the value of an external variable
protected  void typeError(String message, String code, XPathContext context)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

config

protected Configuration config

exec

protected Executable exec

dqc

protected DynamicQueryContext dqc

namePool

protected NamePool namePool

th

protected TypeHierarchy th
Constructor Detail

CompiledUserQuery

public CompiledUserQuery()
Method Detail

setConfiguration

public void setConfiguration(Configuration config)
Supply the configuration in which the query will be executed. Note that this is not required to be the same as the configuration under which the query was compiled. However, any schemas that are present in the run-time configuration must be unchanged from the versions that were used at compile time. If no configuration is supplied then the query will run with a default configuration.

Parameters:
config - the Configuration to be used. If the query is schema-aware, this must be an instance of EnterpriseConfiguration

setExternalVariable

public abstract void setExternalVariable(String clarkName,
                                         ValueRepresentation value)
Supply the value of an external variable

Parameters:
clarkName - The expanded name of the variable in Clark notation: that is, the local name in the case of a name in no namespace, or "{uri}local" for a name with namespace URI "uri" and local name "local"
value - The value to be assigned to the external variable

setDynamicContext

public void setDynamicContext(DynamicQueryContext context)
Supply the dynamic context for the query. The dynamic context may include a context item, values of external query parameters, and other details. If no dynamic context is supplied, the query will run with a default context (no context item, no parameter values other than those provided using the method setExternalVariable(java.lang.String, net.sf.saxon.om.ValueRepresentation)).

If any parameter values are included in the context, they will immediately be extracted from the supplied context object and passed to the query as if setExternalVariable(java.lang.String, net.sf.saxon.om.ValueRepresentation) were called. Subsequent changes to the context object have no effect. However, if the values supplied are mutable, it is undefined whether any subsequent changes to the values have any effect.

Parameters:
context - the dynamic context to be used.

run

public void run(Result result,
                Properties outputProperties)
         throws XPathException
Run the query, sending the results directly to a JAXP Result object. This way of executing the query is most efficient in the case of queries that produce a single document (or parentless element) as their output, because it avoids constructing the result tree in memory: instead, it is piped straight to the serializer.

Parameters:
result - the destination for the results of the query. The query is effectively wrapped in a document{} constructor, so that the items in the result are concatenated to form a single document; this is then written to the requested Result destination, which may be (for example) a DOMResult, a SAXResult, or a StreamResult
outputProperties - Supplies serialization properties, in JAXP format, if the result is to be serialized. This parameter can be defaulted to null. Values supplied here take precedence over any values supplied in the query source using the saxon:output option declaration.
Throws:
XPathException - if the query fails.

getConfiguration

public Configuration getConfiguration()
Get the Configuration

Returns:
the Saxon configuration object

getExecutable

public Executable getExecutable()
Get the Executable

Returns:
the Executable containing this query

initializeGlobals

public abstract void initializeGlobals(XPathContext context)
                                throws XPathException
Run the query-specific initialization code. This code is generated as part of the compiled query.

Parameters:
context - the XPath dynamic context
Throws:
XPathException

importSchemata

public abstract void importSchemata(Configuration config)
                             throws SchemaException
Load the schema documents that were imported into the query source code. The implementation of this method is part of the generated code. This method is not called automatically when invoking the compiled query via the run(javax.xml.transform.Result, java.util.Properties) method; it can be called directly if required. It is called automatically when the query is run from the command line.

Parameters:
config - the Saxon Configuration (which must be schema-aware)
Throws:
SchemaException

getStackFrameMap

protected SlotManager getStackFrameMap()
Get a StackFrameMap for the first local stackframe (that is, for the main query body).

Returns:
the stack frame map

process

public abstract void process(XPathContext context)
                      throws XPathException
Run the query, sending the results to the current output destination

Parameters:
context - the XPath dynamic context
Throws:
XPathException

typeError

protected void typeError(String message,
                         String code,
                         XPathContext context)
                  throws XPathException
Throws:
XPathException

dynamicError

protected void dynamicError(String message,
                            String code,
                            XPathContext context)
                     throws XPathException
Throws:
XPathException

getContextNode

protected NodeInfo getContextNode(Item item)
                           throws XPathException
Helper method to get the context node, throwing appropriate exceptions if there isn't one

Parameters:
item - the context item
Returns:
the supplied item if it is not null and is a node
Throws:
XPathException - if the context item does not exist or is not a node

generalCompare

protected boolean generalCompare(SequenceIterator iter1,
                                 SequenceIterator iter2,
                                 SimpleAtomicComparer comparer,
                                 XPathContext context)
                          throws XPathException
Helper method to implement a general comparison

Parameters:
iter1 - the first operand
iter2 - the second operand
comparer - the comparer to be used
context - the XPath dynamic context
Returns:
the result of the comparison
Throws:
XPathException

mainCommand

public void mainCommand(String[] args)
                 throws Exception
Run the query from the command line

Parameters:
args - command line options
Throws:
Exception


Copyright (c) Saxonica Limited. All rights reserved.