ConnectionConfiguration (SAS Query Services)

All Libraries

This Library

Package

Class

Use

Tree

Deprecated

Index

Grand Index

Help

Query

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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

com.sas.iquery.dataretrieval
Class ConnectionConfiguration

com.sas.iquery.dataretrieval.ConnectionConfiguration

public class ConnectionConfiguration

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

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.

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.

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.

See Also:: Constant Field Values

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

See Also:: Constant Field Values

Constructor Detail