org.eclipse.persistence.sessions.server
Interface Server

All Superinterfaces:

DatabaseSession, Session

All Known Implementing Classes:

ServerSession

public interface Server
extends DatabaseSession

Purpose: A single session that supports multiple user/clients connection at the same time.

Description: This session supports a shared session that can be used by multiple users or clients in a three-tiered application. It brokers client sessions to allow read and write access through a unified object cache. The server session uses a single connection pool by default, but allows multiple connection pools and separate read/write pools to be configured. All changes to objects and the database must be done through a unit of work acquired from the client session, this allows the changes to occur in a transactional object space and under a exclusive database connection.

Responsibilities:

• Connection pooling.
• Reading objects and maintaining the object cache.
• Brokering client sessions.
• Requiring the UnitOfWork to be used for modification.

See Also:

Server, ClientSession, UnitOfWork

Method Summary

ClientSession	acquireClientSession() PUBLIC: Return a client session for this server session.
ClientSession	acquireClientSession(ConnectionPolicy connectionPolicy) PUBLIC: Return a client session for this server session.
ClientSession	acquireClientSession(Login login) PUBLIC: Return a client session for this server session.
ClientSession	acquireClientSession(java.lang.String poolName) PUBLIC: Return a client session for this server session.
void	addConnectionPool(ConnectionPool pool) PUBLIC: Connection are pooled to share and restrict the number of database connections.
void	addConnectionPool(java.lang.String poolName, Login login, int minNumberOfConnections, int maxNumberOfConnections) PUBLIC: Add the connection pool.
ConnectionPool	getConnectionPool(java.lang.String poolName) PUBLIC: Return the pool by name.
ConnectionPolicy	getDefaultConnectionPolicy() PUBLIC: The default connection policy is used by default by the acquireClientConnection() protocol.
ConnectionPool	getDefaultConnectionPool() PUBLIC: Return the default connection pool.
int	getMaxNumberOfNonPooledConnections() PUBLIC: Return the number of non-pooled database connections allowed.
ConnectionPool	getReadConnectionPool() PUBLIC: Handles allocating connections for read queries.
void	setDatasourceLogin(Login login) PUBLIC: Set the login.
void	setDefaultConnectionPolicy(ConnectionPolicy defaultConnectionPolicy) PUBLIC: The default connection policy is used by default by the acquireClientConnection() protocol.
void	setMaxNumberOfNonPooledConnections(int maxNumberOfNonPooledConnections) PUBLIC: Set the number of non-pooled database connections allowed.
void	setReadConnectionPool(ConnectionPool readConnectionPool) PUBLIC: Sets the read connection pool directly.
void	useExclusiveReadConnectionPool(int minNumberOfConnections, int maxNumberOfConnections) PUBLIC: Sets the read connection pool to be a separate exclusive ConnectionPool with the minimum and maximum number of connections.
void	useExclusiveReadConnectionPool(int initialNumberOfConnections, int minNumberOfConnections, int maxNumberOfConnections) PUBLIC: Sets the read connection pool to be a separate exclusive ConnectionPool with the initial, minimum and maximum number of connections.
void	useExternalReadConnectionPool() PUBLIC: Sets the read connection pool to be an ExternalConnectionPool.
void	useReadConnectionPool(int minNumberOfConnections, int maxNumberOfConnections) PUBLIC: Sets the read connection pool to be a separate shared ConnectionPool with the minimum and maximum number of connections.
void	useReadConnectionPool(int initialNumberOfConnections, int minNumberOfConnections, int maxNumberOfConnections) PUBLIC: Sets the read connection pool to be a separate shared ConnectionPool with the minimum and maximum number of connections.

Methods inherited from interface org.eclipse.persistence.sessions.DatabaseSession

addDescriptor, addDescriptors, addDescriptors, beginTransaction, commitTransaction, deleteAllObjects, deleteObject, getCommandManager, getSequencingControl, getServerPlatform, insertObject, isInTransaction, login, login, login, logout, refreshAndLockObject, refreshAndLockObject, rollbackTransaction, setCommandManager, setExternalTransactionController, setLogin, setServerPlatform, setShouldPropagateChanges, shouldPropagateChanges, updateObject, writeAllObjects, writeObject

Methods inherited from interface org.eclipse.persistence.sessions.Session

