package com.sybase.jaguar.jcm; public class JCMCache extends Object
Manages a pool of connections to a third-tier database server.
None. Call JCM.getCache(String, String, String).
public final static int JCM_FORCE
A value for the getConnection flag parameter.
public final static int JCM_NOWAIT
A value for the getConnection flag parameter.
public final static int JCM_WAIT
A value for the getConnection flag parameter.
byNameAllowed() – Determines whether the cache can be retrieved by calling JCM.getCacheByName(String).
dropConnection(Connection) – Drops a connection. The connection is closed and not released into the cache.
getPoolSizeMax() – Retrieves the maximum number of connections that this cache can manage.
getConlibName() – Returns the connectivity library (or interface) name for the cache.
getConnection(int) – Obtains a connection handle from the cache.
getProxyConnection(int, String) – Obtains a connection handle from the cache, specifying an alternate login name to set-proxy to.
getName() – Retrieves the cache’s name.
getPassword() – Retrieves the password used by connections in the cache.
getRemoteServerName() – Returns the remote server name used by connections in the cache.
getUsername() – Retrieves the user name used by connections in the cache.
releaseConnection(Connection) – Releases a connection to the cache for reuse.
java.sql.Connection, “Using Java Connection Manager classes” in the EAServer Programmer’s Guide
Determines whether the cache can be retrieved by calling JCM.getCacheByName(String).
Package |
|
Class |
public boolean byNameAllowed()
true if the cache can
be retrieved with JCM.getCacheByName(String), false otherwise.
The “Enable cache-by-name access” option in the Connection Cache Properties dialog determines whether components can retrieve the cache by calling JCM.getCacheByName(String). See Chapter 4, “Database Access,” in the EAServer System Administration Guide for more information.
getName(), JCM.byNameAllowed(String), JCM.getCacheByName(String)
Drops a connection. The connection is closed and not released into the cache.
Package |
|
Class |
public void dropConnection( Connection con) throws SQLException
The java.sql.Connection instance to be dropped.
Use dropConnection() to close a connection when you do not want the connection returned to the cache. If necessary, future getConnection(int) calls will allocate new connections to replace any that have been dropped.
getConnection(int), releaseConnection(Connection)
Returns the connectivity library (or interface) name for the cache.
Package |
|
Class |
public String getConlibName()
“JDBC”
Obtains a connection handle from the cache.
Package |
|
Class |
public Connection getConnection(int flag) throws SQLException, JException, JConnectionNotFoundException
A symbolic value that specifies what should happen if the maximum number of connections have been allocated and are in use (that is, no connection is available in the cache). Allowable values are:
Value |
Behavior when no connection is available |
|---|---|
JCM_NOWAIT |
Throws JConnectionNotFoundException. |
JCM_WAIT |
Does not return until a cached connection is available. |
JCM_FORCE |
“Forces” open a new, uncached connection. The cache’s maximum size is ignored. |
A java.sql.Connection instance from the connection cache. If the call specifies JCM_NOWAIT and no connections are available, the call throws a JConnectionNotFoundException instance.
getConnection(int) attempts to return a connection from the cache. Caches are maintained statically; a cache is initially empty when the server starts. Subsequent getConnection(int) calls allocate connections when necessary. releaseConnection(Connection) calls release control of a connection for later reuse.
Each cache has a maximum number of connections determined by the cache’s definition in EAServer Manager. (See Chapter 4, “Database Access,” in the EAServer System Administration Guide for more information.) The flag parameter determines getConnection(int) behavior when the cache’s maximum number of connections are in use. getPoolSizeMax() returns the cache’s maximum number of connections.
For improved performance, connections should not be held any longer than necessary. As a general rule, methods that use a cached connection should release it with releaseConnection(Connection) before returning. This strategy minimizes contention by multiple components for a cache’s connections.
dropConnection(Connection), getPoolSizeMax(), releaseConnection(Connection)
Retrieves the maximum number of connections that can be pooled in the cache.
Package |
|
Class |
public int getPoolSizeMax()
The cache size.
The size of a cache is specified the Connection Cache Properties in EAServer Manager. See Chapter 4, “Database Access,” in the EAServer System Administration Guide for more information.
Retrieves the maximum number of connections that can be pooled in the cache.
Package |
|
Class |
public int getPoolSizeMax()
The cache size.
The size of a cache is specified the Connection Cache Properties in EAServer Manager. See Chapter 4, “Database Access,” in the EAServer System Administration Guide for more information.
Obtains a connection handle from the cache, specifying an alternate login name to set-proxy to.
Not all connection caches support set-proxy
Set-proxy support must be enabled for caches in EAServer Manager
before you can use this feature. See Chapter
4, “Database Access,” in the EAServer System
Administration Guide for more information. You must be
connected to a database server, such as Adaptive Server Enterprise
11.5 or later, that supports the set session authorization command.
Package |
|
Class |
public Connection getProxyConnection(int flag, String proxy) throws SQLException, JException, JConnectionNotFoundException
A symbolic value that specifies what should happen if the maximum number of connections have been allocated and are in use (that is, no connection is available in the cache). Allowable values are:
Value |
Behavior when no connection is available |
|---|---|
JCM_NOWAIT |
Throws JConnectionNotFoundException. |
JCM_WAIT |
Does not return until a cached connection is available. |
JCM_FORCE |
“Forces” open a new, uncached connection. The cache’s maximum size is ignored. |
The user name to set-proxy to.
A java.sql.Connection instance from the connection cache. If the call specifies JCM_NOWAIT and no connections are available, the call throws a JConnectionNotFoundException instance.
This method retrieves a cached connection, specifying an alternate login name to set-proxy to. Set-proxy support must be enabled for a cache in EAServer Manager. If support is enabled, connections retrieved from the cache with getConnection(int) set-proxy to the client user name. Call getProxyConnection(int, String) to specify a different user name to set-proxy to.
Other than the set-proxy behavior, getProxyConnection(int, String) is identical to getConnection(int).
See Chapter 4, “Database Access,” in the EAServer System Administration Guide for information on defining caches and enabling set-proxy support.
For improved performance, connections should not be held any longer than necessary. As a general rule, methods that use a cached connection should release it with releaseConnection(Connection) before returning. This strategy minimizes contention by multiple components for a cache’s connections.
dropConnection(Connection), getPoolSizeMax(), getConnection(int), releaseConnection(Connection)
Retrieves the cache’s name.
Package |
|
Class |
public String getName()
The cache’s name.
You can change a cache’s name using EAServer Manager. See Chapter 4, “Database Access,” in the EAServer System Administration Guide for more information.
Retrieves the password used by connections in the cache.
Package |
|
Class |
public String getPassword()
The password.
A cache’s password is specified on the cache’s EAServer Manager property sheet. See Chapter 4, “Database Access,” in the EAServer System Administration Guide for more information.
getRemoteServerName(), getUsername()
Retrieves the remote server name used by connections in the cache.
Package |
|
Class |
public String getRemoteServerName()
The remote server name.
A cache’s remote server name is specified on the cache’s EAServer Manager property sheet. See Chapter 4, “Database Access,” in the EAServer System Administration Guide for more information.
Retrieves the user name used by connections in the cache.
Package |
|
Class |
public String getUserName()
The user name.
A cache’s user name is specified on the cache’s EAServer Manager property sheet. See Chapter 4, “Database Access,” in the EAServer System Administration Guide for more information.
getPassword(), getRemoteServerName()
Releases a connection to the cache for reuse.
Package |
|
Class |
public void releaseConnection( Connection con) throws SQLException
The connection to release.
Released connections must be in a state that allows new queries to be issued.
The connection will be dropped (and not returned to the cache) if the cache has exceeded its maximum number of connections. The maximum number of connections can be exceeded if calls to getConnection(int) are issued with flag as JCM_FORCE. In this case, releaseConnection drops the excess connections.
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 a connection more than once.
