com.tibco.datagrid

## Interface Connection

- All Superinterfaces:
    java.lang.AutoCloseable

      public interface Connection
      extends java.lang.AutoCloseable

  Applications use a connection object to create sessions

  To create a Connection object, call `DataGrid.connect`.

  A program that creates a connection must explicitly call `Connection.close` to reclaim its resources.

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

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static long` | `TIBDG_CONNECTION_BINDSTRATEGY_BALANCED`
    `static long` | `TIBDG_CONNECTION_BINDSTRATEGY_NAMED`
    `static long` | `TIBDG_CONNECTION_BINDSTRATEGY_RANDOM`
    `static java.lang.String` | `TIBDG_CONNECTION_HTTPS_CONNECTION_TRUST_EVERYONE` Property name to Trust any realm server; property value constant.
    `static java.lang.String` | `TIBDG_CONNECTION_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE` Trust a realm server if its certificate is in a trust file; property value constant.
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_BOOLEAN_IMMUTABLE_ROWS` Property to specify immutability of rows returned from ResultSet/Get APIs.
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_DOUBLE_CONNECT_WAIT_TIME` Property name for initial connection timeout; double.
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_DOUBLE_TIMEOUT` Property name for connection timeout; double.
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_LONG_BINDSTRATEGY` Property name for specifying how a client chooses a proxy to establish a connection
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_LONG_CONNECT_NUMRESPONSES` Property name to cutoff wait time using TIBDG_BINDSTRATEGY_RANDOM or TIBDG_CONNECTION_BINDSTRATEGY_BALANCED No effect for other bind strategies After receiving this many responses, the client will stop looking for additional responses
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_LONG_OWNER_ID` Property to specify owner ID of this connection; long.
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_LONG_REALM_CONNECT_RETRIES` Property name for initial realm connection retries; long.
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_LONG_TRANSPORT_TYPE` Property to indicate the type of transport the client will use to connect to proxies
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_STRING_CLIENT_LABEL` Property name for client label; string.
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_STRING_CONNECT_PROXYNAMES` Property name for specifying pipe '|' delimited list of proxy names for TIBDG_CONNECTION_BINDSTRATEGY_NAMED
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_STRING_GRIDNAME` Property name for data grid name; string.
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_STRING_REALMURL` Property name for realm server url; string.
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_STRING_SECONDARY_REALM` Property name for specifying secondary/backup realm server; string.
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_STRING_TRUST_FILE` Property name for secure realm server trust file; string.
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_STRING_TRUST_TYPE` Property name for secure realm server trust type; long.
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_STRING_USERNAME` Property name for realm server username; string.
    `static java.lang.String` | `TIBDG_CONNECTION_PROPERTY_STRING_USERPASSWORD` Property name for realm server password; string.
    `static long` | `TIBDG_CONNECTION_TRANSPORT_TYPE_AUTO`
    `static long` | `TIBDG_CONNECTION_TRANSPORT_TYPE_DTCP`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close a connection object.
    `Session` | `createSession(java.util.Properties props)` Create a session object to perform operations.
    `GridMetadata` | `getGridMetadata()` Retrieve the current data grid metadata in an object.
    `GridMetadata` | `getGridMetadata(java.util.Properties props)` Retrieve the current data grid metadata in an object.
    `void` | `interrupt()` Interrupts all outstanding requests on the connection forcing them to return an interrupted exception (`InterruptedException`).

- - ### Field Detail

    - #### TIBDG_CONNECTION_PROPERTY_DOUBLE_CONNECT_WAIT_TIME

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_DOUBLE_CONNECT_WAIT_TIME

      Property name for initial connection timeout; double.

      When connecting to a data grid, supply this property to `DataGrid.connect` This value sets the fixed amount of time the call will wait inside DataGrid.connect while it collects proxy responses. The value must be set to greater than the client-proxy roundtrip time or the connection will fail and must be retried. Default is 0.1 seconds. This value should generally be kept to less than 10 seconds. For ways to reduce to reduce the binding time, refer to the documentation for `Connection.TIBDG_CONNECTION_PROPERTY_LONG_BINDSTRATEGY` and related properties. Note: this duration applies once the realm connection has been established. If the realm server experiences disruption, up to 5 additional seconds may be required.

      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_LONG_REALM_CONNECT_RETRIES

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_LONG_REALM_CONNECT_RETRIES

      Property name for initial realm connection retries; long.

      When connecting to a data grid, supply this property to `DataGrid.connect`. This value sets the number of times the underlying TIBCO FTL client library will attempt to connect to the Realm. The default is 5.

      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_LONG_BINDSTRATEGY

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_LONG_BINDSTRATEGY

      Property name for specifying how a client chooses a proxy to establish a connection

      Supply this property to `DataGrid.connect`. TIBDG_CONNECTION_BINDSTRATEGY_RANDOM will choose a proxy at random from the responses received. TIBDG_CONNECTION_BINDSTRATEGY_NAMED will choose only a proxy supplied using the property TIBDG_CONNECTION_PROPERTY_STRING_CONNECT_PROXYNAME TIBDG_CONNECTION_BINDSTRATEGY_BALANCED will choose the proxy with the lowest load from the responses received.

      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_BINDSTRATEGY_RANDOM

          static final long TIBDG_CONNECTION_BINDSTRATEGY_RANDOM

      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_BINDSTRATEGY_NAMED

          static final long TIBDG_CONNECTION_BINDSTRATEGY_NAMED

      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_BINDSTRATEGY_BALANCED

          static final long TIBDG_CONNECTION_BINDSTRATEGY_BALANCED

      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_STRING_CONNECT_PROXYNAMES

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_STRING_CONNECT_PROXYNAMES

      Property name for specifying pipe '|' delimited list of proxy names for TIBDG_CONNECTION_BINDSTRATEGY_NAMED

      A client using TIBDG_CONNECTION_BINDSTRATEGY_NAMED will not bind to a proxy not in the list Note: existing proxy names utilizing this reserved character are not eligible

      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_LONG_CONNECT_NUMRESPONSES

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_LONG_CONNECT_NUMRESPONSES

      Property name to cutoff wait time using TIBDG_BINDSTRATEGY_RANDOM or TIBDG_CONNECTION_BINDSTRATEGY_BALANCED No effect for other bind strategies After receiving this many responses, the client will stop looking for additional responses
      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_BOOLEAN_IMMUTABLE_ROWS

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_BOOLEAN_IMMUTABLE_ROWS

      Property to specify immutability of rows returned from ResultSet/Get APIs.

      Supply this property to `DataGrid.connect`. If true, rows returned cannot be modified. If unspecified, the default value is false.

      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_LONG_TRANSPORT_TYPE

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_LONG_TRANSPORT_TYPE

      Property to indicate the type of transport the client will use to connect to proxies

      Supply this property to `DataGrid.connect`. The type of transport used by the client when this property is not provided is determined by the grid configuration. TIBDG_CONNECTION_TRANSPORT_TYPE_DTCP will enable the client to connect to proxy processes via DTCP TIBDG_CONNECTION_TRANSPORT_TYPE_AUTO will enable the client to connect to proxies via an Auto Transport

      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_TRANSPORT_TYPE_DTCP

          static final long TIBDG_CONNECTION_TRANSPORT_TYPE_DTCP

      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_TRANSPORT_TYPE_AUTO

          static final long TIBDG_CONNECTION_TRANSPORT_TYPE_AUTO

      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_DOUBLE_TIMEOUT

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_DOUBLE_TIMEOUT

      Property name for connection timeout; double.

      When connecting to a data grid, supply this property to `DataGrid.connect` Its value determines how long all calls, other than DataGrid.connect, block waiting for the data grid to respond. Default is 5.0 seconds.

      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_STRING_USERNAME

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_STRING_USERNAME

      Property name for realm server username; string.

      Supply this property to `DataGrid.connect` if using a secure realm server.

      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_STRING_USERPASSWORD

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_STRING_USERPASSWORD

      Property name for realm server password; string. Supply this property to `DataGrid.connect` if using a secure realm server.
      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_STRING_SECONDARY_REALM

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_STRING_SECONDARY_REALM

      Property name for specifying secondary/backup realm server; string. Supply this property to `DataGrid.connect` if using a secondary/backup realm server
      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_HTTPS_CONNECTION_TRUST_EVERYONE

          static final java.lang.String TIBDG_CONNECTION_HTTPS_CONNECTION_TRUST_EVERYONE

      Property name to Trust any realm server; property value constant. This constant is one possible value of the property `Connection.TIBDG_CONNECTION_PROPERTY_STRING_TRUST_TYPE` in the method `DataGrid.connect`. The client trusts any realm server without verifying trust in the server's certificate. Do not use this value except for convenience in development and testing. It is not secure.
      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE

          static final java.lang.String TIBDG_CONNECTION_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE

      Trust a realm server if its certificate is in a trust file; property value constant. This constant is one possible value of the property `Connection.TIBDG_CONNECTION_PROPERTY_STRING_TRUST_TYPE` in the method `DataGrid.connect`. The client trusts the realm server based on the trust file created by the realm server and distributed by the administrator. Specify the file path of the trust file in the property `Connection.TIBDG_CONNECTION_PROPERTY_STRING_TRUST_FILE`
      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_STRING_TRUST_TYPE

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_STRING_TRUST_TYPE

      Property name for secure realm server trust type; long. When connecting to a secure realm server, supply this property to `DataGrid.connect`. Its value determines trust in the realm server's certificate. `Connection.TIBDG_CONNECTION_HTTPS_CONNECTION_TRUST_EVERYONE` `Connection.TIBDG_CONNECTION_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE`
      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_STRING_TRUST_FILE

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_STRING_TRUST_FILE

      Property name for secure realm server trust file; string. When connecting to a secure realm server, supply this property to `DataGrid.connect`. If the grid connect call specifies the trust type as `Connection.TIBDG_CONNECTION_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_FILE` use this property to indicate the location of the trust file.
      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_STRING_GRIDNAME

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_STRING_GRIDNAME

      Property name for data grid name; string. Supply this property as part of your JDBC URL as follows: jdbc:tibco:datagrid;com.tibco.tibdg.gridname="<data grid name>"
      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_STRING_REALMURL

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_STRING_REALMURL

      Property name for realm server url; string. Supply this property as part of your JDBC URL as follows: jdbc:tibco:datagrid:<data grid name>;com.tibco.tibdg.realmurl="<realm server url>"
      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_STRING_CLIENT_LABEL

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_STRING_CLIENT_LABEL

      Property name for client label; string. It is good practice to include this property in `DataGrid.connect` calls of every application program. Administrators can use client labels in monitoring and management to recognize and distinguish among processes.
      See Also:
        Constant Field Values

    - #### TIBDG_CONNECTION_PROPERTY_LONG_OWNER_ID

          static final java.lang.String TIBDG_CONNECTION_PROPERTY_LONG_OWNER_ID

      Property to specify owner ID of this connection; long. Specifies the owner ID of this connection for use with single owner tables. Must be a 64-bit non-zero integer value.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### createSession

          Session createSession(java.util.Properties props)
                         throws DataGridException

      Create a session object to perform operations.

      A session object provides the context for a thread of operations involving grid resources.

      The session object is NOT thread-safe. Do not invoke multiple operations on a single session using more than one thread. Behavior is not defined if this happens.

      Parameters:
        `props` - Optional, null to omit
        - `Session.TIBDG_SESSION_PROPERTY_BOOLEAN_TRANSACTED`
      Returns:
        On success, this call returns a new session object.
      Throws:
        `DataGridException` - in case of failures

    - #### getGridMetadata

          GridMetadata getGridMetadata(java.util.Properties props)
                                throws DataGridException

      Retrieve the current data grid metadata in an object.

      A grid metadata object contains information about the data grid including name, version, and additional metadata about tables.

      The information in a grid metadata object will be current when the request returns and will not be updated after that point.

      A grid metadata object must be closed to release internal state and no further access should be made to the grid metadata object or any nested objects after it has been closed.

      Parameters:
        `props` - Optional, null to omit
      Returns:
        On success, this call returns a new grid metadata object.
      Throws:
        `DataGridException` - in case of failures

    - #### getGridMetadata

          GridMetadata getGridMetadata()
                                throws DataGridException

      Retrieve the current data grid metadata in an object.

      A grid metadata object contains information about the data grid including name, version, and additional metadata about tables.

      The information in a grid metadata object will be current when the request returns and will not be updated after that point.

      A grid metadata object must be closed to release internal state and no further access should be made to the grid metadata object or any nested objects after it has been closed.

      Returns:
        On success, this call returns a new grid metadata object.
      Throws:
        `DataGridException` - in case of failures

    - #### close

          void close()
              throws DataGridException

      Close a connection object.

      Releases all resources associated with this connection object.

      Note that all resources created or opened by this object are invalidated by this call. These resources should be destroyed or closed before closing this connection.

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

    - #### interrupt

          void interrupt()
                  throws DataGridException

      Interrupts all outstanding requests on the connection forcing them to return an interrupted exception (`InterruptedException`).
      Throws:
        `DataGridException` - in case of failures