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.


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
 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 connection timeout (in milliseconds).
 long getMaxWaitTime()
          Returns the max. time to wait for a connection request when the pool is exhausted.
The default value is 30 seconds (30000 ms).
 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 timeout check period in (ms), i.e. the time after which all connections are being checked for timeouts periodically.
The default value is 60 seconds (60000 ms).
 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)
          Closes a connection and removes it from the pool
 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 new connection timeout (in milliseconds).
 void setMaxWaitTime(long max_wait_time)
          Sets the max. time to wait in a connection request when a pool is exhausted.
 void setTimeoutCheckPeriod(long timeout_check_period)
          Sets the timeout check period (in milliseconds), i.e. the time after which all connections are being checked for timeouts periodically.
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

getTimeoutCheckPeriod

public long getTimeoutCheckPeriod()
Returns the timeout check period in (ms), i.e. the time after which all connections are being checked for timeouts periodically.
The default value is 60 seconds (60000 ms).
Returns:
the time interval in milliseconds

setTimeoutCheckPeriod

public void setTimeoutCheckPeriod(long timeout_check_period)
Sets the timeout check period (in milliseconds), i.e. the time after which all connections are being checked for timeouts periodically. An interval of 0 disables checkings.
The default value is 60 seconds (60000 ms).
Parameters:
timeout_check_period - the new interval after which the connections will be checked for timeouts.

getConnectionTimeout

public long getConnectionTimeout()
Returns the connection timeout (in milliseconds). A connection is being regarded as timed out when there has been no activity on it for the specified time interval.
The default value is 10 minutes (600000 ms).
Returns:
the connection timeout in units of milliseconds

setConnectionTimeout

public void setConnectionTimeout(long connection_timeout)
Sets the new connection timeout (in milliseconds). A connection is being regarded as timed-out when there has been no activity on it for the specified time interval.
The default value is 10 minutes (600000 ms).
Parameters:
connection_timeout - the new value for the connection timeout in milliseconds

getMaxWaitTime

public final long getMaxWaitTime()
Returns the max. time to wait for a connection request when the pool is exhausted.
The default value is 30 seconds (30000 ms).
Returns:
Returns the max. time to wait for a connection

setMaxWaitTime

public final void setMaxWaitTime(long max_wait_time)
Sets the max. time to wait in a connection request when a pool is exhausted. This methods resets the max. wait time for all the pools which are currently under control of the PoolManager.
The default value is 30 seconds (30000 ms).
Parameters:
max_wait_time - the time to wait for a connection request

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

removeConnection

public void removeConnection(JCO.Connection connection)
Closes a connection and removes it from the pool
Parameters:
connection - the connection which will be removed from its pool