com.sybase.jdbcx
Interface SybConnection


public abstract interface SybConnection
extends Connection

Defines the java.sql.Connection interface for the Sybase JDBC driver. Connection objects obtained from jConnect can be cast to this class to access Sybase-specific methods.

See Also:
Statement, ResultSet, DatabaseMetaData, java.sql.DriverManager#getConnection, com.sybase.jdbc4.jdbc.SybDriver#connect

Method Summary
 void cancel()
          Cancels all pending results on this connection.
 SybCallableStatement copyCallableStatement(SybCallableStatement callStmt)
          Create a light-weight copy of a CallableStatement that may have been created on a different Connection.
 SybPreparedStatement copyPreparedStatement(SybPreparedStatement prepStmt)
          Create a light-weight copy of a PreparedStatement that may have been created on a different Connection.
 Capture createCapture()
           
 String getSessionID()
          Returns the session ID associated with this connection, or null if there is no ID.
 SybMessageHandler getSybMessageHandler()
          Returns the current message handler object for this connection.
 PreparedStatement prepareStatement(String sql, boolean dynamic)
          Creates a prepared statement, overriding the DYNAMIC_PREPARE connection property.
 void regNoWatch(String eventName)
          Removes the application from the notification list of a registered procedure.
 void regWatch(String eventName, SybEventHandler eventHdlr, int option)
          Adds the application to the notification list of a registered procedure.
 void setSybMessageHandler(SybMessageHandler msgHandler)
          Sets the message handler for this connection.
 
Methods inherited from interface java.sql.Connection
clearWarnings, close, commit, createStatement, createStatement, getAutoCommit, getCatalog, getMetaData, getTransactionIsolation, getTypeMap, getWarnings, isClosed, isReadOnly, nativeSQL, prepareCall, prepareCall, prepareStatement, prepareStatement, rollback, setAutoCommit, setCatalog, setReadOnly, setTransactionIsolation, setTypeMap
 

Method Detail

cancel

public void cancel()
            throws SQLException
Cancels all pending results on this connection. This is a Sybase extension and not a standard JDBC method.
Throws:
SQLException - if the cancel command cannot be sent or the cancel is not acknowledged by the server

createCapture

public Capture createCapture()
                      throws SQLException
Returns:
the Capture object which can be used to enable and disable protocol tracing

getSessionID

public String getSessionID()
                              throws SQLException
Returns the session ID associated with this connection, or null if there is no ID. This is a Sybase, jConnect-specific extension.
Returns:
the session ID associated with this connection

prepareStatement

public PreparedStatement prepareStatement(String sql,
                         boolean dynamic)
                                            throws SQLException
Creates a prepared statement, overriding the DYNAMIC_PREPARE connection property.
Parameters:
sql - string giving the query to prepare
dynamic - if true, compile the query in advance for greater efficiency of repeated execution

regNoWatch

public void regNoWatch(String eventName)
                throws SQLException
Removes the application from the notification list of a registered procedure.
Parameters:
eventName - the name of the registered procedure for which the application no longer wants notification
Throws:
SQLException - if eventName is not a registered procedure or the server is unable to remove the client from the notification list

regWatch

public void regWatch(String eventName,
                     SybEventHandler eventHdlr,
                     int option)
              throws SQLException
Adds the application to the notification list of a registered procedure.
Parameters:
eventName - the name of the registered procedure for which the application wants notification
eventHdlr - the class that will handle the notification event
option - an int specifying whether the application should be removed from the notification list after a single notification (SybEventHandler.NOTIFY_ONCE) or be called every time the procedure executes (SybEventHandler.NOTIFY_ALWAYS)
Throws:
SQLException - if eventName is not a registered procedure or the server is unable to add the client to the notification list

setSybMessageHandler

public void setSybMessageHandler(SybMessageHandler msgHandler)
Sets the message handler for this connection.
Parameters:
msgHandler - message handler to be called when an error occurs or null to turn off error callbacks

getSybMessageHandler

public SybMessageHandler getSybMessageHandler()
Returns the current message handler object for this connection.
Returns:
the message handler

copyPreparedStatement

public SybPreparedStatement copyPreparedStatement(SybPreparedStatement prepStmt)
                                           throws SQLException
Create a light-weight copy of a PreparedStatement that may have been created on a different Connection. The usefulness of this method is for applications that might be implementing some kind of cache of m PreparedStatements that are to be shared among n Connections. Instead of having to keep m PreparedStatements for each of the n connections (leading to m * n PreparedStatements in memory), the cache can keep m PreparedStatements as templates and then call this method on the Connection for which the application wants to execute it. Testing of this method has revealed that intelligent copying can lead to significant performance improvements due to reduced CPU and memory usage.
jConnect does some internal optimizations to implement this copy method, which lead to the following conditions that must be followed when using the copyPreparedStatement method:
NOTE:Failure to follow the above restrictions will lead to data corruption. Finally, it is allowable to use the copyPreparedStatement method when using PooledConnections.
Parameters:
prepStmt - the template SybPreparedStatement that you wish to copy and then execute on this Connection. This SybPreparedStatement may have been originally created on another Connection object.

copyCallableStatement

public SybCallableStatement copyCallableStatement(SybCallableStatement callStmt)
                                           throws SQLException
Create a light-weight copy of a CallableStatement that may have been created on a different Connection. The usefulness of this method is for applications that might be implementing some kind of cache of m CallableStatements that are to be shared among n Connections. Instead of having to keep m CallableStatements for each of the n connections (leading to m * n CallableStatements in memory), the cache can keep m CallableStatements as templates and then call this method on the Connection for which the application wants to execute it. Testing of this method has revealed that intelligent copying can lead to significant performance improvements due to reduced CPU and memory usage.
jConnect does some internal optimizations to implement this copy method, which lead to the following conditions that must be followed when using the copyCallableStatement method:
NOTE:Failure to follow the above restrictions will lead to data corruption. Finally, it is allowable to use the copyCallableStatement method when using PooledConnections.
Parameters:
callStmt - the template SybCallableStatement that you wish to copy and then execute on this Connection. This SybCallableStatement may have been originally created on another Connection object.