org.apache.xalan.lib.sql

## Class XConnection

- java.lang.Object
- - org.apache.xalan.lib.sql.XConnection

-     public class XConnection
      extends java.lang.Object

  An XSLT extension that allows a stylesheet to access JDBC data. It is accessed by specifying a namespace URI as follows:

          xmlns:sql="http://xml.apache.org/xalan/sql"

  From the stylesheet perspective, XConnection provides 3 extension functions: new(), query(), and close(). Use new() to call one of XConnection constructors, which establishes a JDBC driver connection to a data source and returns an XConnection object. Then use the XConnection object query() method to return a result set in the form of a row-set element. When you have finished working with the row-set, call the XConnection object close() method to terminate the connection.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `XConnection()`
    `XConnection(ExpressionContext exprContext, org.w3c.dom.NodeList list)`
    `XConnection(ExpressionContext exprContext, java.lang.String connPoolName)` Constructs a new XConnection and attempts to connect to a datasource as defined in the `connect(ExpressionContext exprContext, String connPoolName)` method.
    `XConnection(ExpressionContext exprContext, java.lang.String driver, java.lang.String dbURL)`
    `XConnection(ExpressionContext exprContext, java.lang.String driver, java.lang.String dbURL, org.w3c.dom.Element protocolElem)`
    `XConnection(ExpressionContext exprContext, java.lang.String driver, java.lang.String dbURL, java.lang.String user, java.lang.String password)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addParameter(java.lang.String value)` Add an untyped value to the parameter list.
    `void` | `addParameterFromElement(org.w3c.dom.Element e)` Add a single parameter to the parameter list formatted as an Element
    `void` | `addParameterFromElement(org.w3c.dom.NodeList nl)` Add a section of parameters to the Parameter List Do each element from the list
    `void` | `addParameterWithType(java.lang.String value, java.lang.String Type)` Add a typed parameter to the parameter list.
    `void` | `clearParameters()`
    `void` | `close()` Close the connection to the data source.
    `void` | `close(ExpressionContext exprContext, java.lang.Object doc)` Close the connection to the data source.
    `XBooleanStatic` | `connect(ExpressionContext exprContext, org.w3c.dom.Element protocolElem)`
    `XBooleanStatic` | `connect(ExpressionContext exprContext, org.w3c.dom.NodeList list)`
    `XBooleanStatic` | `connect(ExpressionContext exprContext, java.lang.String name)` Returns an XConnection from either a user created `org.apache.xalan.lib.sql.ConnectionPool` or a JNDI datasource.
    `XBooleanStatic` | `connect(ExpressionContext exprContext, java.lang.String driver, java.lang.String dbURL)` Create an XConnection object with just a driver and database URL.
    `XBooleanStatic` | `connect(ExpressionContext exprContext, java.lang.String driver, java.lang.String dbURL, org.w3c.dom.Element protocolElem)` Create an XConnection object with a connection protocol
    `XBooleanStatic` | `connect(ExpressionContext exprContext, java.lang.String driver, java.lang.String dbURL, java.lang.String user, java.lang.String password)` Create an XConnection object with user ID and password.
    `void` | `disableDefaultConnectionPool()` Deprecated. Use setFeature("default-pool-enabled", "false");
    `void` | `disableStreamingMode()` Deprecated. Use setFeature("streaming", "false");
    `void` | `enableDefaultConnectionPool()` Deprecated. Use setFeature("default-pool-enabled", "true");
    `void` | `enableStreamingMode()` Deprecated. Use setFeature("streaming", "true");
    `ConnectionPool` | `getConnectionPool()` Allow the SQL Document to retrive a connection to be used to build the SQL Statement.
    `DTM` | `getError()` Provide access to the last error that occued.
    `java.lang.String` | `getFeature(java.lang.String feature)` Get feature options for this XConnection.
    `DTM` | `pquery(ExpressionContext exprContext, java.lang.String queryString)` Execute a parameterized query statement by instantiating an
    `DTM` | `pquery(ExpressionContext exprContext, java.lang.String queryString, java.lang.String typeInfo)` Execute a parameterized query statement by instantiating an
    `DTM` | `query(ExpressionContext exprContext, java.lang.String queryString)` Execute a query statement by instantiating an
    `void` | `setError(java.lang.Exception excp, ExpressionContext expr)` This is an internal version of Set Error that is called withen XConnection where there is no SQLDocument created yet.
    `void` | `setError(java.lang.Exception excp, SQLDocument doc, java.sql.SQLWarning warn)` Set an error and/or warning on this connection.
    `void` | `setFeature(java.lang.String feature, java.lang.String setting)` Set feature options for this XConnection.
    `void` | `skipRec(ExpressionContext exprContext, java.lang.Object o, int value)` The purpose of this routine is to force the DB cursor to skip forward N records.

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

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

