com.sap.mw.jco

Class JCO.Pool

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

Enclosing class:

JCO

public static class JCO.Pool

extends Object

This class encapsulates a connection pool. A pool is a set of client-connections to a certain destination with the same logon data. The pool creates automatically new connections to the specified remote system or returns an already existing one. The reusing of existing connections can increase the performance of your application by avoiding of logging on to the remote server. The pool class also provides methods to return a connection back to the pool when it is no longer needed.
It checks periodically which connections are not longer in use and can be closed in order to save valuable system resources. The time period after which the pool checks the connections as well as the time after which a connection will time-out can be configured by the application. Note: SAP recommends to use a connection pool with a technical user for application internal calls only. If authenticated user makes use of the application calling remote functions, it is recommended to use dedicated connections with the identity of the accessing user. This allows the backend to check for correct access permissions. Note:All pools created by an application are visible for all applications running in the same VM.

Field Summary

protected com.sap.mw.jco.util.LimitedList	available List of free connections in this pool
protected long	connection_timeout The time (ms) after which a connection will be regarded as timed out
protected int	current_used Number of allocated connections from this pool
int	INFINITE The max of connections these can be created by the pool
protected boolean	is_initialized Indicates whether the pool is initialized or not
protected JCO.PoolManager	manager Reference to the pool manager
protected JCO.Client	master The master connection for this pool
protected int	max_connections The max. number of connections these can be created by the pool
protected int	max_pool_size The max. number of opened connections holding by the pool
protected int	max_used The max. number of connections used so far
protected long	max_wait_time The max. time to wait for a getClient() request
protected String	name Name of this pool
protected long	next_timeout_check The time interval (ms) after which the connections will be checked for timeouts periodically
protected byte	r3_version The R/3 version of the partner (0, 2, 3 or 4)
protected boolean	reset_on_release Whether to reset the client connection on release
protected long	timeout_check_period The time interval (ms) after which the connections will be checked for timeouts periodically
protected com.sap.mw.jco.util.ObjectList	waiting_threads Queue that holds waiting threads

Constructor Summary

protected

JCO.Pool(JCO.PoolManager manager, String name, JCO.Client master, int max_pool_size) Creates a new pool.

Method Summary

protected void	checkForTimeout() Process the necessary operation on timeout
protected void	clear() Disconnects all available clients
void	detachFromPool(JCO.Client client) Detaches a client-connection from the pool.
boolean	getAbapDebug() Returns true if ABAP debugging is enabled for the connections of this pool, and false otherwise.
protected JCO.Client	getClient(boolean reset) Returns a client from the pool
long	getConnectionTimeout() Returns the connection timeout in milliseconds.
int	getCurrentPoolSize() Returns the number of connections that are created for this pool and are currently alive.
int	getMaxConnections() Returns the maximum number of connections that can be allocated from the pool.
int	getMaxPoolSize() Returns the maximum number of connections that will be pooled.
int	getMaxUsed() Returns the max. number of connections used simultaneously so far
long	getMaxWaitTime() Returns the maximum time to wait in a connection request for a free connection.
String	getName() Returns the pool's name
int	getNumUsed() Returns the number of connections in the pool which are currently reserved by the application due to calls to JCO.getClient().
int	getNumWaitingThreads() Returns the number of threads that are waiting for a connection.
JCO.PoolManager	getPoolManager() Returns the pool manager this pool is a member of
boolean	getResetOnRelease() Returns true if a connection is being cleaned up in JCO.releaseClient(), false otherwise.
byte[]	getStates() Deprecated. This method will be removed in the next release. Use getNumUsed(), getCurrentPoolSize() instead
long	getTimeoutCheckPeriod() Returns the timeout check period in milliseconds.
boolean	getTrace() Returns whether trace for this pool is enabled or not.
protected void	initPool() Initializes the pool
protected void	releaseClient(JCO.Client client) Returns the client connection to the pool
void	setAbapDebug(boolean debug) Enables/disables ABAP debug.
void	setConnectionTimeout(long connection_timeout) Sets the connection timeout in milliseconds.
void	setMaxConnections(int max_connections) Sets the maximum number of connections which can be allocated from the pool.
void	setMaxPoolSize(int max_pool_size) Sets the maximum number of connections which will be held open by the pool for possible future reuse after they have been released.
void	setMaxWaitTime(long max_wait_time) Sets the maximum time to wait in a connection request for a free connection.
void	setResetOnRelease(boolean reset_on_release) Enables/disables cleanup when the client is being returned to its pool.
void	setTimeoutCheckPeriod(long timeout_check_period) Sets the timeout check period in milliseconds.
void	setTrace(boolean trace) Enables/disables RFC tracing for the connections of the pool.

