*** This class is subject to change ***

com.sas.iquery.dataretrieval
Class ConnectionConfiguration

java.lang.Object
  |
  +--com.sas.iquery.dataretrieval.ConnectionConfiguration

public class ConnectionConfiguration

extends Object

Contains settings that are used to configure connection behaviour.

SAS Query Services currently supports two connection management strategies:

• ACQUIRE_RELEASE- Indicates that a new connection is acquired for each query and attached to the query result set.
• USER_SESSION- Indicates that one connection is shared by all queries performed by a single user.

A more detailed description follows:

• When executing a query using ACQUIRE_RELEASE(by passing a DataSelectionto the QueryConnector), a new server connection will always be made. This connection will be associated with the specific result set returned from the query connector, and it must be closed along with the result set by calling ResultSetInterface.close().
  Since each query must establish a new connection to the server, using the USER_SESSION strategy may limit application scalability.

  In order to ensure that resources are always correctly closed, the following try-finally usage pattern is recommended:

   
   //create a new retrieval policy:
   RetrievalPolicy retrievalPolicy = new RetrievalPolicy();
   
   //configure to acquire new connections always:
   retrievalPolicy.getConnectionConfiguration().setConnectionLifetime(
   	ConnectionConfiguration.ACQUIRE_RELEASE);
   
   //create a QueryConnector for executing queries:
   QueryConnector queryConnector = new QueryConnector();
   
   //set the query connector's default retrieval policy:
   queryConnector.setRetrievalPolicy(retrievalPolicy);
   
   //build a query:
   BusinessQuery query1 = buildRelationalBusinessQuery();
   
   ResultSetInterface result = null;
   try {
   
   	//execute the query using the default retrieval policy:
   	Map results = queryConnector.retrieveQueryResultMap(Collections.singletonList(query1));
   
   	//fetch the result of query1:
   	result = (ResultSetInterface) results.get(query1.getID());
   
   	useResult(result);
   
   } finally {
   	if (result != null) {
   		result.close();
   	}
   }
   

• When using USER_SESSION, a single connection for each server is re-used by all queries executed by a single user.
  These connections are not closed until the application explicitly calls QueryConnector.closeResources(SessionContextInterface, int) with the appropriate parameters.
  In order to improve scalability, connections should not remain open longer than absolutely necessary as each open connection consumes server resources. This is particularly important in a connection-pooled environment configured with a limited number of concurrent connections.
  A reasonable connection lifetime might be the time used to populate a single page with multiple query results. After the entire page is completed, the application would close the connection.
  In general, it is bad practice to retain open connections during user think time unless some special situation demands it.

  An example of this use would be

   RetrievalPolicy connectionRecyclingPolicy = new RetrievalPolicy();
   //make the policy re-use connections: 
   connectionRecyclingPolicy.getConnectionConfiguration().setConnectionLifetime(
   	ConnectionConfiguration.USER_SESSION);
   
   //execute the query again, using the new retrieval policy
   //(overriding the default for this call only):
   Map moreResults = queryConnector.retrieveQueryResultMap(Collections.singletonList(query1),
   	connectionRecyclingPolicy);
   
   //use the result here...
   
   //close the result sets just retrieved and the server connection:
   int closeConnectionAndResultSet = QueryConnector.CloseOptions.ALL_RESULTSET_OPTIONS
   	| QueryConnector.CloseOptions.ALL_CONNECTION_OPTIONS;
   
   queryConnector.closeResources(getSessionContext(), closeConnectionAndResultSet);
   

See Also:

RetrievalPolicy, QueryConnectorInterface, QueryConnector

Inner Class Summary

Field Summary

static int	ACQUIRE_RELEASE Specify this value to indicate that a new connection should be acquired for each query.
static int	USER_SESSION Specify this value to indicate that a connection should be re-used until it is explicitly released by calling QueryConnector.closeResources(SessionContextInterface, int).

Constructor Summary

ConnectionConfiguration()
Creates a new connection configuration with default settings.

ConnectionConfiguration(ConnectionConfiguration connectionConfiguration)
Copy constructor.

Method Summary

int	getConnectionLifetime() Returns the setting for connection lifetime management.
long	getMaxConnectionWaitTime() Returns the maximum time to wait for a connection.
void	setConnectionLifetime(int connectionLifetime) Specifies the connection management strategy.
void	setMaxConnectionWaitTime(long maxConnectionWaitTime) Sets how long to wait for a connection when executing a query.

Methods inherited from class java.lang.Object

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

Field Detail

ACQUIRE_RELEASE

public static final int ACQUIRE_RELEASE

Specify this value to indicate that a new connection should be acquired for each query. The connections are freed when the retrieved result set is closed.

USER_SESSION

public static final int USER_SESSION

Specify this value to indicate that a connection should be re-used until it is explicitly released by calling QueryConnector.closeResources(SessionContextInterface, int).

Constructor Detail

ConnectionConfiguration

public ConnectionConfiguration()

Creates a new connection configuration with default settings. The default settings are:

• USER_SESSION connection lifetime
• A connection wait time of 0 (wait for a connection indefinitely)
• DEFAULT result set caching behaviour

ConnectionConfiguration

public ConnectionConfiguration(ConnectionConfiguration connectionConfiguration)

Copy constructor. Creates a new connection configuration which has the same settings as the argument.

Method Detail

getConnectionLifetime

public int getConnectionLifetime()

Returns the setting for connection lifetime management.

Returns:

The current connection lifetime management setting (one of either ACQUIRE_RELEASE or USER_SESSION)

setConnectionLifetime

public void setConnectionLifetime(int connectionLifetime)

Specifies the connection management strategy. Possible values are:

• ACQUIRE_RELEASE
• USER_SESSION

Parameters:

connectionLifetime - The scope of connections

Throws:

IllegalArgumentException - If the given lifetime is not one of those listed above.

getMaxConnectionWaitTime

public long getMaxConnectionWaitTime()

Returns the maximum time to wait for a connection.
See setMaxConnectionWaitTime(long) for a description of the values returned by this method.

Returns:

the maximum time to wait for a connection, in milliseconds.

See Also:

setMaxConnectionWaitTime(long), com.sas.services.connection.platform.PlatformConnectionFactoryConfiguration

setMaxConnectionWaitTime

public void setMaxConnectionWaitTime(long maxConnectionWaitTime)

Sets how long to wait for a connection when executing a query.
The value indicates how the query execution should behave if all connections are currently allocated. The possible values and their meanings are:

• <0 throw an exception immediately
• 0 wait until another user returns a connection to the factory's pool
• >0 wait up to maxConnectionWaitTime milliseconds for another user to return a connection to the factory's pool and throw an exception if a connection is not returned in the allotted time

Parameters:

maxConnectionWaitTime - a timeout value as described above

See Also:

com.sas.services.connection.platform.PlatformConnectionFactoryConfiguration

*** This class is subject to change ***