com.sap.mw.jco

Class JCO.PoolManager

java.lang.Object
  com.sap.mw.jco.JCO.PoolManager

Enclosing class:

JCO

public static class JCO.PoolManager

extends Object

This manager handles all pool objects. It checks periodically which connections are no longer in use and can be closed in order to save valuable system resources. The time period after which the pool manager checks the connections as well as the time after which a connection will time-out can be configured by the calling application for each pool independently.

Nested Class Summary

protected static class

JCO.PoolManager.TimeoutChecker Helper class

Field Summary

protected long	connection_timeout The time (ms) after which a released pooled connection will be regarded as timed out
protected long	max_wait_time The max. time to wait for a getClient() request
protected Hashtable	pools Hashtable which holds the pools
protected long	timeout_check_period The time interval (ms) after which the connections will be checked for timeouts periodically
protected JCO.PoolManager.TimeoutChecker	timeout_checker The thread that checks for connections that have timed out

Constructor Summary

protected

JCO.PoolManager() Create a new instance of a PoolManager.

Method Summary

void	addPool(String pool_name, JCO.Client master, int max_pool_size) Adds a new pool to the pools list
void	addPoolChangedListener(JCO.PoolChangedListener listener) Register a pool changed listener
void	detachFromPool(JCO.Client client) Detaches a client-connection from the pool.
protected void	firePoolChanged(JCO.Pool pool) Calls the poolChanged() method of the registered listeners
JCO.Client	getClient(String pool_name) Returns a new client connection from the specified pool.
JCO.Client	getClient(String pool_name, boolean reset) Returns a new client connection from the specified pool and resets all resources associated with this connection.
long	getConnectionTimeout() Returns the default value for the connection timeout in milliseconds.
long	getMaxWaitTime() Returns the maximum time to wait in a connection request for a free connection.
JCO.Pool	getPool(String pool_name) Returns the pool with the specified name or null if such a pool does not exist in the pool list
String[]	getPoolNames() Returns the array of pool names that are currently under control of the manager
long	getTimeoutCheckPeriod() Returns the default value for the timeout check period in milliseconds.
protected static void	registerPoolManager(JCO.PoolManager pool_manager) Registers the given object as PoolManager
void	releaseClient(JCO.Client client) Returns the client connection to the pool.
void	removeConnection(JCO.Connection connection) Deprecated. This method will be removed in the next release. Use JCO.releaseClient(connection) instead
void	removePool(String pool_name) Removes the named pool from the list of pools.
void	removePoolChangedListener(JCO.PoolChangedListener listener) Unregister a pool changed listener
void	setConnectionTimeout(long connection_timeout) Sets the default value for the connection timeout in milliseconds.
void	setMaxWaitTime(long max_wait_time) Sets the maximum time to wait in a connection request for a free connection.
void	setTimeoutCheckPeriod(long timeout_check_period) Sets the default value for the timeout check period in milliseconds.
static JCO.PoolManager	singleton() Returns the instance of the pool manager
protected void	startTimeoutChecker() Starts TimeoutChecker for all pool managed by this pool manager The derived class may overwrite this method

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

pools

protected Hashtable pools

Hashtable which holds the pools

timeout_checker

protected JCO.PoolManager.TimeoutChecker timeout_checker

The thread that checks for connections that have timed out

max_wait_time

protected long max_wait_time

The max. time to wait for a getClient() request

connection_timeout

protected long connection_timeout

The time (ms) after which a released pooled connection will be regarded as timed out

timeout_check_period

protected long timeout_check_period

The time interval (ms) after which the connections will be checked for timeouts periodically

Constructor Detail

JCO.PoolManager

protected JCO.PoolManager()

Create a new instance of a PoolManager.
The constructor starts automacally the TimeoutChecker. If the derived class doesn't need this, it has to overwrite startTimeoutChecker

See Also:

startTimeoutChecker()

Method Detail

startTimeoutChecker

protected void startTimeoutChecker()

Starts TimeoutChecker for all pool managed by this pool manager The derived class may overwrite this method

singleton

public static JCO.PoolManager singleton()

Returns the instance of the pool manager

registerPoolManager

protected static void registerPoolManager(JCO.PoolManager pool_manager)

