Package com.saxonica.xqj

## Class SaxonXQDataSource

- java.lang.Object
- - com.saxonica.xqj.SaxonXQDataSource

- All Implemented Interfaces:
    `XQDataSource`, `Configuration.ApiProvider`

      public class SaxonXQDataSource
      extends java.lang.Object
      implements XQDataSource, Configuration.ApiProvider

  Saxon implementation of the XQJ XQDataSource interface. The first action of a client application is to instantiate a SaxonXQDataSource. This is done directly: there is no factory class as with JAXP. An application that does not want compile-time references to the Saxon XQJ implementation can instantiate this class dynamically using the reflection API (class.newInstance()).

  For full Javadoc descriptions of the public methods, see the XQJ specification.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SaxonXQDataSource()` | Create a SaxonXQDataSource using a default configuration.
    `SaxonXQDataSource​(Configuration config)` | Create a Saxon XQDataSource with a specific configuration

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.String` | `getAllowExternalFunctions()` | Ask whether queries are allowed to call external functions.
    `Configuration` | `getConfiguration()` | Get the Saxon Configuration in use.
    `XQConnection` | `getConnection()` | Attempts to create a connection to an XML datasource.
    `XQConnection` | `getConnection​(java.lang.String username, java.lang.String password)` | Get a connection, by supplying a username and password.
    `XQConnection` | `getConnection​(java.sql.Connection con)` | Get a connection based on an underlying JDBC connection
    `java.lang.String` | `getDtdValidation()` | Ask whether source documents are to be parsed with DTD validation enabled
    `java.lang.String` | `getExpandAttributeDefaults()` | Ask whether fixed or default values defined in a schema or DTD will be expanded
    `java.lang.String` | `getExpandXInclude()` | Ask whether XInclude processing is to be applied to source documents
    `int` | `getLoginTimeout()` | Gets the maximum time in seconds that this datasource can wait while attempting to connect to a database.
    `java.io.PrintWriter` | `getLogWriter()` | Retrieves the log writer for this `XQDataSource` object.
    `java.lang.String` | `getProperty​(java.lang.String name)` | Get a configuration property setting.
    `java.lang.String` | `getRetainLineNumbers()` | Ask whether line and column information will be retained for source documents
    `java.lang.String` | `getSchemaValidationMode()` | Ask whether source documents will be validated against a schema
    `java.lang.String` | `getStripWhitespace()` | Ask whether whitespace will be stripped when loading source documents
    `java.lang.String[]` | `getSupportedPropertyNames()` | Returns an array containing the property names supported by this `XQDataSource`.
    `java.lang.String` | `getUseXsiSchemaLocation()` | Ask whether the schema processor is to take account of xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes encountered in an instance document being validated
    `java.lang.String` | `getXmlVersion()` | Ask whether XML 1.0 or XML 1.1 rules for XML names are to be followed
    `java.lang.String` | `getXsdVersion()` | Ask whether XML Schema 1.0 syntax must be used or whether XML Schema 1.1 features are allowed
    `void` | `registerExtensionFunction​(ExtensionFunctionDefinition function)` | Register an extension function that is to be made available within any query.
    `void` | `setAllowExternalFunctions​(java.lang.String value)` | Say whether queries are allowed to call external functions.
    `void` | `setDtdValidation​(java.lang.String value)` | Say whether source documents are to be parsed with DTD validation enabled
    `void` | `setExpandAttributeDefaults​(java.lang.String value)` | Say whether whether fixed and default values defined in a schema or DTD will be expanded.
    `void` | `setExpandXInclude​(java.lang.String value)` | Say whether XInclude processing is to be applied to source documents
    `void` | `setLoginTimeout​(int seconds)` | Sets the maximum time in seconds that this datasource will wait while attempting to connect to a database.
    `void` | `setLogWriter​(java.io.PrintWriter out)` | Sets the log writer for this `XQDataSource` object to the given `java.io.PrintWriter` object.
    `void` | `setProperties​(java.util.Properties props)` | Sets the data source properties from the specified `Properties` instance.
    `void` | `setProperty​(java.lang.String name, java.lang.String value)` | Set a configuration property.
    `void` | `setRetainLineNumbers​(java.lang.String value)` | Say whether source documents should have line and column information retained.
    `void` | `setSchemaValidationMode​(java.lang.String value)` | Say whether source documents should be validated against a schema
    `void` | `setStripWhitespace​(java.lang.String value)` | Say whether whitespace should be stripped when loading source documents
    `void` | `setUseXsiSchemaLocation​(java.lang.String value)` | Say whether the schema processor is to take account of xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes encountered in an instance document being validated
    `void` | `setXmlVersion​(java.lang.String value)` | Say whether XML 1.0 or XML 1.1 rules for XML names are to be followed
    `void` | `setXsdVersion​(java.lang.String value)` | Say whether XML Schema 1.0 syntax must be used or whether XML Schema 1.1 features are allowed

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

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

