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

This class encapsulates a connection pool. A pool is a set of client-connections to a certain destination. The pool may automatically create new connections to the specified remote system or return an already existing one. It also provides methods to return a connection back to the pool when it is no longer needed.
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 checks the connections as well as the time after which a connection will time-out can be configured by the calling application.

Field Summary

int	INFINITE The max of connections these can be created by the pool

Method Summary

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.
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.
java.lang.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.
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. This property only affects future connections that will be created by the pool.

Methods inherited from class java.lang.Object

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

Method Detail

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

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

java.lang.IllegalArgumentException - if timeout_check_period is negative.

See Also:

getTimeoutCheckPeriod()

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

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