## com.saxonica.deploy
Class CompiledQueryServlet

    java.lang.Object
      javax.servlet.GenericServlet
          javax.servlet.http.HttpServlet
              com.saxonica.deploy.CompiledQueryServlet

All Implemented Interfaces:
  java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

    public abstract class CompiledQueryServlet

extends javax.servlet.http.HttpServlet

This abstract class acts as a superclass for every query generated by the Saxon code generator in servlet mode. In this mode the generated code is thread-safe: it is possible to have a single instance of the class running in multiple threads concurrently.

It is possible to define a user-defined subclass of this class that specializes the behaviour of the init() and service() methods. When a query is compiled, the -superclass option on the command line determines the immediate superclass of the compiled code. Such a class will be needed, for example, if different queries are to share access to the same in-memory documents.

During servlet initialization, the init() method attempts to determine whether the servlet context includes an attribute named `com.saxonica.servlet.applicationdata` that is an instance of the interface `SharedApplicationDataHandler`. If this object exists, it is called on each servlet request, at which point it has the opportunity to configure the `Controller` for the query execution, for example by supplying parameter values, setting a URIResolver, or otherwise.

If no `SharedApplicationDataHandler` object is available, external variables for the query can be specified as query parameters in the request URL. The names of query parameters are taken as local names of no-namespace variables, and the values are treated as UntypedAtomic strings (which will be converted to the declared type of the variable if necessary). Any query parameters that do not correspond to declared external variables in the query will be ignored.

See Also:
  Serialized Form

Field Summary
`protected Configuration` `config`
`protected Executable` `exec`
`protected NamePool` `namePool`
`protected SharedApplicationDataHandler` `sharedData`
`protected TypeHierarchy` `th`

Constructor Summary
`CompiledQueryServlet()`

Method Summary
`void` `doGet(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res)` Run the query as a servlet
`protected void` `dynamicError(java.lang.String message, java.lang.String code, XPathContext context)` Signal a dynamic error.
`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 abstract int` `getNumberOfGlobalVariables()` Get a StackFrameMap for the first local stackframe (that is, for the main query body).
`void` `init()` Servlet initialization method
`abstract void` `initializeGlobals()` Run the query-specific initialization code.
`abstract void` `process(XPathContext context)` Run the query, sending the results to the current output destination.
`protected void` `runQuery(Controller controller, javax.xml.transform.Result result, java.util.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.
`protected abstract void` `setExternalVariable(java.lang.String clarkName, ValueRepresentation value, Controller controller)`
`protected void` `typeError(java.lang.String message, java.lang.String code, XPathContext context)` Signal a type error.

Methods inherited from class javax.servlet.http.HttpServlet
`doDelete, doOptions, doPost, doPut, doTrace, getLastModified, service, service`

Methods inherited from class javax.servlet.GenericServlet
`destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, init, log, log`

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

### namePool

    protected NamePool namePool

### th

    protected TypeHierarchy th

### sharedData

    protected SharedApplicationDataHandler sharedData

Constructor Detail

### CompiledQueryServlet

    public CompiledQueryServlet()

Method Detail

### init

    public void init()
              throws javax.servlet.ServletException

  Servlet initialization method

  Overrides:
    `init` in class `javax.servlet.GenericServlet`
  Throws:
    `javax.servlet.ServletException`

### initializeGlobals

    public abstract void initializeGlobals()
                                    throws XPathException

  Run the query-specific initialization code. This method is present in each compiled query.

  Throws:
    `XPathException`

### setConfiguration

    public final 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.

  This method should be called during initialization by the init() method. If a user-defined subclass of `CompiledQueryServlet` is in use, the subclass may call this method directly. In the absence of such a class, the default implementation will call the `SharedApplicationDataHandler` to supply a Configuration; and in the absence of `SharedApplicationDataHandler` it will construct a Configuration specific to this servlet instance.

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

### doGet

    public void doGet(javax.servlet.http.HttpServletRequest req,
                      javax.servlet.http.HttpServletResponse res)
               throws javax.servlet.ServletException,
                      java.io.IOException

  Run the query as a servlet

  Overrides:
    `doGet` in class `javax.servlet.http.HttpServlet`
  Throws:
    `javax.servlet.ServletException`
    `java.io.IOException`

### runQuery

    protected void runQuery(Controller controller,
                            javax.xml.transform.Result result,
                            java.util.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 final Configuration getConfiguration()

  Get the Configuration. This method is provided for use by the compiled query code.

  Returns:
    the configuration in use.

### getExecutable

    public Executable getExecutable()

  Get the Executable. This method is provided for use by the compiled query code.

  Returns:
    the Executable in use.

### getNumberOfGlobalVariables

    protected abstract int getNumberOfGlobalVariables()

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

### setExternalVariable

    protected abstract void setExternalVariable(java.lang.String clarkName,
                                                ValueRepresentation value,
                                                Controller controller)

### process

    public abstract void process(XPathContext context)
                          throws XPathException

  Run the query, sending the results to the current output destination. This method is provided in each compiled query.

  Throws:
    `XPathException`

### typeError

    protected void typeError(java.lang.String message,
                             java.lang.String code,
                             XPathContext context)
                      throws XPathException

  Signal a type error. This method is provided for use by the generated query code.

  Parameters:
    `message` -
    `code` -
    `context` -
  Throws:
    `XPathException`

### dynamicError

    protected void dynamicError(java.lang.String message,
                                java.lang.String code,
                                XPathContext context)
                         throws XPathException

  Signal a dynamic error. This method is provided for use by the generated query code.

  Parameters:
    `message` -
    `code` -
    `context` -
  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. This method is provided for use by the generated query code.

  Throws:
    `XPathException`

### generalCompare

    protected boolean generalCompare(SequenceIterator iter1,
                                     SequenceIterator iter2,
                                     SimpleAtomicComparer comparer,
                                     XPathContext context)
                              throws XPathException

  Helper method to implement a general comparison. This method is provided for use by the generated query code.

  Parameters:
    `iter1` - iterator over the first operand of the comparison
    `iter2` - iterator over the second operand of the comparison
    `comparer` - object used to compare the two values
    `context` - the XPath dynamic context
  Returns:
    true if the comparison is true, false if it is false.
  Throws:
    `XPathException` - if a dynamic error occurs

Copyright (c) Saxonica Limited. All rights reserved.