Package net.sf.saxon

## Class Query

- java.lang.Object
- - net.sf.saxon.Query

- Direct Known Subclasses:
    `JDOM2Query`, `Query`

      public class Query
      extends java.lang.Object

  This Query class provides a command-line interface to the Saxon XQuery processor.

  The XQuery syntax supported conforms to the W3C XQuery 1.0 drafts.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected boolean` | `backup` |
    `protected Configuration` | `config` |
    `protected boolean` | `explain` |
    `protected java.lang.String` | `explainOutputFileName` |
    `protected java.lang.String` | `moduleURIResolverClass` |
    `protected java.lang.String` | `outputFileName` |
    `protected Processor` | `processor` |
    `protected boolean` | `projection` |
    `protected java.lang.String` | `queryFileName` |
    `protected int` | `repeat` |
    `protected boolean` | `showTime` |
    `protected java.lang.String` | `sourceFileName` |
    `protected boolean` | `streaming` |
    `protected boolean` | `updating` |
    `protected java.lang.String` | `uriResolverClass` |
    `protected boolean` | `useURLs` |
    `protected boolean` | `wrap` |
    `protected boolean` | `writeback` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Query()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `applyLocalOptions​(CommandLineOptions options, Configuration config)` | Customisation hook: apply options defined locally in a subclass
    `protected void` | `badUsage​(java.lang.String message)` | Report incorrect usage of the command line, with a list of the options and arguments that are available
    `protected XQueryExecutable` | `compileQuery​(XQueryCompiler compiler, java.lang.String queryFileName, boolean useURLs)` | Compile the query
    `static void` | `createFileIfNecessary​(java.io.File file)` | Utility method to create a file if it does not already exist, including creation of any necessary directories named in the file path
    `protected void` | `doQuery​(java.lang.String[] args, java.lang.String command)` | Support method for main program.
    `protected void` | `explain​(XQueryExpression exp)` | Explain the results of query compilation
    `protected Configuration` | `getConfiguration()` | Get the configuration in use
    `protected void` | `initializeConfiguration​(Configuration config)` | Customisation hook called immediately after the Configuration object is instantiated.
    `static void` | `main​(java.lang.String[] args)` | Main program, can be used directly from the command line.
    `protected void` | `parseOptions​(CommandLineOptions options)` | Parse the options supplied on the command line
    `protected void` | `processSource​(javax.xml.transform.Source sourceInput, XQueryExecutable exp, XQueryEvaluator evaluator)` | Process the supplied source file
    `protected javax.xml.transform.Source` | `processSourceFile​(java.lang.String sourceFileName, boolean useURLs)` |
    `protected void` | `quit​(java.lang.String message, int code)` | Exit with a message
    `protected void` | `runQuery​(XQueryExecutable exp, XQueryEvaluator evaluator, javax.xml.transform.Source input, Destination destination)` | Run the query
    `protected void` | `runUpdate​(XQueryExecutable exp, XQueryEvaluator evaluator, Serializer serializer)` | Run an updating query
    `void` | `setPermittedOptions​(CommandLineOptions options)` | Set the options that are recognized on the command line.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### processor

          protected Processor processor

    - #### config

          protected Configuration config

    - #### showTime

          protected boolean showTime

    - #### repeat

          protected int repeat

    - #### sourceFileName

          protected java.lang.String sourceFileName

    - #### queryFileName

          protected java.lang.String queryFileName

    - #### useURLs

          protected boolean useURLs

    - #### outputFileName

          protected java.lang.String outputFileName

    - #### moduleURIResolverClass

          protected java.lang.String moduleURIResolverClass

    - #### uriResolverClass

          protected final java.lang.String uriResolverClass

    - #### explain

          protected boolean explain

    - #### wrap

          protected boolean wrap

    - #### projection

          protected boolean projection

    - #### streaming

          protected boolean streaming

    - #### updating

          protected boolean updating

    - #### writeback

          protected boolean writeback

    - #### backup

          protected boolean backup

    - #### explainOutputFileName

          protected java.lang.String explainOutputFileName

  - ### Constructor Detail

    - #### Query

          public Query()

  - ### Method Detail

    - #### getConfiguration

          protected Configuration getConfiguration()

      Get the configuration in use
      Returns:
        the configuration

    - #### main

          public static void main​(java.lang.String[] args)

      Main program, can be used directly from the command line.

      The format is:

      java net.sf.saxon.Query [options] query-file >output-file

      followed by any number of parameters in the form {keyword=value}... which can be referenced from within the query.

      This program executes the query in query-file.

      Parameters:
        `args` - List of arguments supplied on operating system command line

    - #### setPermittedOptions

          public void setPermittedOptions​(CommandLineOptions options)

      Set the options that are recognized on the command line. This method can be overridden in a subclass to define additional command line options.
      Parameters:
        `options` - the CommandLineOptions in which the recognized options are to be registered.

    - #### doQuery

          protected void doQuery​(java.lang.String[] args,
                                 java.lang.String command)

      Support method for main program. This support method can also be invoked from subclasses that support the same command line interface
      Parameters:
        `args` - the command-line arguments
        `command` - name of the class, to be used in error messages

    - #### initializeConfiguration

          protected void initializeConfiguration​(Configuration config)

      Customisation hook called immediately after the Configuration object is instantiated. The intended purpose of this hook is to allow a subclass to supply an OEM license key programmatically, but it can also be used for other initialization of the Configuration. This method is called before analyzing the command line options, so configuration settings made at this stage may be overridden when the command line options are processed. However, if a configuration file is used, the settings defined in the configuration file will have been applied.
      Parameters:
        `config` - the Configuration object

    - #### parseOptions

          protected void parseOptions​(CommandLineOptions options)
                               throws javax.xml.transform.TransformerException

      Parse the options supplied on the command line
      Parameters:
        `options` - the command line arguments
      Throws:
        `javax.xml.transform.TransformerException` - if failures occur. Note, the method may also invoke System.exit().

    - #### applyLocalOptions

          protected void applyLocalOptions​(CommandLineOptions options,
                                           Configuration config)

      Customisation hook: apply options defined locally in a subclass
      Parameters:
        `options` - the CommandLineOptions
        `config` - the Saxon Configuration

    - #### processSourceFile

          protected javax.xml.transform.Source processSourceFile​(java.lang.String sourceFileName,
                                                                 boolean useURLs)
                                                          throws javax.xml.transform.TransformerException

      Throws:
        `javax.xml.transform.TransformerException`

    - #### compileQuery

          protected XQueryExecutable compileQuery​(XQueryCompiler compiler,
                                                  java.lang.String queryFileName,
                                                  boolean useURLs)
                                           throws SaxonApiException,
                                                  java.io.IOException

      Compile the query
      Parameters:
        `compiler` - the XQuery compiler
        `queryFileName` - the filename holding the query (or "-" for the standard input, or the actual query text enclosed in curly braces
        `useURLs` - true if the filename is in the form of a URI
      Returns:
        the compiled query
      Throws:
        `SaxonApiException` - if query compilation fails
        `java.io.IOException` - if the query cannot be read

    - #### explain

          protected void explain​(XQueryExpression exp)
                          throws java.io.FileNotFoundException,
                                 XPathException

      Explain the results of query compilation
      Parameters:
        `exp` - the compiled expression
      Throws:
        `java.io.FileNotFoundException` - if the destination for the explanation doesn't exist
        `XPathException` - if other failures occur

    - #### processSource

          protected void processSource​(javax.xml.transform.Source sourceInput,
                                       XQueryExecutable exp,
                                       XQueryEvaluator evaluator)
                                throws SaxonApiException

      Process the supplied source file
      Parameters:
        `sourceInput` - the supplied source
        `exp` - the compiled XQuery expression
        `evaluator` - the dynamic query context
      Throws:
        `SaxonApiException` - if processing fails

    - #### runQuery

          protected void runQuery​(XQueryExecutable exp,
                                  XQueryEvaluator evaluator,
                                  javax.xml.transform.Source input,
                                  Destination destination)
                           throws SaxonApiException

      Run the query
      Parameters:
        `exp` - the compiled query expression
        `evaluator` - the dynamic query context
        `input` - the supplied source
        `destination` - the destination for serialized results
      Throws:
        `SaxonApiException` - if the query fails

    - #### runUpdate

          protected void runUpdate​(XQueryExecutable exp,
                                   XQueryEvaluator evaluator,
                                   Serializer serializer)
                            throws SaxonApiException

      Run an updating query
      Parameters:
        `exp` - the compiled query expression
        `evaluator` - the query evaluator
        `serializer` - the destination for serialized results
      Throws:
        `SaxonApiException` - if the query fails

    - #### quit

          protected void quit​(java.lang.String message,
                              int code)

      Exit with a message
      Parameters:
        `message` - The message to be output
        `code` - The result code to be returned to the operating system shell

    - #### badUsage

          protected void badUsage​(java.lang.String message)

      Report incorrect usage of the command line, with a list of the options and arguments that are available
      Parameters:
        `message` - The error message

    - #### createFileIfNecessary

          public static void createFileIfNecessary​(java.io.File file)
                                            throws java.io.IOException

      Utility method to create a file if it does not already exist, including creation of any necessary directories named in the file path
      Parameters:
        `file` - the file that is required to exist
      Throws:
        `java.io.IOException` - if file creation fails