Registers the given object as PoolManager

Throws:

JCO.Exception - with group

addPoolChangedListener

public void addPoolChangedListener(JCO.PoolChangedListener listener)

Register a pool changed listener

Parameters:

listener - the listener to add

removePoolChangedListener

public void removePoolChangedListener(JCO.PoolChangedListener listener)

Unregister a pool changed listener

Parameters:

listener - the listener to remove

firePoolChanged

protected void firePoolChanged(JCO.Pool pool)

Calls the poolChanged() method of the registered listeners

Parameters:

pool - the pool that has been modified

addPool

public void addPool(String pool_name,
                    JCO.Client master,
                    int max_pool_size)

Adds a new pool to the pools list

Parameters:

pool_name - the name of the new pool

master - the connection that specifies the parameters for all connections in this pool.

max_pool_size - the max. number of connections that can be opened simultaneously in this pool

Throws:

JCO.Exception - thrown if a pool with the same name already exists.

getPoolNames

public String[] getPoolNames()

Returns the array of pool names that are currently under control of the manager

Returns:

a string array of pool names

getPool

public JCO.Pool getPool(String pool_name)

Returns the pool with the specified name or null if such a pool does not exist in the pool list

Parameters:

pool_name - the name of the pool to return

removePool

public void removePool(String pool_name)

Removes the named pool from the list of pools. Note: The routine will close all open connections of the specified pool forcefully.

Parameters:

pool_name - the name of the pool to remove

getClient

public JCO.Client getClient(String pool_name)

Returns a new client connection from the specified pool.
Note: Any client obtained by this method must be released with JCO.releaseClient() if not needed anymore. If the pool is exhausted, that is, all clients of the pool are currently allocated by an application, the method will wait for a while and retry. The max. time the routine will wait can be specified by setMaxWaitTime(). If the second try to request a client from the pool also fails, the method will throw an exception.

Note: To avoid reconnect on connections to the SAP Systems below 4.0A it is necessary to set the resetOnRelease property to false and use JCO.getClient([pool name], false). Be careful, if you use this way, if have to be certain, that the application using this pool never invokes functions, that maintain a state on the ABAP server.

Parameters:

pool_name - the name of the pool from which to take the connection

Returns:

the newly created client or null in the case when the thread which was waiting for the client has been interrupted or client pool was removed.

Throws:

JCO.Exception - with the error group set to JCO.Exception.JCO_ERROR_RESOURCE, if a client could not be allocated, i.e. the client pool is exhausted

JCO.Exception - thrown if a client connection could not be established due to wrong logon data, network problems, etc.

See Also:

JCO.releaseClient(com.sap.mw.jco.JCO.Client), setMaxWaitTime(long)

getClient

public JCO.Client getClient(String pool_name,
                            boolean reset)

Returns a new client connection from the specified pool and resets all resources associated with this connection. If the pool is exhausted, that is, all clients of the pool are currently allocated by an application, the method will wait for a while and retry. The max. time the routine will wait can be specified by setMaxWaitTime(). If the second try to request a client from the pool also fails, the method will throw an exception.

Note: To avoid reconnect on connections to the SAP Systems below 4.0A it is necessary to set the resetOnRelease property to false and use JCO.getClient([pool name], false). Be careful, if you use this way, if have to be certain, that the application using this pool never invokes functions, that maintain a state on the ABAP server.

Parameters:

pool_name - the name of the pool from which to take the connection

reset - if true reset the connection, e.g. free all resources that might have been allocated on either the server side or by the local middleware layer. On SAP systems below 4.0A resetting a connection effectively means closing and subsequently reopening the connection which is a very expensive process. However, several scenarios (e.g. BAPIs) might need such reinitialized connections. Use with care !

Returns:

the newly created client or null in the case when the thread which was waiting for the client has been interrupted.

Throws:

JCO.Exception - with the error group set to JCO.Exception.JCO_ERROR_RESOURCE, if a client could not be allocated, i.e. the client pool is exhausted

JCO.Exception - thrown if a client connection could not be established due to wrong logon data, network problems, etc.

See Also:

JCO.releaseClient(com.sap.mw.jco.JCO.Client), setMaxWaitTime(long)

releaseClient

public void releaseClient(JCO.Client client)

