com.tibco.datagrid

## Interface Statement

- All Superinterfaces:
    java.lang.AutoCloseable

      public interface Statement
      extends java.lang.AutoCloseable

  A statement object is used to execute SQL and return a resultset.

  To create a statement object, call `Session.createStatement`.

  A program that creates a statement object should explicitly call `Statement.close` to reclaim its resources.

  Since Version 4.10: Whenever a `Statement` that did not have its `Statement.close` method called is garbage collected, the native resources will be reclaimed automatically. This behavior is controlled by the com.tibco.tibdg.autoclose System Property. If the property is not set or set to "cleanup" (the default), the native resources will be reclaimed as if the `Statement.close` method had been called. If the System Property is set to "warn", a warning will be printed to stderr instead of doing the cleanup. If the property is set to "inactive", this feature will not be activated.

  This interface is implemented internally. Applications do not implement this interface.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `TIBDG_STATEMENT_CONSISTENCY_GLOBAL_SNAPSHOT` Global snapshot consistency; property value constant.
    `static java.lang.String` | `TIBDG_STATEMENT_CONSISTENCY_SNAPSHOT` Snapshot consistency; property value constant.
    `static java.lang.String` | `TIBDG_STATEMENT_PROPERTY_DOUBLE_FETCH_TIMEOUT` Property name for the Statement fetch timeout; double.
    `static java.lang.String` | `TIBDG_STATEMENT_PROPERTY_DOUBLE_UPDATE_TIMEOUT` Property name for the Statement update timeout; double.
    `static java.lang.String` | `TIBDG_STATEMENT_PROPERTY_LONG_PREFETCH` Property name for Statement query prefetch; long.
    `static java.lang.String` | `TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY` Property name for Statement consistency; string.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearParameters()` Clears all of the parameter values set on the statement object.
    `void` | `close()` Close the statement object.
    `ResultSet` | `executeQuery(java.util.Properties props)` Executes the query on the statement object and returns the resultset object.
    `long` | `executeUpdate(java.util.Properties props)` Executes the SQL statement in this `Statement` object, which must be an SQL Data Manipulation Language (DML) statement, such as `INSERT`.
    `long` | `getParameterCount()` Returns the number of parameters in the statement.
    `ResultSetMetadata` | `getResultSetMetadata()` Get the metadata associated with a statement
    `void` | `setDateTime(int parameterIndex, TibDateTime value)` Sets a TibDateTime value to a parameter number in a statement object.
    `void` | `setDouble(int parameterIndex, double value)` Sets a double value to a parameter number in a statement object.
    `void` | `setLong(int parameterIndex, long value)` Sets a long value to a parameter number in a statement object.
    `void` | `setNull(int parameterIndex)` Sets an empty value for a parameter number in a statement object.
    `void` | `setOpaque(int parameterIndex, byte[] value)` Sets an opaque value to a parameter number in a statement object.
    `void` | `setString(int parameterIndex, java.lang.String value)` Sets a string value to a parameter number in a statement object.

- - ### Field Detail

    - #### TIBDG_STATEMENT_PROPERTY_LONG_PREFETCH

          static final java.lang.String TIBDG_STATEMENT_PROPERTY_LONG_PREFETCH

      Property name for Statement query prefetch; long.

      When creating a statement, supply this property to `Session.createStatement`. Its value determines the maximum number of rows that will be prefetched from the data grid when executing a query. This property can also be supplied to `Statement.executeQuery` to override the value that was used when the statement was created. If not specified or a value less than or equal to 0 is specified, a default prefetch of 256 is used.

      See Also:
        Constant Field Values

    - #### TIBDG_STATEMENT_CONSISTENCY_GLOBAL_SNAPSHOT

          static final java.lang.String TIBDG_STATEMENT_CONSISTENCY_GLOBAL_SNAPSHOT

      Global snapshot consistency; property value constant. This constant is one possible value of the property `Statement.TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY` in the methods `Session.createStatement` and `Statement.executeQuery`. This value will cause a global snapshot to be taken across all nodes in the grid when a query is executed, which will then be used when iterating through the results. A global snapshot will ensure no partially committed transactions that span multiple nodes are observed in the query results at the cost of needing to coordinate the global snapshot when executing the query.
      See Also:
        Constant Field Values

    - #### TIBDG_STATEMENT_CONSISTENCY_SNAPSHOT

          static final java.lang.String TIBDG_STATEMENT_CONSISTENCY_SNAPSHOT

      Snapshot consistency; property value constant. This constant is one possible value of the property `Statement.TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY` in the methods `Session.createStatement` and `Statement.executeQuery`. This value will cause a snapshot to be taken at each node independently when a query is executed, which will then be used when iterating through the results. A snapshot taken at each node does not require waiting to create a global snapshot across the entire grid when creating the iterator but could result in a partially committed transaction that spanned multiple nodes being observed in the results.
      See Also:
        Constant Field Values

    - #### TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY

          static final java.lang.String TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY

      Property name for Statement consistency; string.

      When creating a statement, supply this property to `Session.createStatement`. Its value determines the consistency when executing a query and whether or not a global snapshot needs to be taken. This property can also be supplied to `Statement.executeQuery` to override the value that was used when the statement was created.

      Supported values are `Statement.TIBDG_STATEMENT_CONSISTENCY_GLOBAL_SNAPSHOT` and `Statement.TIBDG_STATEMENT_CONSISTENCY_SNAPSHOT`

      See Also:
        Constant Field Values

    - #### TIBDG_STATEMENT_PROPERTY_DOUBLE_FETCH_TIMEOUT

          static final java.lang.String TIBDG_STATEMENT_PROPERTY_DOUBLE_FETCH_TIMEOUT

      Property name for the Statement fetch timeout; double.

      This value determines how long (in seconds) the application will wait for the next batch of rows before timing out. If this property is not supplied the current timeout for the parent Connection is used. If a value of zero is supplied then there will be no limit to how long the application will wait. The use of an unlimited timeout is NOT advised in production environments because there are certain error situations that can result in the application waiting forever for a response that will not come. An unlimited timeout could be used in testing/development to discover how long a given query takes to execute so that a meaningful timeout can be set in production. When creating a statement, supply this property to `Session.createStatement`. This property can also be supplied to `Statement.executeQuery` to override the value that was used when the statement was created.

      See Also:
        Constant Field Values

    - #### TIBDG_STATEMENT_PROPERTY_DOUBLE_UPDATE_TIMEOUT

          static final java.lang.String TIBDG_STATEMENT_PROPERTY_DOUBLE_UPDATE_TIMEOUT

      Property name for the Statement update timeout; double. This value determines how long (in seconds) the application will wait for a reply to an ExecuteUpdate request, on a statement, before timing out. If this property is not supplied the current timeout for the parent Connection is used. If a value of zero is supplied then there will be no limit to how long the application will wait. The use of an unlimited timeout is NOT advised in production environments because there are certain error situations that can result in the application waiting forever for a response that will not come. An unlimited timeout could be used in testing/development to discover how long a given update takes to execute so that a meaningful timeout can be set in production. When creating a statement, supply this property to `Session.createStatement`.. This property can also be supplied to `Statement.executeUpdate` to override value that was used when the statement was created.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### executeQuery

          ResultSet executeQuery(java.util.Properties props)
                          throws DataGridException,
                                 DataGridInvalidArgumentException

      Executes the query on the statement object and returns the resultset object.

      Cannot be called if there are any open resultsets on the statement object.

      Parameters:
        `props` - Optional, null to omit
        - `Statement.TIBDG_STATEMENT_PROPERTY_LONG_PREFETCH`
        - `Statement.TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY`
        - `Statement.TIBDG_STATEMENT_PROPERTY_DOUBLE_FETCH_TIMEOUT`
      Returns:
        `ResultSet`
      Throws:
        `DataGridException` - in case of failures
        `DataGridInvalidArgumentException`

    - #### executeUpdate

          long executeUpdate(java.util.Properties props)
                      throws DataGridException,
                             DataGridInvalidArgumentException,
                             DataGridNotPermittedException

      Executes the SQL statement in this `Statement` object, which must be an SQL Data Manipulation Language (DML) statement, such as `INSERT`.
      Parameters:
        `props` - Optional, null to omit
        - `Statement.TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY`
        - `Statement.TIBDG_STATEMENT_PROPERTY_DOUBLE_UPDATE_TIMEOUT`
      Returns:
        The count of rows affected by the statement execution.
      Throws:
        `DataGridException` - in case of failure to execute on the datagrid.
        `DataGridInvalidArgumentException` - in case of null or invalid statement.
        `DataGridNotPermittedException` - When invoked on other than a DML statement.

    - #### setDateTime

          void setDateTime(int parameterIndex,
                           TibDateTime value)
                    throws DataGridException

      Sets a TibDateTime value to a parameter number in a statement object.

      Copies the datetime parameter so that the program is allowed to free or modify it after the function returns. Note that parameter numbers start from 1. Setting the same parameter multiple times is allowed, even with different types, as long as when ExecuteQuery is called all parameters are set and have the correct types.

      Parameters:
        `parameterIndex` - The parameter number to set.
        `value` - The datetime value to set into the statement.
      Throws:
        `DataGridException` - in case of failures

    - #### setDouble

          void setDouble(int parameterIndex,
                         double value)
                  throws DataGridException

      Sets a double value to a parameter number in a statement object.

      Note that parameter numbers start from 1. Setting the same parameter multiple times is allowed, even with different types, as long as when ExecuteQuery is called all parameters are set and have the correct types.

      Parameters:
        `parameterIndex` - The parameter number to set.
        `value` - The double value to set into the statement.
      Throws:
        `DataGridException` - in case of failures

    - #### setLong

          void setLong(int parameterIndex,
                       long value)
                throws DataGridException

      Sets a long value to a parameter number in a statement object.

      Note that parameter numbers start from 1. Setting the same parameter multiple times is allowed, even with different types, as long as when ExecuteQuery is called all parameters are set and have the correct types.

      Parameters:
        `parameterIndex` - The parameter number to set.
        `value` - The long value to set into the statement.
      Throws:
        `DataGridException` - in case of failures

    - #### setOpaque

          void setOpaque(int parameterIndex,
                         byte[] value)
                  throws DataGridException

      Sets an opaque value to a parameter number in a statement object.

      Copies the opaque parameter so that the program is allowed to free or modify it after the function returns. Note that parameter numbers start from 1. Setting the same parameter multiple times is allowed, even with different types, as long as when ExecuteQuery is called all parameters are set and have the correct types.

      Parameters:
        `parameterIndex` - The parameter number to set.
        `value` - The opaque value to set into the statement.
      Throws:
        `DataGridException` - in case of failures

    - #### setString

          void setString(int parameterIndex,
                         java.lang.String value)
                  throws DataGridException

      Sets a string value to a parameter number in a statement object.

      Note that parameter numbers start from 1. Setting the same parameter multiple times is allowed, even with different types, as long as when ExecuteQuery is called all parameters are set and have the correct types.

      Parameters:
        `parameterIndex` - The parameter number to set.
        `value` - The string value to set into the statement.
      Throws:
        `DataGridException` - in case of failures

    - #### setNull

          void setNull(int parameterIndex)
                throws DataGridException

      Sets an empty value for a parameter number in a statement object.

      Note that parameter numbers start from 1. Setting the same parameter multiple times is allowed, even with different types, as long as when ExecuteQuery is called all parameters are set and have the correct types.

      Parameters:
        `parameterIndex` - The parameter number to set.
      Throws:
        `DataGridException` - in case of failures

    - #### clearParameters

          void clearParameters()
                        throws DataGridException

      Clears all of the parameter values set on the statement object.

      After calling this function, all parameters must be set again before calling ExecuteQuery. A partially bound statement object may be closed without calling this function.

      Throws:
        `DataGridException` - in case of failures

    - #### getResultSetMetadata

          ResultSetMetadata getResultSetMetadata()
                                          throws DataGridException

      Get the metadata associated with a statement
      Returns:
        `ResultSetMetadata`
      Throws:
        `DataGridException` - in case of failures

    - #### getParameterCount

          long getParameterCount()
                          throws DataGridException

      Returns the number of parameters in the statement.
      Returns:
        The number of parameters in the statement.
      Throws:
        `DataGridException` - in case of failures

    - #### close

          void close()
              throws DataGridException

      Close the statement object.

      Note that all resultset objects must also be closed to allow for the statement's resources to also be reclaimed.

      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Throws:
        `DataGridException` - in case of failures