DataHandler (Jython API documentation)
Date: 2024-08-18

com.ziclix.python.sql

## Class DataHandler

- java.lang.Object
- - com.ziclix.python.sql.DataHandler

- Direct Known Subclasses:
    FilterDataHandler, Jython22DataHandler

      public class DataHandler
      extends java.lang.Object

  The DataHandler is responsible mapping the JDBC data type to a Jython object. Depending on the version of the JDBC implementation and the particulars of the driver, the type mapping can be significantly different. This interface can also be used to change the behaviour of the default mappings provided by the cursor. This might be useful in handling more complicated data types such as BLOBs, CLOBs and Arrays.
  Author:
    brian zimmer

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DataHandler()` Handle most generic Java data types.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `PyObject` | `__chain__()` Returns a list of datahandlers chained together through the use of delegation.
    `static boolean` | `checkNull(java.sql.PreparedStatement stmt, int index, PyObject object, int type)` Handles checking if the object is null or None and setting it on the statement.
    `java.lang.String` | `getMetaDataName(PyObject name)` Some database vendors are case sensitive on calls to DatabaseMetaData, most notably Oracle.
    `Procedure` | `getProcedure(PyCursor cursor, PyObject name)` A factory method for determing the correct procedure class to use per the cursor type.
    `PyObject` | `getPyObject(java.sql.CallableStatement stmt, int col, int type)` Given a CallableStatement, column and type, return the appropriate Jython object.
    `PyObject` | `getPyObject(java.sql.ResultSet set, int col, int type)` Given a ResultSet, column and type, return the appropriate Jython object.
    `PyObject` | `getRowId(java.sql.Statement stmt)` Returns the row id of the last executed statement.
    `static DataHandler` | `getSystemDataHandler()` Build the DataHandler chain depending on the VM.
    `void` | `postExecute(java.sql.Statement stmt)` A callback after successfully executing the statement.
    `void` | `preExecute(java.sql.Statement stmt)` A callback prior to each execution of the statement.
    `static byte[]` | `read(java.io.InputStream stream)` Consume the InputStream into an byte array and close the InputStream.
    `static java.lang.String` | `read(java.io.Reader reader)` Consume the Reader into a String and close the Reader.
    `void` | `registerOut(java.sql.CallableStatement statement, int index, int colType, int dataType, java.lang.String dataTypeName)` Called when a stored procedure or function is executed and OUT parameters need to be registered with the statement.
    `void` | `setJDBCObject(java.sql.PreparedStatement stmt, int index, PyObject object)` Any .execute() which uses prepared statements will receive a callback for deciding how to map the PyObject to the appropriate JDBC type.
    `void` | `setJDBCObject(java.sql.PreparedStatement stmt, int index, PyObject object, int type)` Any .execute() which uses prepared statements will receive a callback for deciding how to map the PyObject to the appropriate JDBC type.
    `java.lang.String` | `toString()` Returns the classname of this datahandler.

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

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

- - ### Constructor Detail

    - #### DataHandler

          public DataHandler()

      Handle most generic Java data types.

  - ### Method Detail

    - #### getMetaDataName

          public java.lang.String getMetaDataName(PyObject name)

      Some database vendors are case sensitive on calls to DatabaseMetaData, most notably Oracle. This callback allows a DataHandler to affect the name.

    - #### getProcedure

          public Procedure getProcedure(PyCursor cursor,
                                        PyObject name)
                                 throws java.sql.SQLException

      A factory method for determing the correct procedure class to use per the cursor type.
      Parameters:
        `cursor` - an open cursor
        `name` - the name of the procedure to invoke
      Returns:
        an instance of a Procedure
      Throws:
        `java.sql.SQLException`

    - #### getRowId

          public PyObject getRowId(java.sql.Statement stmt)
                            throws java.sql.SQLException

      Returns the row id of the last executed statement.
      Parameters:
        `stmt` - the current statement
      Returns:
        the row id of the last executed statement or None
      Throws:
        `java.sql.SQLException` - thrown if an exception occurs

    - #### preExecute

          public void preExecute(java.sql.Statement stmt)
                          throws java.sql.SQLException

      A callback prior to each execution of the statement. If the statement is a PreparedStatement, all the parameters will have been set.
      Throws:
        `java.sql.SQLException`

    - #### postExecute

          public void postExecute(java.sql.Statement stmt)
                           throws java.sql.SQLException

      A callback after successfully executing the statement.
      Throws:
        `java.sql.SQLException`

    - #### setJDBCObject

          public void setJDBCObject(java.sql.PreparedStatement stmt,
                                    int index,
                                    PyObject object)
                             throws java.sql.SQLException

      Any .execute() which uses prepared statements will receive a callback for deciding how to map the PyObject to the appropriate JDBC type.
      Parameters:
        `stmt` - the current PreparedStatement
        `index` - the index for which this object is bound
        `object` - the PyObject in question
      Throws:
        `java.sql.SQLException`

    - #### setJDBCObject

          public void setJDBCObject(java.sql.PreparedStatement stmt,
                                    int index,
                                    PyObject object,
                                    int type)
                             throws java.sql.SQLException

      Any .execute() which uses prepared statements will receive a callback for deciding how to map the PyObject to the appropriate JDBC type. The type is the JDBC type as obtained from java.sql.Types.
      Parameters:
        `stmt` - the current PreparedStatement
        `index` - the index for which this object is bound
        `object` - the PyObject in question
        `type` - the java.sql.Types for which this PyObject should be bound
      Throws:
        `java.sql.SQLException`

    - #### getPyObject

          public PyObject getPyObject(java.sql.ResultSet set,
                                      int col,
                                      int type)
                               throws java.sql.SQLException

      Given a ResultSet, column and type, return the appropriate Jython object.

      Note: DO NOT iterate the ResultSet.

      Parameters:
        `set` - the current ResultSet set to the current row
        `col` - the column number (adjusted properly for JDBC)
        `type` - the column type
      Throws:
        `java.sql.SQLException` - if the type is unmappable

    - #### getPyObject

          public PyObject getPyObject(java.sql.CallableStatement stmt,
                                      int col,
                                      int type)
                               throws java.sql.SQLException

      Given a CallableStatement, column and type, return the appropriate Jython object.
      Parameters:
        `stmt` - the CallableStatement
        `col` - the column number (adjusted properly for JDBC)
        `type` - the column type
      Throws:
        `java.sql.SQLException` - if the type is unmappable

    - #### registerOut

          public void registerOut(java.sql.CallableStatement statement,
                                  int index,
                                  int colType,
                                  int dataType,
                                  java.lang.String dataTypeName)
                           throws java.sql.SQLException

      Called when a stored procedure or function is executed and OUT parameters need to be registered with the statement.
      Parameters:
        `statement` -
        `index` - the JDBC offset column number
        `colType` - the column as from DatabaseMetaData (eg, procedureColumnOut)
        `dataType` - the JDBC datatype from Types
        `dataTypeName` - the JDBC datatype name
      Throws:
        `java.sql.SQLException`

    - #### checkNull

          public static final boolean checkNull(java.sql.PreparedStatement stmt,
                                                int index,
                                                PyObject object,
                                                int type)
                                         throws java.sql.SQLException

      Handles checking if the object is null or None and setting it on the statement.
      Returns:
        true if the object is null and was set on the statement, false otherwise
      Throws:
        `java.sql.SQLException`

    - #### read

          public static final byte[] read(java.io.InputStream stream)

      Consume the InputStream into an byte array and close the InputStream.
      Returns:
        the contents of the InputStream a byte[]

    - #### read

          public static java.lang.String read(java.io.Reader reader)

      Consume the Reader into a String and close the Reader.
      Returns:
        the contents of the Reader as a String

    - #### getSystemDataHandler

          public static final DataHandler getSystemDataHandler()

      Build the DataHandler chain depending on the VM. This guarentees a DataHandler but might additionally chain a JDBC2.0 or JDBC3.0 implementation.
      Returns:
        a DataHandler configured for the VM version

    - #### __chain__

          public PyObject __chain__()

      Returns a list of datahandlers chained together through the use of delegation.
      Returns:
        a list of datahandlers

    - #### toString

          public java.lang.String toString()

      Returns the classname of this datahandler.
      Overrides:
        `toString` in class `java.lang.Object`

Jython homepage