SQLRConnection
Date: 2014-09-29

com.firstworks.sqlrelay

## Class SQLRConnection

- java.lang.Object
- - com.firstworks.sqlrelay.SQLRConnection

-     public class SQLRConnection
      extends java.lang.Object

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `long` | `connection` connection is used internally, it's just public to make the JNI wrapper work faster.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SQLRConnection(java.lang.String server, short port, java.lang.String socket, java.lang.String user, java.lang.String password, int retrytime, int tries)` Initiates a connection to "server" on "port" or to the unix "socket" on the local machine and authenticates with "user" and "password".

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `autoCommitOff()` Instructs the database to wait for the client to tell it when to commit.
    `boolean` | `autoCommitOn()` Instructs the database to perform a commit after every successful query.
    `boolean` | `begin()` Begins a transaction.
    `java.lang.String` | `bindFormat()` Returns a string representing the format of the bind variables used in the db.
    `java.lang.String` | `clientVersion()` Returns the version of the sqlrelay client software
    `boolean` | `commit()` Issues a commit.
    `java.lang.String` | `dbHostName()` Returns the host name of the database
    `java.lang.String` | `dbIpAddress()` Returns the ip address of the database
    `java.lang.String` | `dbVersion()` Returns the version of the database
    `void` | `debugOff()` Turns debugging off.
    `void` | `debugOn()` Causes verbose debugging information to be sent to standard output.
    `void` | `delete()` Disconnects and ends the session if it hasn't been ended already.
    `void` | `endSession()` Ends the session.
    `java.lang.String` | `errorMessage()` If an operation failed and generated an error, the error message is available here.
    `long` | `errorNumber()` If an operation failed and generated an error, the error number is available here.
    `java.lang.String` | `getClientInfo()` Returns the string that was set by setClientInfo().
    `short` | `getConnectionPort()` Returns the inet port that the connection is communicating over.
    `java.lang.String` | `getConnectionSocket()` Returns the unix socket that the connection is communicating over.
    `java.lang.String` | `getCurrentDatabase()` Returns the database/schema that is currently in use
    `boolean` | `getDebug()` Returns 0 if debugging is off and 1 if debugging is on.
    `long` | `getLastInsertId()` Returns the value of the autoincrement column for the last insert
    `java.lang.String` | `identify()` Returns the type of database: oracle8, postgresql, mysql, etc.
    `boolean` | `ping()` Returns 1 if the database is up and 0 if it's down.
    `boolean` | `resumeSession(short port, java.lang.String socket)` Resumes a session previously left open using suspendSession().
    `boolean` | `rollback()` Issues a rollback.
    `boolean` | `selectDatabase(java.lang.String database)` Sets the current database/schema to "database"
    `java.lang.String` | `serverVersion()` Returns the version of the sqlrelay server software
    `void` | `setAuthenticationTimeout(int timeoutsec, int timeoutusec)` Sets the authentication timeout in seconds and milliseconds.
    `boolean` | `setClientInfo(java.lang.String clientinfo)` Allows you to set a string that will be passed to the server and ultimately included in server-side logging along with queries that were run by this instance of the client.
    `void` | `setConnectTimeout(int timeoutsec, int timeoutusec)` Sets the server connect timeout in seconds and milliseconds.
    `boolean` | `setDebugFile(java.lang.String debugfile)` Allows you to specify a file to write debug to.
    `void` | `setResponseTimeout(int timeoutsec, int timeoutusec)` Sets the response timeout (for queries, commits, rollbacks, pings, etc.) in seconds and milliseconds.
    `boolean` | `suspendSession()` Disconnects this connection from the current session but leaves the session open so that another connection can connect to it using resumeSession().

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

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

