Chapter 28 Using Connection Management

Using Java Connection Manager classes

Java components can use the Java Connection Manager (JCM) classes to take advantage of connection caching. The JCM classes manage JDBC connections.

Classes

The JCM classes are:

com.sybase.jaguar.jcm.JCMCache, which represents a configured connection cache and provides methods to manage connections in the cache.
com.sybase.jaguar.jcm.JCM, which provides access to JDBC connection caches defined in Jaguar Manager. JCM is a factory for JCMCache instances.

These classes are documented in Chapter 1, "Java Classes and Interfaces" of the Jaguar CTS API Reference.

Java Connection Manager example

The example below implements a Java component that calls these JCM class methods:

JCM.getCache(String, String, String) - called in the constructor to obtain a cache reference.
JCMCache.getConnection(int) - called in the method passthru_query(String) to obtain a connection.
JCMCache.releaseConnection(Connection) - called by passthru_query(String) to release the connection before the method returns.

Many JDBC programs do not explicitly clean up java.sql.Statement objects. Instead, they rely on the JDBC driver to clean up Statement objects when the connection is closed. This strategy does not work with cached connections; you must explicitly clean up Statement objects before releasing a connection back into the cache. To clean up Statement objects, call Statement.close() and set the Statement reference to null.

WARNING!

To prevent memory leaks, you must explicitly clean up a connection's Statement objects before releasing the connection back into the cache. Do not release the same connection more than once.

The code also calls JContext.forwardResultSet(ResultSet) to forward result sets from a remote server to the client. Here is the code:

import com.sybase.jaguar.sql.*;
import com.sybase.jaguar.server.*;
import com.sybase.jaguar.jcm.*;
import com.sybase.jaguar.util.*;

import java.io.*;
import java.sql.*;
import java.util.*;

/**
 *  Java class to implement rs_passthru Jaguar component.
 */
class rs_passthruImpl {
  
  JCMCache _cache = null;
  private static final String _user = "dba";
  private static final String _password = "sql";
  private static final String _server_url = 
                       "jdbc:odbc:Jaguar SVU Sample";

  /**
   * Default constructor that is called by Jaguar when a
   * component instance is created.
   */
  public rs_passthruImpl() throws JException {

    // Get a JDBC connection cache handle.
    try {
      _cache = JCM.getCache(_user, _password, _server_url);
    } catch (Exception e) {
      Jaguar.writeLog(true, "rs_passthru(): getCache() exception"
                      + e.getMessage());
      _cache = null;
    }

    // If we can't get a cache handle here, log an error
    // message then throw an exception. The exception will 
    // cause Jaguar to return a failure to the stub.
    if (_cache == null) 
    {
      Jaguar.writeLog(true, 
        "rs_passthru(): Could not access connection cache.");
      Jaguar.writeLog(false, "rs_passthru(): Cache may not be configured properly in Jaguar Manager.");
      throw new JException(
        "rstest(): Could not create connection cache.");
    }
  } // rs_passthruImpl()

  /**
   * Forward the client's query to the remote server, forward
   * the results back to the client.
   */
  public void passthru_query (String query)
     throws JException, SQLException
  {
    Connection conn = null;
    Statement stmt = null;
    ResultSet rs = null;

    // Note that this code does not catch exceptions; 
    // if an exception is thrown will be caught by Jaguar 
    // and the method invocation will fail.

    // Call getConnection(int) to get a connection from 
    // the cache. We use the JCM_WAIT flag; since
    // getConnection(JCM_WAIT) can return null if 
    // it is interrupted, we call it in a loop.
    while (conn == null)
    {
      conn = _cache.getConnection(JCMCache.JCM_WAIT);
    }

    // Create a Statement instance and use it to 
    // forward the query.
    stmt = conn.createStatement();
    boolean results = stmt.execute(query);
    int update_count = -1;

    // Process all the results, forwarding each result set 
    // to the client.
    do {
      if (results)
      {
        rs = stmt.getResultSet();
        if (rs != null)
          JContext.forwardResultSet(rs);
      }
      else 
      {
        update_count = stmt.getUpdateCount();
      }
      results = stmt.getMoreResults();
    } while (results || (update_count != -1));

    //
    // Explicitly release the Statement object. 
    // Otherwise, it will linger attached to the cached
    // connection.
    //
    stmt.close()
    stmt = NULL;

    _cache.releaseConnection(conn);
  
  } // passthru_query (String)

} // class rs_passthruImpl

For more Java connection management examples, see the source for the Jaguar sample Java components in your installation directory.