acquireHistoricalSession, acquireUnitOfWork, acquireUnitOfWork, addJPAQuery, addQuery, clearIntegrityChecker, clearProfile, containsQuery, copyObject, copyObject, doesObjectExist, dontLogMessages, executeNonSelectingCall, executeNonSelectingSQL, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeSelectingCall, executeSQL, getActiveSession, getActiveUnitOfWork, getAsOfClause, getClassDescriptor, getClassDescriptor, getClassDescriptorForAlias, getDatasourceLogin, getDatasourcePlatform, getDefaultReferenceMode, getDescriptor, getDescriptor, getDescriptorForAlias, getDescriptors, getEventManager, getExceptionHandler, getExternalTransactionController, getIdentityMapAccessor, getIntegrityChecker, getJPAQueries, getLog, getLogin, getLogLevel, getLogLevel, getName, getNextSequenceNumberValue, getPlatform, getProfiler, getProject, getProperties, getProperty, getQueries, getQuery, getQuery, getSessionLog, handleException, handleSevere, hasDescriptor, hasExceptionHandler, hasExternalTransactionController, isClientSession, isConnected, isDatabaseSession, isDistributedSession, isFinalizersEnabled, isInProfile, isRemoteSession, isRemoteUnitOfWork, isServerSession, isSessionBroker, isUnitOfWork, keyFromObject, log, logMessage, readAllObjects, readAllObjects, readAllObjects, readObject, readObject, readObject, readObject, refreshObject, release, removeProperty, removeQuery, setDefaultReferenceMode, setExceptionHandler, setIntegrityChecker, setIsFinalizersEnabled, setLog, setLogLevel, setName, setProfiler, setProperty, setSessionLog, shouldLog, shouldLogMessages, validateCache

Method Detail

acquireClientSession

ClientSession acquireClientSession()
                                   throws DatabaseException

PUBLIC: Return a client session for this server session. Each user/client connected to this server session must acquire there own client session to communicate to the server through. This method allows for a client session to be acquired sharing the same login as the server session.

Throws:

DatabaseException

acquireClientSession

ClientSession acquireClientSession(java.lang.String poolName)

PUBLIC: Return a client session for this server session. Each user/client connected to this server session must acquire there own client session to communicate to the server through. This method allows for a client session to be acquired sharing its connection from a pool of connection allocated on the server session. By default this uses a lazy connection policy.

acquireClientSession

ClientSession acquireClientSession(Login login)

PUBLIC: Return a client session for this server session. Each user/client connected to this server session must acquire there own client session to communicate to the server through. The client must provide its own login to use, and the client session returned will have its own exclusive database connection. This connection will be used to perform all database modification for all units of work acquired from the client session. By default this does not use a lazy connection policy.

acquireClientSession

ClientSession acquireClientSession(ConnectionPolicy connectionPolicy)

PUBLIC: Return a client session for this server session. The connection policy specifies how the client session's connection will be acquired.

addConnectionPool

void addConnectionPool(java.lang.String poolName,
                       Login login,
                       int minNumberOfConnections,
                       int maxNumberOfConnections)

PUBLIC: Add the connection pool. Connections are pooled to share and restrict the number of database connections.

addConnectionPool

void addConnectionPool(ConnectionPool pool)

PUBLIC: Connection are pooled to share and restrict the number of database connections.

getConnectionPool

ConnectionPool getConnectionPool(java.lang.String poolName)

PUBLIC: Return the pool by name.

getDefaultConnectionPolicy

ConnectionPolicy getDefaultConnectionPolicy()

PUBLIC: The default connection policy is used by default by the acquireClientConnection() protocol. By default it uses the default connection pool.

getDefaultConnectionPool

ConnectionPool getDefaultConnectionPool()

PUBLIC: Return the default connection pool.

getMaxNumberOfNonPooledConnections

int getMaxNumberOfNonPooledConnections()

PUBLIC: Return the number of non-pooled database connections allowed. This can be enforced to make up for the resource limitation of most JDBC drivers and database clients. By default this is 50.

getReadConnectionPool

ConnectionPool getReadConnectionPool()

PUBLIC: Handles allocating connections for read queries.

By default a read connection pool is not used, the default connection pool is used for reading.

The read connection pool is not used while in transaction.

See Also:

setReadConnectionPool(ConnectionPool), useExclusiveReadConnectionPool(int, int), useExternalReadConnectionPool(), useReadConnectionPool(int, int)

setDatasourceLogin

void setDatasourceLogin(Login login)

PUBLIC: Set the login.

Specified by:

setDatasourceLogin in interface DatabaseSession

setDefaultConnectionPolicy

void setDefaultConnectionPolicy(ConnectionPolicy defaultConnectionPolicy)

PUBLIC: The default connection policy is used by default by the acquireClientConnection() protocol. By default it uses the default connection pool.