Returns the client connection to the pool.
On SAP systems equal or above 4.0A the method resets the connection, i.e. frees all resources and context allocated on the server side (i.e. '/n' in SAP system) or by the local middleware layer unless specified differently by the pool's setResetOnRelease() method.

Parameters:

client - the client connection which is being returned to its pool

Throws:

JCO.Exception - thrown if a connection could not be released cleanly

See Also:

getClient(java.lang.String)

detachFromPool

public void detachFromPool(JCO.Client client)

Detaches a client-connection from the pool. The client wont be closed. This method converts a pooled client to a single client. Only pooled clients, those aren't released, can be detached from its pool.

Parameters:

client - the client connection which is being returned to its pool

Throws:

JCO.Exception - thrown if a connection could not be removed from pool cleanly

removeConnection

public void removeConnection(JCO.Connection connection)

Deprecated. This method will be removed in the next release.
Use JCO.releaseClient(connection) instead

Closes a connection and removes it from the pool

Parameters:

connection - the connection which will be removed from its pool

See Also:

JCO.releaseClient(com.sap.mw.jco.JCO.Client), releaseClient(com.sap.mw.jco.JCO.Client), JCO.Pool.releaseClient(com.sap.mw.jco.JCO.Client)

getTimeoutCheckPeriod

public long getTimeoutCheckPeriod()

Returns the default value for the timeout check period in milliseconds. This value will be used for new pools created by the pool manager.
The timeout check period specifies the periodical time interval after which all connections that have been released to a pool and are held open by the pool for possible future reuse are being checked for timeouts. Connections that have not been used for at least the connection timeout interval will be closed.
The default value is -1 and means that the timeout check period has not been specified by an application, so the default value of 60 seconds (60000 ms) will be used.

Returns:

the timeout check period in milliseconds

See Also:

JCO.Pool.getTimeoutCheckPeriod()

setTimeoutCheckPeriod

public void setTimeoutCheckPeriod(long timeout_check_period)

Sets the default value for the timeout check period in milliseconds. This value will be used for new pools created by the pool manager.
The timeout check period specifies the periodical time interval after which all connections that have been released to the pool and are held open by the pool for possible future reuse are being checked for timeouts. Connections that have not been used for at least the connection timeout interval will be closed.
A timeout check period of 0 disables the timeout checks.
The default value is 60 seconds (60000 ms).

Parameters:

timeout_check_period - the timeout check period in milliseconds.

Throws:

IllegalArgumentException - if timeout_check_period is negative.

See Also:

JCO.Pool.setTimeoutCheckPeriod(long)

getConnectionTimeout

public long getConnectionTimeout()

Returns the default value for the connection timeout in milliseconds. This value will be used for new pools created by the pool manager.
The default value is -1 and means that the connection timeout has not been specified by an application, so the default value of 10 minutes (600000 ms) will be used.

Returns:

the connection timeout in milliseconds

See Also:

JCO.Pool.getConnectionTimeout()

setConnectionTimeout

public void setConnectionTimeout(long connection_timeout)

Sets the default value for the connection timeout in milliseconds. This value will be used for new pools created by the pool manager.

Parameters:

connection_timeout - the new value for the connection timeout in milliseconds

See Also:

JCO.Pool.setConnectionTimeout(long), getConnectionTimeout()

getMaxWaitTime

public final long getMaxWaitTime()

Returns the maximum time to wait in a connection request for a free connection. This value will be used for new pools created by the pool manager.
The default value is -1 and means that the maximum time to wait has not been specified by an application, so the default value of 30 seconds (30000 ms) will be used.

Returns:

Returns the maximum time to wait for a free connection in milliseconds

See Also:

JCO.Pool.getMaxWaitTime()

setMaxWaitTime

public final void setMaxWaitTime(long max_wait_time)

Sets the maximum time to wait in a connection request for a free connection. This property will be used for new pools created by the pool manager.
If a pool is exhausted and after the specified time still no connection became available a JCO.Exception with the key JCO_ERROR_RESOURCE will be thrown.

Parameters:

max_wait_time - the maximum time to wait for a free connection in milliseconds

See Also:

getMaxWaitTime(), JCO.Pool.setMaxWaitTime(long)