Methods inherited from class java.lang.Object

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

Field Detail

INFINITE

public final int INFINITE

The max of connections these can be created by the pool

See Also:

Constant Field Values

name

protected String name

Name of this pool

master

protected JCO.Client master

The master connection for this pool

max_pool_size

protected int max_pool_size

The max. number of opened connections holding by the pool

max_connections

protected int max_connections

The max. number of connections these can be created by the pool

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

next_timeout_check

protected long next_timeout_check

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

max_used

protected int max_used

The max. number of connections used so far

current_used

protected int current_used

Number of allocated connections from this pool

available

protected com.sap.mw.jco.util.LimitedList available

List of free connections in this pool

waiting_threads

protected com.sap.mw.jco.util.ObjectList waiting_threads

Queue that holds waiting threads

manager

protected JCO.PoolManager manager

Reference to the pool manager

is_initialized

protected boolean is_initialized

Indicates whether the pool is initialized or not

r3_version

protected byte r3_version

The R/3 version of the partner (0, 2, 3 or 4)

reset_on_release

protected boolean reset_on_release

Whether to reset the client connection on release

Constructor Detail

JCO.Pool

protected JCO.Pool(JCO.PoolManager manager,
                   String name,
                   JCO.Client master,
                   int max_pool_size)

Creates a new pool.

Parameters:

manager - the pool-manager this pool will be a member of

master - the connection that fully specifies the connection parameters to a remote server and which will be shared among all connections in this pool

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

Method Detail

initPool

protected void initPool()

Initializes the pool

Throws:

JCO.Exception - if the pool could not be initialized

setResetOnRelease

public final void setResetOnRelease(boolean reset_on_release)

Enables/disables cleanup when the client is being returned to its pool. The default is resetting the connection after each JCO.releaseClient().

Parameters:

reset_on_release - 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 systems below SAP 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) need reinitialized connections while others might not. This depends strongly on the function modules and their implementation in the mySAP system. In certain cases it might be worthwhile to switch the cleanup off for performance reasons. Use with care !

getResetOnRelease

public final boolean getResetOnRelease()

Returns true if a connection is being cleaned up in JCO.releaseClient(), false otherwise.

Returns:

true if a connection is being cleaned up, false otherwise.

setAbapDebug

public void setAbapDebug(boolean debug)

Enables/disables ABAP debug. This property only affects future connections that will be created by the pool. It should be set before the first usage of the pool. All connections that have already been opened and are held by the pool or the by application wont be affected. Use JCO.Client.setAbapDebug for activating the ABAP debugger on a particular connection.

Parameters:

debug - if true enables ABAP debugging, disables it otherwise

getAbapDebug

public final boolean getAbapDebug()

Returns true if ABAP debugging is enabled for the connections of this pool, and false otherwise.

Returns:

true if ABAP debugging is enabled, false otherwise

See Also:

setAbapDebug(boolean)

getTrace

public final boolean getTrace()

Returns whether trace for this pool is enabled or not.

Returns:

true if trace is enabled, false otherwise

setTrace

public final void setTrace(boolean trace)

Enables/disables RFC tracing for the connections of the pool.
This property only affects future connections that will be created by the pool. It should be set before the first usage of the pool. All connections that have already been opened and are held by the pool or the by application wont be affected. Use JCO.Client.setTrace for activating the RFC trace on a particular connection.

Parameters:

trace - if true enables the trace and disables it otherwise.

getName

public final String getName()

Returns the pool's name

Returns:

the name of the pool

getPoolManager

public final JCO.PoolManager getPoolManager()

Returns the pool manager this pool is a member of

Returns:

the pool manager

getMaxPoolSize

public final int getMaxPoolSize()

Returns the maximum number of connections that will be pooled. If
getMaxPoolSize() < getMaxConnections()
the superfluous connections will be closed immediately.

Returns:

the max. number of connections that will be held by this pool

See Also:

setMaxPoolSize(int), getMaxConnections()

setMaxPoolSize

public final void setMaxPoolSize(int max_pool_size)