- - ### Field Detail

    - #### connection

          public long connection

      connection is used internally, it's just public to make the JNI wrapper work faster.

  - ### Constructor Detail

    - #### SQLRConnection

          public SQLRConnection(java.lang.String server,
                                short port,
                                java.lang.String socket,
                                java.lang.String user,
                                java.lang.String password,
                                int retrytime,
                                int tries)

      Initiates a connection to "server" on "port" or to the unix "socket" on the local machine and authenticates with "user" and "password". Failed connections will be retried for "tries" times, waiting "retrytime" seconds between each try. If "tries" is 0 then retries will continue forever. If "retrytime" is 0 then retries will be attempted on a default interval. If the "socket" parameter is neither NULL nor "" then an attempt will be made to connect through it before attempting to connect to "server" on "port". If it is NULL or "" then no attempt will be made to connect through the socket.

  - ### Method Detail

    - #### delete

          public void delete()

      Disconnects and ends the session if it hasn't been ended already.

    - #### setConnectTimeout

          public void setConnectTimeout(int timeoutsec,
                                        int timeoutusec)

      Sets the server connect timeout in seconds and milliseconds. Setting either parameter to -1 disables the timeout. You can also set this timeout using the SQLR_CLIENT_CONNECT_TIMEOUT environment variable.

    - #### setAuthenticationTimeout

          public void setAuthenticationTimeout(int timeoutsec,
                                               int timeoutusec)

      Sets the authentication timeout in seconds and milliseconds. Setting either parameter to -1 disables the timeout. You can also set this timeout using the SQLR_CLIENT_AUTHENTICATION_TIMEOUT environment variable.

    - #### setResponseTimeout

          public void setResponseTimeout(int timeoutsec,
                                         int timeoutusec)

      Sets the response timeout (for queries, commits, rollbacks, pings, etc.) in seconds and milliseconds. Setting either parameter to -1 disables the timeout. You can also set this timeout using the SQLR_CLIENT_RESPONSE_TIMEOUT environment variable.

    - #### endSession

          public void endSession()

      Ends the session.

    - #### suspendSession

          public boolean suspendSession()

      Disconnects this connection from the current session but leaves the session open so that another connection can connect to it using resumeSession().

    - #### getConnectionPort

          public short getConnectionPort()

      Returns the inet port that the connection is communicating over. This parameter may be passed to another connection for use in the resumeSession() method. Note: the value returned by this method is only valid after a call to suspendSession().

    - #### getConnectionSocket

          public java.lang.String getConnectionSocket()

      Returns the unix socket that the connection is communicating over. This parameter may be passed to another connection for use in the resumeSession() method. Note: the value returned by this method is only valid after a call to suspendSession().

    - #### resumeSession

          public boolean resumeSession(short port,
                                       java.lang.String socket)

      Resumes a session previously left open using suspendSession(). Returns 1 on success and 0 on failure.

    - #### ping

          public boolean ping()

      Returns 1 if the database is up and 0 if it's down.

    - #### identify

          public java.lang.String identify()

      Returns the type of database: oracle8, postgresql, mysql, etc.

    - #### dbVersion

          public java.lang.String dbVersion()

      Returns the version of the database

    - #### dbHostName

          public java.lang.String dbHostName()

      Returns the host name of the database

    - #### dbIpAddress

          public java.lang.String dbIpAddress()

      Returns the ip address of the database

    - #### serverVersion

          public java.lang.String serverVersion()

      Returns the version of the sqlrelay server software

    - #### clientVersion

          public java.lang.String clientVersion()

      Returns the version of the sqlrelay client software

    - #### bindFormat

          public java.lang.String bindFormat()

      Returns a string representing the format of the bind variables used in the db.

    - #### selectDatabase

          public boolean selectDatabase(java.lang.String database)

      Sets the current database/schema to "database"

    - #### getCurrentDatabase

          public java.lang.String getCurrentDatabase()

      Returns the database/schema that is currently in use

    - #### getLastInsertId

          public long getLastInsertId()

      Returns the value of the autoincrement column for the last insert

    - #### autoCommitOn

          public boolean autoCommitOn()

      Instructs the database to perform a commit after every successful query.

    - #### autoCommitOff

          public boolean autoCommitOff()

      Instructs the database to wait for the client to tell it when to commit.

    - #### begin

          public boolean begin()

      Begins a transaction. Returns true if the begin succeeded, false if it failed. If the database automatically begins a new transaction when a commit or rollback is issued then this doesn't do anything unless SQL Relay is faking transaction blocks.

    - #### commit

          public boolean commit()

      Issues a commit. Returns true if the commit succeeded, false if it failed.

    - #### rollback

          public boolean rollback()

      Issues a rollback. Returns true if the rollback succeeded, false if it failed.

    - #### errorMessage

          public java.lang.String errorMessage()

      If an operation failed and generated an error, the error message is available here. If there is no error then this method returns NULL.

    - #### errorNumber

          public long errorNumber()

      If an operation failed and generated an error, the error number is available here. If there is no error then this method returns 0.

    - #### debugOn

          public void debugOn()

      Causes verbose debugging information to be sent to standard output. Another way to do this is to start a query with "-- debug\n". Yet another way is to set the environment variable SQLR_CLIENT_DEBUG to "ON"

    - #### debugOff

          public void debugOff()

      Turns debugging off.

    - #### getDebug

          public boolean getDebug()

      Returns 0 if debugging is off and 1 if debugging is on.

    - #### setDebugFile

          public boolean setDebugFile(java.lang.String debugfile)

      Allows you to specify a file to write debug to. Setting "filename" to NULL or an empty string causes debug to be written to standard output (the default).

    - #### setClientInfo

          public boolean setClientInfo(java.lang.String clientinfo)

      Allows you to set a string that will be passed to the server and ultimately included in server-side logging along with queries that were run by this instance of the client.

    - #### getClientInfo

          public java.lang.String getClientInfo()

      Returns the string that was set by setClientInfo().