- - ### Constructor Detail

    - #### SaxonXQDataSource

          public SaxonXQDataSource()

      Create a SaxonXQDataSource using a default configuration. The Configuration will be an EE, PE, or HE configuration depending on the what is found on the classpath

    - #### SaxonXQDataSource

          public SaxonXQDataSource​(Configuration config)

      Create a Saxon XQDataSource with a specific configuration
      Parameters:
        `config` - The Saxon configuration to be used

  - ### Method Detail

    - #### getConfiguration

          public Configuration getConfiguration()

      Get the Saxon Configuration in use. Changes made to this Configuration will affect this data source and XQJ connections created from it (either before or afterwards). Equally, changes made to this SaxonXQDataSource are reflected in the Configuration object (which means they also impact any other SaxonXQDataSource objects that share the same Configuration).
      Returns:
        the configuration in use.

    - #### getConnection

          public XQConnection getConnection()

      Description copied from interface: `XQDataSource`
      Attempts to create a connection to an XML datasource.
      Specified by:
        `getConnection` in interface `XQDataSource`
      Returns:
        a connection to the XML datasource

    - #### getConnection

          public XQConnection getConnection​(java.sql.Connection con)
                                     throws XQException

      Get a connection based on an underlying JDBC connection
      Specified by:
        `getConnection` in interface `XQDataSource`
      Parameters:
        `con` - the JDBC connection
      Returns:
        a connection based on an underlying JDBC connection
      Throws:
        `XQException` - The Saxon implementation of this method always throws an XQException, indicating that Saxon does not support connection to a JDBC data source.

    - #### getConnection

          public XQConnection getConnection​(java.lang.String username,
                                            java.lang.String password)

      Get a connection, by supplying a username and password. The Saxon implementation of this is equivalent to the default constructor: the username and password are ignored.
      Specified by:
        `getConnection` in interface `XQDataSource`
      Parameters:
        `username` - the user name
        `password` - the password
      Returns:
        a connection

    - #### getLoginTimeout

          public int getLoginTimeout()

      Description copied from interface: `XQDataSource`
      Gets the maximum time in seconds that this datasource can wait while attempting to connect to a database. A value of zero means that the timeout is the default system timeout if there is one; otherwise, it means that there is no timeout. When a XQDataSource object is created, the login timeout is initially zero. It is implementation-defined whether the returned login timeout is actually used by the data source implementation.
      Specified by:
        `getLoginTimeout` in interface `XQDataSource`
      Returns:
        the datasource login time limit

    - #### getLogWriter

          public java.io.PrintWriter getLogWriter()

      Description copied from interface: `XQDataSource`
      Retrieves the log writer for this `XQDataSource` object. The log writer is a character output stream to which all logging and tracing messages for this datasource will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. When a `XQDataSource` object is created, the log writer is initially `null`; in other words, the default is for logging to be disabled.
      Specified by:
        `getLogWriter` in interface `XQDataSource`
      Returns:
        the log writer for this datasource or `null` if logging is disabled

    - #### getProperty

          public java.lang.String getProperty​(java.lang.String name)
                                       throws XQException

      Get a configuration property setting. The properties that are supported, and their meanings, are the same as the properties that can be obtained using "get" methods; for example `getProperty("dtdValidation")` returns the same result as `getDtdValidation()`.

      Further Saxon configuration properties are available using the URIs defined as constants in `FeatureKeys`

      Specified by:
        `getProperty` in interface `XQDataSource`
      Parameters:
        `name` - the name of the configuration property
      Returns:
        the value of the configuration property. Note that in the case of on/off properties this will be returned as the string true/false
      Throws:
        `XQException` - if the property name or value is invalid

    - #### getSupportedPropertyNames

          public java.lang.String[] getSupportedPropertyNames()

      Description copied from interface: `XQDataSource`
      Returns an array containing the property names supported by this `XQDataSource`.

      Implementations that support user name and password must recognize the user name and password properties listed below.

      - `user`: the user name to use for creating a connection
      - `password`: the password to use for creating a connection

      Any additional properties are implementation-defined.

      Specified by:
        `getSupportedPropertyNames` in interface `XQDataSource`
      Returns:
        `String[]` an array of property names supported by this implementation

    - #### setLoginTimeout

          public void setLoginTimeout​(int seconds)

      Description copied from interface: `XQDataSource`
      Sets the maximum time in seconds that this datasource will wait while attempting to connect to a database. A value of zero specifies that the timeout is the default system timeout if there is one; otherwise, it specifies that there is no timeout. When a `XQDataSource` object is created, the login timeout is initially zero. It is implementation-defined whether the specified login timeout is actually used by the data source implementation. If the connection is created over an existing JDBC connection, then the login timeout value from the underlying JDBC connection may be used.
      Specified by:
        `setLoginTimeout` in interface `XQDataSource`
      Parameters:
        `seconds` - the datasource login time limit

    - #### setLogWriter

          public void setLogWriter​(java.io.PrintWriter out)

      Description copied from interface: `XQDataSource`
      Sets the log writer for this `XQDataSource` object to the given `java.io.PrintWriter` object. The log writer is a character output stream to which all logging and tracing messages for this datasource will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. When a `XQDataSource` object is created the log writer is initially `null`; in other words, the default is for logging to be disabled.
      Specified by:
        `setLogWriter` in interface `XQDataSource`
      Parameters:
        `out` - the new log writer; to disable logging, set to `null`

    - #### setProperties

          public void setProperties​(java.util.Properties props)
                             throws XQException

      Description copied from interface: `XQDataSource`
      Sets the data source properties from the specified `Properties` instance. Properties set before this call will still apply but those with the same name as any of these properties will be replaced. Properties set after this call also apply and may replace properties set during this call.

      If the implementation does not support one or more of the given property names, or if it can determine that the value given for a specific property is invalid, then an exception is thrown. If an exception is thrown, then no previous value is overwritten. is invalid, then an exception is raised.

      Specified by:
        `setProperties` in interface `XQDataSource`
      Parameters:
        `props` - the list of properties to set
      Throws:
        `XQException` - if (1) a given property is not recognized, (2) the value for a given property is determined to be invalid, or (3) the `props` parameter is `null`

    - #### setProperty

          public void setProperty​(java.lang.String name,
                                  java.lang.String value)
                           throws XQException

      Set a configuration property. The properties that are supported, and their meanings, are the same as the properties that can be obtained using "set" methods; for example `setProperty("dtdValidation", "true")` has the same effect as `setDtdValidation("true")`.

      Further Saxon configuration properties are available using the URIs defined as constants in `FeatureKeys`

      Specified by:
        `setProperty` in interface `XQDataSource`
      Parameters:
        `name` - the name of the configuration property
        `value` - the value of the configuration property
      Throws:
        `XQException` - if the property name or value is invalid

    - #### setAllowExternalFunctions

          public void setAllowExternalFunctions​(java.lang.String value)

      Say whether queries are allowed to call external functions.
      Parameters:
        `value` - set to "true" if external function calls are allowed (default) or "false" otherwise

    - #### getAllowExternalFunctions

          public java.lang.String getAllowExternalFunctions()

      Ask whether queries are allowed to call external functions.
      Returns:
        "true" if external function calls are allowed, "false" otherwise

    - #### setDtdValidation

          public void setDtdValidation​(java.lang.String value)

      Say whether source documents are to be parsed with DTD validation enabled
      Parameters:
        `value` - "true" if DTD validation is to be enabled, otherwise "false". Default is "false".

    - #### getDtdValidation

          public java.lang.String getDtdValidation()

      Ask whether source documents are to be parsed with DTD validation enabled
      Returns:
        "true" if DTD validation is to be enabled, otherwise "false". Default is "false".

    - #### setExpandAttributeDefaults

          public void setExpandAttributeDefaults​(java.lang.String value)

      Say whether whether fixed and default values defined in a schema or DTD will be expanded. By default, or if the value is "true" (and for conformance with the specification) validation against a DTD or schema will cause default values defined in the schema or DTD to be inserted into the document. Setting this feature to "false" suppresses this behaviour. In the case of DTD-defined defaults this only works if the XML parser reports whether each attribute was specified in the source or generated by expanding a default value. Not all XML parsers report this information.
      Parameters:
        `value` - "true" if default values are to be expanded, otherwise "false". Default is "true".

    - #### getExpandAttributeDefaults

          public java.lang.String getExpandAttributeDefaults()

      Ask whether fixed or default values defined in a schema or DTD will be expanded
      Returns:
        "true" if such values will be expanded, otherwise "false"

    - #### setExpandXInclude

          public void setExpandXInclude​(java.lang.String value)

      Say whether XInclude processing is to be applied to source documents
      Parameters:
        `value` - "true" if XInclude directives are to expanded, otherwise "false". Default is "false".

    - #### getExpandXInclude

          public java.lang.String getExpandXInclude()

      Ask whether XInclude processing is to be applied to source documents
      Returns:
        "true" if XInclude directives are to expanded, otherwise "false". Default is "false".

    - #### setRetainLineNumbers

          public void setRetainLineNumbers​(java.lang.String value)

      Say whether source documents should have line and column information retained. This information is available via extension functions `saxon:line-number()` and `saxon:column-number()`
      Parameters:
        `value` - "true" if line and column information is to be retained, otherwise "false". Default is "false".

    - #### getRetainLineNumbers

          public java.lang.String getRetainLineNumbers()

      Ask whether line and column information will be retained for source documents
      Returns:
        "true" if line and column information is retained, otherwise "false"

    - #### setSchemaValidationMode

          public void setSchemaValidationMode​(java.lang.String value)

      Say whether source documents should be validated against a schema
      Parameters:
        `value` - set to "strict" if source documents are to be subjected to strict validation, "lax" if source documents are to be subjected to lax validation, "skip" if source documents are not to be subjected to schema validation

    - #### getSchemaValidationMode

          public java.lang.String getSchemaValidationMode()

      Ask whether source documents will be validated against a schema
      Returns:
        "strict" if source documents are to be subjected to strict validation, "lax" if source documents are to be subjected to lax validation, "skip" if source documents are not to be subjected to schema validation

    - #### setStripWhitespace

          public void setStripWhitespace​(java.lang.String value)

      Say whether whitespace should be stripped when loading source documents
      Parameters:
        `value` - "all" if all whitespace text nodes are to be stripped, "ignorable" if only whitespace text nodes in elements defined in a schema or DTD as having element-only content are to be stripped, "none" if no whitespace text nodes are to be stripped

    - #### getStripWhitespace

          public java.lang.String getStripWhitespace()

      Ask whether whitespace will be stripped when loading source documents
      Returns:
        "all" if all whitespace text nodes are to be stripped, "ignorable" if only whitespace text nodes in elements defined in a schema or DTD as having element-only content are to be stripped, "none" if no whitespace text nodes are to be stripped

    - #### setUseXsiSchemaLocation

          public void setUseXsiSchemaLocation​(java.lang.String value)

      Say whether the schema processor is to take account of xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes encountered in an instance document being validated
      Parameters:
        `value` - set to "true" if these attributes are to be recognized (default) or "false" otherwise

    - #### getUseXsiSchemaLocation

          public java.lang.String getUseXsiSchemaLocation()

      Ask whether the schema processor is to take account of xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes encountered in an instance document being validated
      Returns:
        "true" if these attributes are to be recognized (default) or "false" otherwise

    - #### setXmlVersion

          public void setXmlVersion​(java.lang.String value)

      Say whether XML 1.0 or XML 1.1 rules for XML names are to be followed
      Parameters:
        `value` - "1.0" (default) if XML 1.0 rules are to be used, "1.1" if XML 1.1 rules apply

    - #### getXmlVersion

          public java.lang.String getXmlVersion()

      Ask whether XML 1.0 or XML 1.1 rules for XML names are to be followed
      Returns:
        "1.0" if XML 1.0 rules are to be used, "1.1" if XML 1.1 rules apply

    - #### setXsdVersion

          public void setXsdVersion​(java.lang.String value)

      Say whether XML Schema 1.0 syntax must be used or whether XML Schema 1.1 features are allowed
      Parameters:
        `value` - "1.0" (default) if XML Schema 1.0 rules are to be followed, "1.1" if XML Schema 1.1 features may be used

    - #### getXsdVersion

          public java.lang.String getXsdVersion()

      Ask whether XML Schema 1.0 syntax must be used or whether XML Schema 1.1 features are allowed
      Returns:
        "1.0" (default) if XML Schema 1.0 rules are to be followed, "1.1" if XML Schema 1.1 features may be used

    - #### registerExtensionFunction

          public void registerExtensionFunction​(ExtensionFunctionDefinition function)

      Register an extension function that is to be made available within any query. This method allows deep integration of an extension function implemented as an instance of `ExtensionFunctionDefinition`, using an arbitrary name and namespace. This supplements the ability to call arbitrary Java methods using a namespace and local name that are related to the Java class and method name.

      This method is a Saxon extension to the XQJ interface

      Parameters:
        `function` - the class that implements the extension function. This must be a class that extends `ExtensionFunctionCall`, and it must have a public zero-argument constructor
      Throws:
        `java.lang.IllegalArgumentException` - if the class cannot be instantiated or does not extend `ExtensionFunctionCall`
      Since:
        9.2