Sets the maximum number of connections which will be held open by the pool for possible future reuse after they have been released. If this number is exceeded all further connections will be closed on release. Note: If max_pool_size is greater than getMaxConnections() the max count of allocable connections will be set to max_pool_size.

Throws:

IllegalArgumentException - if max_pool_size is less than zero.

See Also:

getMaxConnections()

getMaxConnections

public final int getMaxConnections()

Returns the maximum number of connections that can be allocated from the pool.

Returns:

the maximum number of connections that can be allocated from the pool

See Also:

setMaxConnections(int)

setMaxConnections

public final void setMaxConnections(int max_connections)

Sets the maximum number of connections which can be allocated from the pool. This allows you to create more connections as specified by the MaxPoolSize property, for example for temporary peak usage times. Note: If the new value for MaxConnections is less than the MaxPoolSize, the MaxPoolSize will be resized automatically.

Parameters:

max_connections - maximum numbert of connections

Throws:

JCO.Exception - if an error occurs during resizing of pool

See Also:

setMaxPoolSize(int)

getCurrentPoolSize

public final int getCurrentPoolSize()

Returns the number of connections that are created for this pool and are currently alive.
That is the number of the connections that have been allocated by the application with the getClient(pool_name) method plus the number of connections that are currently held by the pool (being the connections that have been previuosly released with the releaseClient(client) method).

Returns:

the current pool size

getMaxUsed

public final int getMaxUsed()

Returns the max. number of connections used simultaneously so far

Returns:

the max. number of connections used simultaneously so far

getNumUsed

public final int getNumUsed()

Returns the number of connections in the pool which are currently reserved by the application due to calls to JCO.getClient().

Returns:

the current number of reserved connections in the pool

getNumWaitingThreads

public final int getNumWaitingThreads()

Returns the number of threads that are waiting for a connection.

Returns:

the current number of threads waiting for a connection.

setMaxWaitTime

public final void setMaxWaitTime(long max_wait_time)

Sets the maximum time to wait in a connection request for a free connection. If the 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. The default value is 30 seconds.

Parameters:

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

getMaxWaitTime

public final long getMaxWaitTime()

Returns the maximum time to wait in a connection request for a free connection.

Returns:

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

getConnectionTimeout

public long getConnectionTimeout()

Returns the connection timeout in milliseconds. The timeout can be changed by calling JCO.Pool.setConnectionTimeout() for this pool instance or by calling JCO.PoolManager.setConnectionTimeout() for all pools that will be newly created afterwards.
The default value is 10 minutes (600000 ms).

Returns:

the connection timeout in milliseconds

See Also:

setMaxWaitTime(long), setConnectionTimeout(long), PoolManager#setConnectionTimeout(long)

setConnectionTimeout

public void setConnectionTimeout(long connection_timeout)

Sets the connection timeout in milliseconds. This property only affects connections that have been previously released to the pool and are held open by the pool for possible future reuse. It does not affect connections that have been requested from the pool and are currently under control of an user application. A pooled 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

See Also:

getConnectionTimeout()

getTimeoutCheckPeriod

public long getTimeoutCheckPeriod()

Returns the timeout check period in milliseconds. It 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.
The default value is 60 seconds (60000 ms).

Returns:

the timeout check period in milliseconds

setTimeoutCheckPeriod

public void setTimeoutCheckPeriod(long timeout_check_period)

Sets the timeout check period in milliseconds. It 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:

getTimeoutCheckPeriod()

clear

protected final void clear()

Disconnects all available clients

getStates

public final byte[] getStates()

Deprecated. This method will be removed in the next release.
Use getNumUsed(), getCurrentPoolSize() instead

This method is not supported. Use getNumUsed(), getCurrentPoolSize() to get information about allocated clients and the free client connections remained in the pool. Returns an empty array for backwards compatibility.

Returns:

empty byte array

See Also:

getNumUsed(), getCurrentPoolSize()

getClient

protected final JCO.Client getClient(boolean reset)

Returns a client from the pool

Parameters:

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 systems below SAP 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 or removed.

See Also:

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

releaseClient

protected final void releaseClient(JCO.Client client)

Returns the client connection to the pool

Parameters:

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

Throws:

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

See Also:

getClient(boolean), setResetOnRelease(boolean)

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

checkForTimeout

protected final void checkForTimeout()

Process the necessary operation on timeout