Chapter 1 Java Classes and Interfaces
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).
JCM_FORCE
public final static int JCM_FORCE
A value for the getConnection flag parameter.
JCM_NOWAIT
public final static int JCM_NOWAIT
A value for the getConnection flag parameter.
JCM_WAIT
public final static int JCM_WAIT
A value for the getConnection flag parameter.
java.sql.Connection, "Using Java Connection Manager Classes" in the Jaguar CTS Programmer's Guide
Determine 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 "Manage Connection Caches" in the Jaguar CTS System Administration Guide for more information.
getName(), JCM.byNameAllowed(String), JCM.getCacheByName(String)
Drop a connection. The connection is closed and not released into the cache.
Package |
|
Class |
public void dropConnection( Connection con)
throws SQLException
con
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)
Retrieve the maximum number of connections that this cache can manage.
Package |
|
Class |
public int getCacheSize()
The cache size.
The size of a cache is specified on the cache's Jaguar Manager property sheet. See "Manage Connection Caches" in the Jaguar CTS System Administration Guide for more information.
Return the connectivity library (or interface) name for the cache.
Package |
|
Class |
public String getConlibName()
"JDBC"
Obtain a connection handle from the cache.
Package |
|
Class |
public Connection getConnection(int flag)
throws SQLException, JException,
JConnectionNotFoundException
flag
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 Jaguar Manager. (See "Manage Connection Caches" in the Jaguar CTS System Administration Guide for more information.) The flag parameter determines getConnection(int) behavior when the cache's maximum number of connections are in use. getCacheSize() 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), getCacheSize(), releaseConnection(Connection)
Obtain 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 Jaguar Manager
before you can use this feature. See the Jaguar CTS System
Administration Guide for more information. You must be
connected to a database server, such as Adaptive Server Enterprise
11.5, that supports the set session authorization command.
Package |
|
Class |
public Connection getProxyConnection(int flag, String proxy)
throws SQLException, JException,
JConnectionNotFoundException
flag
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. |
proxy
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 Jaguar Manager. If support is enabled, connections retrieved from the cache with getConnection(int) set-proxy to the Jaguar 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 the Jaguar CTS 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), getCacheSize(), getConnection(int), releaseConnection(Connection)
Retrieve the cache's name.
Package |
|
Class |
public String getName()
The cache's name.
You can change a cache's name using Jaguar Manager. See "Manage Connection Caches" in the Jaguar CTS System Administration Guide for more information.
Retrieve 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 Jaguar Manager property sheet. See "Manage Connection Caches" in the Jaguar CTS System Administration Guide for more information.
getRemoteServerName(), getUsername()
Retrieve 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 Jaguar Manager property sheet. See "Manage Connection Caches" in the Jaguar CTS System Administration Guide for more information.
Retrieve 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 Jaguar Manager property sheet. See "Manage Connection Caches" in the Jaguar CTS System Administration Guide for more information.
getPassword(), getRemoteServerName()
Release a connection to the cache for reuse.
Package |
|
Class |
public void releaseConnection( Connection con)
throws SQLException
con
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. | ||
getConnection(int), dropConnection(Connection)
| Copyright © 2000 Sybase, Inc. All rights reserved. |
| |