# Poco::Data

# class SessionPool

Library: Data
Package: SessionPooling
Header: Poco/Data/SessionPool.h

## Description

This class implements session pooling for POCO Data.

Creating a connection to a database is often a time consuming operation. Therefore it makes sense to reuse a session object once it is no longer needed.

A SessionPool manages a collection of SessionImpl objects (decorated with a PooledSessionImpl).

When a SessionImpl object is requested, the SessionPool first looks in its set of already initialized SessionImpl for an available object. If one is found, it is returned to the client and marked as "in-use". If no SessionImpl is available, the SessionPool attempts to create a new one for the client. To avoid excessive creation of SessionImpl objects, a limit can be set on the maximum number of objects. Sessions found not to be connected to the database are purged from the pool whenever one of the following events occurs:

- JanitorTimer event
- get() request
- putBack() request

Not connected idle sessions can not exist.

Usage example:

    SessionPool pool("ODBC", "...");
    ...
    Session sess(pool.get());
    ...

## Inheritance

Direct Base Classes: Poco::RefCountedObject

All Base Classes: Poco::RefCountedObject

## Member Summary

Member Functions: allocated, applySettings, available, capacity, connTimeout, customizeSession, dead, deadImpl, get, getFeature, getProperty, idle, isActive, name, onJanitorTimer, purgeDeadSessions, putBack, setFeature, setProperty, shutdown, used

Inherited Functions: duplicate, referenceCount, release

## Types

### FeatureMap

typedef Poco::HashMap < std::string, bool > FeatureMap;

### PooledSessionHolderPtr

typedef Poco::AutoPtr < PooledSessionHolder > PooledSessionHolderPtr;

### PooledSessionImplPtr

typedef Poco::AutoPtr < PooledSessionImpl > PooledSessionImplPtr;

### PropertyMap

typedef Poco::HashMap < std::string, Poco::Any > PropertyMap;

### SessionList

typedef std::list < PooledSessionHolderPtr > SessionList;

## Constructors

### SessionPool

SessionPool(
const std::string & connector,
const std::string & connectionString,
int minSessions = 1,
int maxSessions = 32,
int idleTime = 60,
int connTimeout = 60
);

Creates the SessionPool for sessions with the given connector and connectionString.

The pool allows for at most maxSessions sessions to be created. If a session has been idle for more than idleTime seconds, and more than minSessions sessions are in the pool, the session is automatically destroyed.

## Destructor

### ~SessionPool

~SessionPool();

Destroys the SessionPool.

## Member Functions

### allocated

int allocated() const;

Returns the number of allocated sessions.

### available

int available() const;

Returns the number of available (idle + remaining capacity) sessions.

### capacity

int capacity() const;

Returns the maximum number of sessions the SessionPool will manage.

### connTimeout

int connTimeout() const;

Returns the connection timeout.

### dead

int dead();

Returns the number of not connected active sessions.

### get

Session get();

Returns a Session.

If there are unused sessions available, one of the unused sessions is recycled. Otherwise, a new session is created.

If the maximum number of sessions for this pool has already been created, a SessionPoolExhaustedException is thrown.

### get

template < typename T > Session get(
const std::string & name,
const T & value
);

Returns a Session with requested property set. The property can be different from the default pool value, in which case it is reset back to the pool value when the session is reclaimed by the pool.

### get

Session get(
const std::string & name,
bool value
);

Returns a Session with requested feature set. The feature can be different from the default pool value, in which case it is reset back to the pool value when the session is reclaimed by the pool.

### getFeature

bool getFeature(
const std::string & name
);

Returns the requested feature.

### getProperty

Poco::Any getProperty(
const std::string & name
);

Returns the requested property.

### idle

int idle() const;

Returns the number of idle sessions.

### isActive

bool isActive() const;

Returns true if session pool is active (not shut down).

### name

std::string name() const;

Returns the name for this pool.

### name

static std::string name(
const std::string & connector,
const std::string & connectionString
);

Returns the name formatted from supplied arguments as "connector:///connectionString".

### setFeature

void setFeature(
const std::string & name,
bool state
);

Sets feature for all the sessions.

### setProperty

void setProperty(
const std::string & name,
const Poco::Any & value
);

Sets property for all sessions.

### shutdown

void shutdown();

Shuts down the session pool.

### used

int used() const;

Returns the number of sessions currently in use.

### applySettings

void applySettings(
SessionImpl * pImpl
);

### customizeSession

virtual void customizeSession(
Session & session
);

Can be overridden by subclass to perform custom initialization of a newly created database session.

The default implementation does nothing.

### deadImpl

int deadImpl(
SessionList & rSessions
);

### onJanitorTimer

void onJanitorTimer(
Poco::Timer & param91
);

### purgeDeadSessions

void purgeDeadSessions();

### putBack

void putBack(
PooledSessionHolderPtr pHolder
);