- - ### Constructor Detail

    - #### XConnection

          public XConnection()

    - #### XConnection

          public XConnection(ExpressionContext exprContext,
                             java.lang.String connPoolName)

      Constructs a new XConnection and attempts to connect to a datasource as defined in the `connect(ExpressionContext exprContext, String connPoolName)` method. `org.apache.xalan.lib.sql.ConnectionPool` or a JNDI datasource.
      Parameters:
        `exprContext` - Context automatically passed from the XSLT sheet.
        `name` - The name of the ConnectionPool or the JNDI DataSource path.

    - #### XConnection

          public XConnection(ExpressionContext exprContext,
                             java.lang.String driver,
                             java.lang.String dbURL)

      Parameters:
        `exprContext` -
        `driver` -
        `dbURL` -

    - #### XConnection

          public XConnection(ExpressionContext exprContext,
                             org.w3c.dom.NodeList list)

      Parameters:
        `exprContext` -
        `list` -

    - #### XConnection

          public XConnection(ExpressionContext exprContext,
                             java.lang.String driver,
                             java.lang.String dbURL,
                             java.lang.String user,
                             java.lang.String password)

      Parameters:
        `exprContext` -
        `driver` -
        `dbURL` -
        `user` -
        `password` -

    - #### XConnection

          public XConnection(ExpressionContext exprContext,
                             java.lang.String driver,
                             java.lang.String dbURL,
                             org.w3c.dom.Element protocolElem)

      Parameters:
        `exprContext` -
        `driver` -
        `dbURL` -
        `protocolElem` -

  - ### Method Detail

    - #### connect

          public XBooleanStatic connect(ExpressionContext exprContext,
                                        java.lang.String name)

      Returns an XConnection from either a user created `org.apache.xalan.lib.sql.ConnectionPool` or a JNDI datasource. This method first tries to resolve the passed name against `ConnectionPool`s registered with `ConnectionPoolManager`. If that fails, it attempts to find the name as a JNDI DataSource path.
      Parameters:
        `exprContext` - Context automatically passed from the XSLT sheet.
        `name` - The name of the ConnectionPool or the JNDI DataSource path.

    - #### connect

          public XBooleanStatic connect(ExpressionContext exprContext,
                                        java.lang.String driver,
                                        java.lang.String dbURL)

      Create an XConnection object with just a driver and database URL.
      Parameters:
        `exprContext` -
        `driver` - JDBC driver of the form foo.bar.Driver.
        `dbURL` - database URL of the form jdbc:subprotocol:subname.

    - #### connect

          public XBooleanStatic connect(ExpressionContext exprContext,
                                        org.w3c.dom.Element protocolElem)

      Parameters:
        `exprContext` -
        `protocolElem` -

    - #### connect

          public XBooleanStatic connect(ExpressionContext exprContext,
                                        org.w3c.dom.NodeList list)

      Parameters:
        `exprContext` -
        `list` -

    - #### connect

          public XBooleanStatic connect(ExpressionContext exprContext,
                                        java.lang.String driver,
                                        java.lang.String dbURL,
                                        java.lang.String user,
                                        java.lang.String password)

      Create an XConnection object with user ID and password.
      Parameters:
        `exprContext` -
        `driver` - JDBC driver of the form foo.bar.Driver.
        `dbURL` - database URL of the form jdbc:subprotocol:subname.
        `user` - user ID.
        `password` - connection password.

    - #### connect

          public XBooleanStatic connect(ExpressionContext exprContext,
                                        java.lang.String driver,
                                        java.lang.String dbURL,
                                        org.w3c.dom.Element protocolElem)

      Create an XConnection object with a connection protocol
      Parameters:
        `exprContext` -
        `driver` - JDBC driver of the form foo.bar.Driver.
        `dbURL` - database URL of the form jdbc:subprotocol:subname.
        `protocolElem` - list of string tag/value connection arguments, normally including at least "user" and "password".

    - #### getConnectionPool

          public ConnectionPool getConnectionPool()

      Allow the SQL Document to retrive a connection to be used to build the SQL Statement.

    - #### query

          public DTM query(ExpressionContext exprContext,
                           java.lang.String queryString)

      Execute a query statement by instantiating an
      Parameters:
        `exprContext` -
        `queryString` - the SQL query.
      Returns:
        XStatement implements NodeIterator.
      Throws:
        `java.sql.SQLException`

    - #### pquery

          public DTM pquery(ExpressionContext exprContext,
                            java.lang.String queryString)

      Execute a parameterized query statement by instantiating an
      Parameters:
        `exprContext` -
        `queryString` - the SQL query.
      Returns:
        XStatement implements NodeIterator.
      Throws:
        `java.sql.SQLException`

    - #### pquery

          public DTM pquery(ExpressionContext exprContext,
                            java.lang.String queryString,
                            java.lang.String typeInfo)

      Execute a parameterized query statement by instantiating an
      Parameters:
        `exprContext` -
        `queryString` - the SQL query.
        `typeInfo` -
      Returns:
        XStatement implements NodeIterator.
      Throws:
        `java.sql.SQLException`

    - #### skipRec

          public void skipRec(ExpressionContext exprContext,
                              java.lang.Object o,
                              int value)

      The purpose of this routine is to force the DB cursor to skip forward N records. You should call this function after [p]query to help with pagination. i.e. Perfrom your select, then skip forward past the records you read previously.
      Parameters:
        `exprContext` -
        `o` -
        `value` -

    - #### addParameter

          public void addParameter(java.lang.String value)

      Add an untyped value to the parameter list.
      Parameters:
        `value` -

    - #### addParameterWithType

          public void addParameterWithType(java.lang.String value,
                                           java.lang.String Type)

      Add a typed parameter to the parameter list.
      Parameters:
        `value` -
        `Type` -

    - #### addParameterFromElement

          public void addParameterFromElement(org.w3c.dom.Element e)

      Add a single parameter to the parameter list formatted as an Element
      Parameters:
        `e` -

    - #### addParameterFromElement

          public void addParameterFromElement(org.w3c.dom.NodeList nl)

      Add a section of parameters to the Parameter List Do each element from the list
      Parameters:
        `nl` -

    - #### clearParameters

          public void clearParameters()

    - #### enableDefaultConnectionPool

          public void enableDefaultConnectionPool()

      Deprecated. Use setFeature("default-pool-enabled", "true");
      There is a problem with some JDBC drivers when a Connection is open and the JVM shutsdown. If there is a problem, there is no way to control the currently open connections in the pool. So for the default connection pool, the actuall pooling mechinsm is disabled by default. The Stylesheet designer can re-enabled pooling to take advantage of connection pools. The connection pool can even be disabled which will close all outstanding connections.

    - #### disableDefaultConnectionPool

          public void disableDefaultConnectionPool()

      Deprecated. Use setFeature("default-pool-enabled", "false");
      See enableDefaultConnectionPool

    - #### enableStreamingMode

          public void enableStreamingMode()

      Deprecated. Use setFeature("streaming", "true");
      Control how the SQL Document uses memory. In Streaming Mode, memory consumption is greatly reduces so you can have queries of unlimited size but it will not let you traverse the data more than once.

    - #### disableStreamingMode

          public void disableStreamingMode()

      Deprecated. Use setFeature("streaming", "false");
      Control how the SQL Document uses memory. In Streaming Mode, memory consumption is greatly reduces so you can have queries of unlimited size but it will not let you traverse the data more than once.

    - #### getError

          public DTM getError()

      Provide access to the last error that occued. This error may be over written when the next operation occurs.

    - #### close

          public void close()
                     throws java.sql.SQLException

      Close the connection to the data source.
      Throws:
        `java.sql.SQLException`

    - #### close

          public void close(ExpressionContext exprContext,
                            java.lang.Object doc)
                     throws java.sql.SQLException

      Close the connection to the data source. Only close the connections for a single document.
      Throws:
        `java.sql.SQLException`

    - #### setError

          public void setError(java.lang.Exception excp,
                               ExpressionContext expr)

      This is an internal version of Set Error that is called withen XConnection where there is no SQLDocument created yet. As in the Connect statement or creation of the ConnectionPool.

    - #### setError

          public void setError(java.lang.Exception excp,
                               SQLDocument doc,
                               java.sql.SQLWarning warn)

      Set an error and/or warning on this connection.

    - #### setFeature

          public void setFeature(java.lang.String feature,
                                 java.lang.String setting)

      Set feature options for this XConnection.
      Parameters:
        `feature` - The name of the feature being set, currently supports (streaming, inline-variables, multiple-results, cache-statements, default-pool-enabled).
        `setting` - The new setting for the specified feature, currently "true" is true and anything else is false.

    - #### getFeature

          public java.lang.String getFeature(java.lang.String feature)

      Get feature options for this XConnection.
      Parameters:
        `feature` - The name of the feature to get the setting for.
      Returns:
        The setting of the specified feature. Will be "true" or "false" (null if the feature is not known)

Copyright © 2023 Apache XML Project. All Rights Reserved.