setMaxNumberOfNonPooledConnections

void setMaxNumberOfNonPooledConnections(int maxNumberOfNonPooledConnections)

PUBLIC: Set the number of non-pooled database connections allowed. This can be enforced to make up for the resource limitation of most JDBC drivers and database clients. By default this is 50.

setReadConnectionPool

void setReadConnectionPool(ConnectionPool readConnectionPool)

PUBLIC: Sets the read connection pool directly.

Either useExclusiveReadConnectionPool(int, int) or useExternalReadConnectionPool() is called in the constructor. For a connection pool using concurrent reading useReadConnectionPool(int, int) should be called on a new instance of this.

Throws:

ValidationException - if already connected

useExclusiveReadConnectionPool

void useExclusiveReadConnectionPool(int minNumberOfConnections,
                                    int maxNumberOfConnections)

PUBLIC: Sets the read connection pool to be a separate exclusive ConnectionPool with the minimum and maximum number of connections.

A separate read connection pool is not used by default, by default the default connection pool is used for reading. A separate read connection pool can be used to dedicate a pool of connections only for reading. It can also be used to use a non-JTA DataSource for reading to avoid JTA overhead, or to use a different user login for reading.

See Also:

getReadConnectionPool(), setReadConnectionPool(ConnectionPool), useReadConnectionPool(int, int), useExternalReadConnectionPool()

useExclusiveReadConnectionPool

void useExclusiveReadConnectionPool(int initialNumberOfConnections,
                                    int minNumberOfConnections,
                                    int maxNumberOfConnections)

PUBLIC: Sets the read connection pool to be a separate exclusive ConnectionPool with the initial, minimum and maximum number of connections.

A separate read connection pool is not used by default, by default the default connection pool is used for reading. A separate read connection pool can be used to dedicate a pool of connections only for reading. It can also be used to use a non-JTA DataSource for reading to avoid JTA overhead, or to use a different user login for reading.

See Also:

getReadConnectionPool(), setReadConnectionPool(ConnectionPool), useReadConnectionPool(int, int), useExternalReadConnectionPool()

useExternalReadConnectionPool

void useExternalReadConnectionPool()

PUBLIC: Sets the read connection pool to be an ExternalConnectionPool.

This type of connection pool will be created and configured automatically if an external connection pooling is used.

See Also:

getReadConnectionPool(), setReadConnectionPool(ConnectionPool), useReadConnectionPool(int, int), useExclusiveReadConnectionPool(int, int)

useReadConnectionPool

void useReadConnectionPool(int minNumberOfConnections,
                           int maxNumberOfConnections)

PUBLIC: Sets the read connection pool to be a separate shared ConnectionPool with the minimum and maximum number of connections.

A separate read connection pool is not used by default, by default the default connection pool is used for reading. A separate read connection pool can be used to dedicate a pool of connections only for reading. It can also be used to use a non-JTA DataSource for reading to avoid JTA overhead, or to use a different user login for reading.

Since read connections are not used for writing, multiple users can theoretically use the same connection at the same time. However some JDBC drivers do not allow this, or have poor concurrency when this is done.

Use this read connection pool to take advantage of concurrent reading.

Parameters:

minNumberOfConnections -

maxNumberOfConnections - As multiple readers can use the same connection concurrently fewer connections are needed.

See Also:

getReadConnectionPool(), setReadConnectionPool(ConnectionPool), useExternalReadConnectionPool(), useExclusiveReadConnectionPool(int, int)

useReadConnectionPool

void useReadConnectionPool(int initialNumberOfConnections,
                           int minNumberOfConnections,
                           int maxNumberOfConnections)

PUBLIC: Sets the read connection pool to be a separate shared ConnectionPool with the minimum and maximum number of connections.

A separate read connection pool is not used by default, by default the default connection pool is used for reading. A separate read connection pool can be used to dedicate a pool of connections only for reading. It can also be used to use a non-JTA DataSource for reading to avoid JTA overhead, or to use a different user login for reading.

Since read connections are not used for writing, multiple users can theoretically use the same connection at the same time. However some JDBC drivers do not allow this, or have poor concurrency when this is done.

Use this read connection pool to take advantage of concurrent reading.

Parameters:

initialNumberOfConnections - connections connected at startup

minNumberOfConnections - connections that are pooled

maxNumberOfConnections - As multiple readers can use the same connection concurrently fewer connections are needed.

See Also:

getReadConnectionPool(), setReadConnectionPool(ConnectionPool), useExternalReadConnectionPool(), useExclusiveReadConnectionPool(int, int)