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 data source can be retrieved by calling JCM.getCacheByName(String).
dropConnection(Connection) – Drops a connection. The connection is closed and not released into the data source.
getPoolSizeMax() – Retrieves the maximum number of connections that this data source can manage.
getConlibName() – Returns the connectivity library (or interface) name for the data source.
getConnection(int) – Obtains a connection handle from the data source.
getProxyConnection(int, String) – Obtains a connection handle from the data source, specifying an alternate login name to set-proxy to.
getName() – Retrieves the data source’s name.
getPassword() – Retrieves the password used by connections in the data source.
getRemoteServerName() – Returns the remote server name used by connections in the data source.
getUsername() – Retrieves the user name used by connections in the data source.
releaseConnection(Connection) – Releases a connection to the data source for reuse.
Determines whether the cache can be retrieved by calling JCM.getCacheByName(String).
Beginning in EAServer 6.0, all data sources allow access
by name. This method is provided for backward compatibility.
Package |
|
Class |
public boolean byNameAllowed()
true if the data source
can be retrieved with JCM.getCacheByName(String), false otherwise.
getName(), JCM.byNameAllowed(String), JCM.getCacheByName(String)
See Chapter 4, “Database Access,” in the EAServer System Administration Guide
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 data source. 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 data source.
Package |
|
Class |
public String getConlibName()
“JDBC”
Obtains a connection handle from the data source.
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 data source). 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 data source’s maximum size is ignored. |
A java.sql.Connection instance from the data source. 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 data source. data sources are maintained statically; a data source 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 data source has a maximum number of connections determined by the data source properties. (See Chapter 4, “Database Access,” in the EAServer System Administration Guide for more information.) The flag parameter determines getConnection(int) behavior when the data source’s maximum number of connections are in use. getPoolSizeMax() returns the data source’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 data source’s connections.
dropConnection(Connection), getPoolSizeMax(), releaseConnection(Connection)
Retrieves the maximum number of connections that can be pooled in the data source.
Package |
|
Class |
public int getPoolSizeMax()
The data source size.
The size is specified the data source properties. 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 data source.
Package |
|
Class |
public int getPoolSizeMax()
The data source size.
The size is specified the data source properties. See Chapter 4, “Database Access,” in the EAServer System Administration Guide for more information.
Obtains a connection handle from the data source, specifying an alternate login name to set-proxy to.
Not all data sources support set-proxy
Set-proxy support must be enabled in the data source properties
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 data source). 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 data source’s maximum size is ignored. |
The user name to set-proxy to.
A java.sql.Connection instance from the data source. 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 in the data source properties. If support is enabled, connections retrieved from the data source 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 data sources 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 data source’s connections.
dropConnection(Connection), getPoolSizeMax(), getConnection(int), releaseConnection(Connection)
Retrieves the data source’s name.
Package |
|
Class |
public String getName()
The data source’s name.
Retrieves the password used by connections in the data source.
Package |
|
Class |
public String getPassword()
The password.
getRemoteServerName(), getUsername()
Retrieves the remote server name used by connections in the data source.
Package |
|
Class |
public String getRemoteServerName()
The remote server name.
Retrieves the user name used by connections in the data source.
Package |
|
Class |
public String getUserName()
The user name.
getPassword(), getRemoteServerName()
Releases a connection to the data source 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 data source) if the data source 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 data source. 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 data source. Do not release a connection more than once.
