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 java.lang.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.

Method Summary

void	addPool(java.lang.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.
JCO.Client	getClient(java.lang.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.
JCO.Client	getClient(java.lang.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(java.lang.String pool_name) Returns the pool with the specified name or null if such a pool does not exist in the pool list
java.lang.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.
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.
void	removeConnection(JCO.Connection connection) Deprecated. This method will be removed in the next release. Use JCO.releaseClient(connection) instead
void	removePool(java.lang.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

Methods inherited from class java.lang.Object

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

Method Detail

singleton

public static JCO.PoolManager singleton()

Returns the instance of the pool manager

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

addPool

public void addPool(java.lang.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 java.lang.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(java.lang.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(java.lang.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(java.lang.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.

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.

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(java.lang.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.

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.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:

java.lang.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

max_wait_time - the time to wait for a connection request

See Also:

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