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 provides a shared read only database connection that is used by all of its client for reads. 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:

• Connecting/disconnecting the default reading login.
• Reading objects and maintaining the object cache.
• Brokering client sessions.
• Disabling database modification through the shared connection.

See Also:

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 standard ConnectionPool.
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 ReadConnectionPool.

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 is a connection pool with min 5 and max 10 lazy pooled connections.

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 created and configured automatically in the constructor. A default read connection pool is one with two connections, and does not support concurrent reads.

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 is a connection pool with min 5 and max 10 lazy pooled connections.

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 standard ConnectionPool.

Minimum and maximum number of connections is determined from the ConnectionPolicy. The defaults are 2 for both.

Since the same type of connection pool is used as for writing, no two users will use the same connection for reading at the same time.

This read connection pool is the default as some JDBC drivers do not support concurrent reading.

Unless this hasExternalTransactionController() a read connection pool of this type will be setup in the constructor.

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 transaction controller is used.

See Also:

Session.hasExternalTransactionController(), 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 ReadConnectionPool.

Since read connections are not used for writing, multiple users can theoretically use the same connection at the same time. Most JDBC drivers have concurrent reading which supports this.

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)