EclipseLink1.0 - 20080707 API Reference

org.eclipse.persistence.sessions.server
Class ClientSession

java.lang.Object
  extended by org.eclipse.persistence.internal.sessions.AbstractSession
      extended by org.eclipse.persistence.sessions.server.ClientSession
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, CommandProcessor, Session

public class ClientSession
extends org.eclipse.persistence.internal.sessions.AbstractSession

Purpose: Acts as a client to the server session.

Description: This session is brokered by the server session for use in three-tiered applications. It is used to store the context of the connection, i.e. the login to be used for this cleint. This allows each client connected to the server to contain its own user login.

Responsibilities:

This class is an implementation of Session. Please refer to that class for a full API. The public interface should be used.

See Also:
Server, 05/28/2008-1.0M8 Andrei Ilitchev - 224964: Provide support for Proxy Authentication through JPA. Added a new constructor that takes Properties., Serialized Form

Field Summary
protected  ConnectionPolicy connectionPolicy
           
protected  boolean isActive
           
protected  ServerSession parent
           
protected  org.eclipse.persistence.internal.sequencing.Sequencing sequencing
           
protected  org.eclipse.persistence.internal.databaseaccess.Accessor writeConnection
           
 
Fields inherited from class org.eclipse.persistence.internal.sessions.AbstractSession
accessor, activeCommandThreads, broker, commandManager, commitManager, defaultReferenceMode, eventManager, exceptionHandler, externalTransactionController, identityMapAccessor, integrityChecker, isFinalizersEnabled, isInBroker, isInProfile, isSynchronized, jpaQueries, lastDescriptorAccessed, logSessionString, name, numberOfActiveUnitsOfWork, platform, profiler, project, properties, queries, sessionLog, shouldPropagateChanges, transactionMutex, wasJTSTransactionInternallyStarted
 
Fields inherited from interface org.eclipse.persistence.sessions.coordination.CommandProcessor
LOG_DEBUG, LOG_ERROR, LOG_INFO, LOG_WARNING
 
Constructor Summary
protected ClientSession(Project project)
           
  ClientSession(ServerSession parent, ConnectionPolicy connectionPolicy)
          INTERNAL: Create and return a new client session.
  ClientSession(ServerSession parent, ConnectionPolicy connectionPolicy, java.util.Map properties)
           
 
Method Summary
 void basicBeginTransaction()
          INTERNAL: This is internal to the unit of work and should never be called otherwise.
 void basicCommitTransaction()
          INTERNAL: This is internal to the unit of work and should not be called otherwise.
 void basicRollbackTransaction()
          INTERNAL: This is internal to the unit of work and should not be called otherwise.
 void connect()
          INTERNAL: Connect the session only (this must be the write connection as the read is shared).
 boolean containsQuery(java.lang.String queryName)
          INTERNAL: Was PUBLIC: customer will be redirected to Session.
 void disconnect()
          INTERNAL: Disconnect the accessor only (this must be the write connection as the read is shared).
 org.eclipse.persistence.internal.databaseaccess.Accessor getAccessor()
          INTERNAL: Return the read or write connection depending on the transaction state.
 CommandManager getCommandManager()
          INTERNAL: Return the manager that allows this processor to receive or propagate commands from/to TopLink cluster
 ConnectionPolicy getConnectionPolicy()
          ADVANCED: This method will return the connection policy that was used during the acquisition of this client session.
 java.util.Map getDescriptors()
          INTERNAL: Was PUBLIC: customer will be redirected to Session.
 org.eclipse.persistence.internal.sessions.AbstractSession getExecutionSession(DatabaseQuery query)
          INTERNAL: Gets the session which this query will be executed on.
 ServerSession getParent()
          INTERNAL: Return the parent.
 org.eclipse.persistence.internal.sessions.AbstractSession getParentIdentityMapSession(DatabaseQuery query, boolean canReturnSelf, boolean terminalOnly)
          INTERNAL: Gets the next link in the chain of sessions followed by a query's check early return, the chain of sessions with identity maps all the way up to the root session.
 java.lang.Object getProperty(java.lang.String name)
          Search for and return the user defined property from this client session, if it not found then search for the property from parent.
 DatabaseQuery getQuery(java.lang.String name)
          INTERNAL: Was PUBLIC: customer will be redirected to Session.
 DatabaseQuery getQuery(java.lang.String name, java.util.Vector args)
          INTERNAL:
 org.eclipse.persistence.internal.sequencing.Sequencing getSequencing()
          INTERNAL: Return the Sequencing object used by the session.
 ServerPlatform getServerPlatform()
          INTERNAL: Marked internal as this is not customer API but helper methods for accessing the server platform from within TopLink's other sessions types (ie not DatabaseSession)
 java.lang.String getSessionTypeString()
          INTERNAL: Returns the type of session, its class.
 org.eclipse.persistence.internal.databaseaccess.Accessor getWriteConnection()
          INTERNAL: Return the connection to be used for database modification.
protected  boolean hasWriteConnection()
          INTERNAL: Return if this session has been connected.
 void initializeIdentityMapAccessor()
          INTERNAL: Set up the IdentityMapManager.
 void initializeSequencing()
          INTERNAL: was ADVANCED: Creates sequencing object for the session.
 boolean isActive()
          INTERNAL: Was PUBLIC: customer will be redirected to Session.
 boolean isClientSession()
          INTERNAL: Return if this session is a client session.
 boolean isConnected()
          INTERNAL: Was PUBLIC: customer will be redirected to Session.
 boolean isExclusiveConnectionRequired()
          INTERNAL: This method is called in case externalConnectionPooling is used.
 void postConnectExternalConnection(org.eclipse.persistence.internal.databaseaccess.Accessor accessor)
          INTERNAL: This method is called in case externalConnectionPooling is used right after the accessor is connected.
 void preDisconnectExternalConnection(org.eclipse.persistence.internal.databaseaccess.Accessor accessor)
          INTERNAL: This method is called in case externalConnectionPooling is used right before the accessor is disconnected.
 void release()
          INTERNAL: Was PUBLIC: customer will be redirected to Session.
 void releaseJTSConnection()
          INTERNAL: Called in the end of beforeCompletion of external transaction sychronization listener.
 void releaseReadConnection(org.eclipse.persistence.internal.databaseaccess.Accessor connection)
          INTERNAL:
protected  void releaseWriteConnection()
          INTERNAL: This is internal to the unit of work and should not be called otherwise.
 void setConnectionPolicy(ConnectionPolicy connectionPolicy)
          INTERNAL: Set the connection policy.
protected  void setIsActive(boolean isActive)
          INTERNAL: Set if the client session is actvie (has not been released).
protected  void setParent(ServerSession parent)
          INTERNAL: Set the parent.
 void setWriteConnection(org.eclipse.persistence.internal.databaseaccess.Accessor writeConnection)
          INTERNAL: Set the connection to be used for database modification.
 boolean shouldPropagateChanges()
          INTERNAL: Return whether changes should be propagated to TopLink cluster.
 java.lang.String toString()
          INTERNAL: Print the connection status with the session.
 
Methods inherited from class org.eclipse.persistence.internal.sessions.AbstractSession
acquireHistoricalSession, acquireNonSynchronizedUnitOfWork, acquireNonSynchronizedUnitOfWork, acquireUnitOfWork, acquireUnitOfWork, addAlias, addJPAQuery, addQuery, addQuery, basicBeginTransaction, beginExternalTransaction, beginTransaction, checkHierarchyForDescriptor, clearIntegrityChecker, clearLastDescriptorAccessed, clearProfile, clone, commitExternalTransaction, commitTransaction, compareObjects, compareObjectsDontMatch, config, copyDescriptorNamedQueries, copyObject, copyObject, copyReadOnlyClasses, deleteAllObjects, deleteAllObjects, deleteObject, doesObjectExist, dontLogMessages, endOperationProfile, endOperationProfile, executeCall, executeNonSelectingCall, executeNonSelectingSQL, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeSelectingCall, executeSQL, fine, finer, finest, getAccessor, getAccessor, getActiveCommandThreads, getActiveSession, getActiveUnitOfWork, getAliasDescriptors, getAllQueries, getAsOfClause, getBroker, getClassDescriptor, getClassDescriptor, getClassDescriptorForAlias, getCommitManager, getDatasourceLogin, getDatasourcePlatform, getDefaultReadOnlyClasses, getDefaultReferenceMode, getDescriptor, getDescriptor, getDescriptorForAlias, getEventManager, getExceptionHandler, getExceptionHandlerClass, getExternalTransactionController, getIdentityMapAccessor, getIdentityMapAccessorInstance, getIntegrityChecker, getJPAQueries, getLog, getLogin, getLogLevel, getLogLevel, getLogSessionString, getName, getNextQueryId, getNextSequenceNumberValue, getNumberOfActiveUnitsOfWork, getParentIdentityMapSession, getPlatform, getPlatform, getProfiler, getProject, getProperties, getQueries, getQuery, getRootSession, getSessionForClass, getSessionLog, getTransactionMutex, handleException, handleSevere, hasBroker, hasCommitManager, hasDescriptor, hasExceptionHandler, hasExternalTransactionController, hasProperties, incrementProfile, info, insertObject, internalExecuteQuery, isBroker, isClassReadOnly, isClassReadOnly, isDatabaseSession, isDistributedSession, isExclusiveIsolatedClientSession, isFinalizersEnabled, isHistoricalSession, isInBroker, isInProfile, isInTransaction, isIsolatedClientSession, isRemoteSession, isRemoteUnitOfWork, isServerSession, isSessionBroker, isSynchronized, isUnitOfWork, keyFromObject, keyFromObject, log, log, log, log, log, log, log, log, log, log, logMessage, logMessage, logThrowable, prepareDatabaseQuery, processCommand, readAllObjects, readAllObjects, readAllObjects, readAllObjects, readObject, readObject, readObject, readObject, readObject, refreshAndLockObject, refreshAndLockObject, refreshObject, registerFinalizer, releaseUnitOfWork, removeProperty, removeQuery, removeQuery, rollbackExternalTransaction, rollbackTransaction, setAccessor, setBroker, setCommandManager, setCommitManager, setDatasourceLogin, setDefaultReferenceMode, setEventManager, setExceptionHandler, setExternalTransactionController, setIntegrityChecker, setIsFinalizersEnabled, setIsInBroker, setIsInProfile, setLog, setLogin, setLogin, setLogLevel, setName, setNumberOfActiveUnitsOfWork, setProfiler, setProject, setProperties, setProperty, setQueries, setSessionLog, setShouldPropagateChanges, setSynchronized, setTransactionMutex, setWasJTSTransactionInternallyStarted, severe, shouldLog, shouldLogMessages, shouldLogMessages, startOperationProfile, startOperationProfile, unwrapObject, updateObject, updateProfile, validateCache, validateQuery, verifyDelete, warning, wasJTSTransactionInternallyStarted, wrapObject, writeAllObjects, writeAllObjectsWithChangeSet, writeObject, writesCompleted
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

parent

protected ServerSession parent

connectionPolicy

protected ConnectionPolicy connectionPolicy

writeConnection

protected org.eclipse.persistence.internal.databaseaccess.Accessor writeConnection

isActive

protected boolean isActive

sequencing

protected org.eclipse.persistence.internal.sequencing.Sequencing sequencing
Constructor Detail

ClientSession

public ClientSession(ServerSession parent,
                     ConnectionPolicy connectionPolicy)
INTERNAL: Create and return a new client session.


ClientSession

public ClientSession(ServerSession parent,
                     ConnectionPolicy connectionPolicy,
                     java.util.Map properties)

ClientSession

protected ClientSession(Project project)
Method Detail

releaseJTSConnection

public void releaseJTSConnection()
INTERNAL: Called in the end of beforeCompletion of external transaction sychronization listener. Close the managed sql connection corresponding to the external transaction and releases accessor.

Overrides:
releaseJTSConnection in class org.eclipse.persistence.internal.sessions.AbstractSession

basicBeginTransaction

public void basicBeginTransaction()
INTERNAL: This is internal to the unit of work and should never be called otherwise.

Overrides:
basicBeginTransaction in class org.eclipse.persistence.internal.sessions.AbstractSession

basicCommitTransaction

public void basicCommitTransaction()
INTERNAL: This is internal to the unit of work and should not be called otherwise.

Overrides:
basicCommitTransaction in class org.eclipse.persistence.internal.sessions.AbstractSession

basicRollbackTransaction

public void basicRollbackTransaction()
INTERNAL: This is internal to the unit of work and should not be called otherwise.

Overrides:
basicRollbackTransaction in class org.eclipse.persistence.internal.sessions.AbstractSession

connect

public void connect()
             throws DatabaseException
INTERNAL: Connect the session only (this must be the write connection as the read is shared).

Throws:
DatabaseException

containsQuery

public boolean containsQuery(java.lang.String queryName)
INTERNAL: Was PUBLIC: customer will be redirected to Session. Return true if the pre-defined query is defined on the session.

Specified by:
containsQuery in interface Session
Overrides:
containsQuery in class org.eclipse.persistence.internal.sessions.AbstractSession

disconnect

public void disconnect()
                throws DatabaseException
INTERNAL: Disconnect the accessor only (this must be the write connection as the read is shared).

Throws:
DatabaseException

getAccessor

public org.eclipse.persistence.internal.databaseaccess.Accessor getAccessor()
INTERNAL: Return the read or write connection depending on the transaction state.

Overrides:
getAccessor in class org.eclipse.persistence.internal.sessions.AbstractSession

getConnectionPolicy

public ConnectionPolicy getConnectionPolicy()
ADVANCED: This method will return the connection policy that was used during the acquisition of this client session. The properties within the ConnectionPolicy may be used when acquiring an exclusive connection for an IsolatedSession.


getDescriptors

public java.util.Map getDescriptors()
INTERNAL: Was PUBLIC: customer will be redirected to Session. Return all registered descriptors. The clients session inherits its parent's descriptors.

Specified by:
getDescriptors in interface Session
Overrides:
getDescriptors in class org.eclipse.persistence.internal.sessions.AbstractSession

getParentIdentityMapSession

public org.eclipse.persistence.internal.sessions.AbstractSession getParentIdentityMapSession(DatabaseQuery query,
                                                                                             boolean canReturnSelf,
                                                                                             boolean terminalOnly)
INTERNAL: Gets the next link in the chain of sessions followed by a query's check early return, the chain of sessions with identity maps all the way up to the root session.

Used for session broker which delegates to registered sessions, or UnitOfWork which checks parent identity map also.

Overrides:
getParentIdentityMapSession in class org.eclipse.persistence.internal.sessions.AbstractSession
Parameters:
canReturnSelf - true when method calls itself. If the path starting at this is acceptable. Sometimes true if want to move to the first valid session, i.e. executing on ClientSession when really should be on ServerSession.
terminalOnly - return the session we will execute the call on, not the next step towards it.
Returns:
this if there is no next link in the chain

getProperty

public java.lang.Object getProperty(java.lang.String name)
Search for and return the user defined property from this client session, if it not found then search for the property from parent.

Specified by:
getProperty in interface Session
Overrides:
getProperty in class org.eclipse.persistence.internal.sessions.AbstractSession

getExecutionSession

public org.eclipse.persistence.internal.sessions.AbstractSession getExecutionSession(DatabaseQuery query)
INTERNAL: Gets the session which this query will be executed on. Generally will be called immediately before the call is translated, which is immediately before session.executeCall.

Since the execution session also knows the correct datasource platform to execute on, it is often used in the mappings where the platform is needed for type conversion, or where calls are translated.

Is also the session with the accessor. Will return a ClientSession if it is in transaction and has a write connection.

Overrides:
getExecutionSession in class org.eclipse.persistence.internal.sessions.AbstractSession
Parameters:
query - may store session name or reference class for brokers case
Returns:
a session with a live accessor

getParent

public ServerSession getParent()
INTERNAL: Return the parent. This is a server session.

Overrides:
getParent in class org.eclipse.persistence.internal.sessions.AbstractSession

getQuery

public DatabaseQuery getQuery(java.lang.String name)
INTERNAL: Was PUBLIC: customer will be redirected to Session. Return the query from the session pre-defined queries with the given name. This allows for common queries to be pre-defined, reused and executed by name.

Specified by:
getQuery in interface Session
Overrides:
getQuery in class org.eclipse.persistence.internal.sessions.AbstractSession

getQuery

public DatabaseQuery getQuery(java.lang.String name,
                              java.util.Vector args)
INTERNAL:

Overrides:
getQuery in class org.eclipse.persistence.internal.sessions.AbstractSession

initializeSequencing

public void initializeSequencing()
INTERNAL: was ADVANCED: Creates sequencing object for the session. Typically there is no need for the user to call this method - it is called from the constructor.


getSequencing

public org.eclipse.persistence.internal.sequencing.Sequencing getSequencing()
INTERNAL: Return the Sequencing object used by the session. Lazy init sequencing to defer from client session creation to improve creation performance.

Overrides:
getSequencing in class org.eclipse.persistence.internal.sessions.AbstractSession

getServerPlatform

public ServerPlatform getServerPlatform()
INTERNAL: Marked internal as this is not customer API but helper methods for accessing the server platform from within TopLink's other sessions types (ie not DatabaseSession)

Specified by:
getServerPlatform in interface Session
Overrides:
getServerPlatform in class org.eclipse.persistence.internal.sessions.AbstractSession

getSessionTypeString

public java.lang.String getSessionTypeString()
INTERNAL: Returns the type of session, its class.

Override to hide from the user when they are using an internal subclass of a known class.

A user does not need to know that their UnitOfWork is a non-deferred UnitOfWork, or that their ClientSession is an IsolatedClientSession.

Overrides:
getSessionTypeString in class org.eclipse.persistence.internal.sessions.AbstractSession

getWriteConnection

public org.eclipse.persistence.internal.databaseaccess.Accessor getWriteConnection()
INTERNAL: Return the connection to be used for database modification.


hasWriteConnection

protected boolean hasWriteConnection()
INTERNAL: Return if this session has been connected.


initializeIdentityMapAccessor

public void initializeIdentityMapAccessor()
INTERNAL: Set up the IdentityMapManager. This method allows subclasses of Session to override the default IdentityMapManager functionality.

Overrides:
initializeIdentityMapAccessor in class org.eclipse.persistence.internal.sessions.AbstractSession

isActive

public boolean isActive()
INTERNAL: Was PUBLIC: customer will be redirected to Session. Return if the client session is actvie (has not been released).


isClientSession

public boolean isClientSession()
INTERNAL: Return if this session is a client session.

Specified by:
isClientSession in interface Session
Overrides:
isClientSession in class org.eclipse.persistence.internal.sessions.AbstractSession

isConnected

public boolean isConnected()
INTERNAL: Was PUBLIC: customer will be redirected to Session. Return if this session has been connected to the database.

Specified by:
isConnected in interface Session
Overrides:
isConnected in class org.eclipse.persistence.internal.sessions.AbstractSession

release

public void release()
             throws DatabaseException
INTERNAL: Was PUBLIC: customer will be redirected to Session. Release the client session. This releases the client session back to it server. Normally this will logout of the client session's connection, and allow the client session to garbage collect.

Specified by:
release in interface Session
Overrides:
release in class org.eclipse.persistence.internal.sessions.AbstractSession
Throws:
DatabaseException

releaseWriteConnection

protected void releaseWriteConnection()
INTERNAL: This is internal to the unit of work and should not be called otherwise.


setConnectionPolicy

public void setConnectionPolicy(ConnectionPolicy connectionPolicy)
INTERNAL: Set the connection policy.


setIsActive

protected void setIsActive(boolean isActive)
INTERNAL: Set if the client session is actvie (has not been released).


setParent

protected void setParent(ServerSession parent)
INTERNAL: Set the parent. This is a server session.


setWriteConnection

public void setWriteConnection(org.eclipse.persistence.internal.databaseaccess.Accessor writeConnection)
INTERNAL: Set the connection to be used for database modification.


toString

public java.lang.String toString()
INTERNAL: Print the connection status with the session.

Overrides:
toString in class org.eclipse.persistence.internal.sessions.AbstractSession

getCommandManager

public CommandManager getCommandManager()
INTERNAL: Return the manager that allows this processor to receive or propagate commands from/to TopLink cluster

Specified by:
getCommandManager in interface CommandProcessor
Overrides:
getCommandManager in class org.eclipse.persistence.internal.sessions.AbstractSession
Returns:
a remote command manager
See Also:
#CommandManager

shouldPropagateChanges

public boolean shouldPropagateChanges()
INTERNAL: Return whether changes should be propagated to TopLink cluster. This is one of the required cache synchronization setting

Overrides:
shouldPropagateChanges in class org.eclipse.persistence.internal.sessions.AbstractSession

releaseReadConnection

public void releaseReadConnection(org.eclipse.persistence.internal.databaseaccess.Accessor connection)
INTERNAL:

Overrides:
releaseReadConnection in class org.eclipse.persistence.internal.sessions.AbstractSession

postConnectExternalConnection

public void postConnectExternalConnection(org.eclipse.persistence.internal.databaseaccess.Accessor accessor)
INTERNAL: This method is called in case externalConnectionPooling is used right after the accessor is connected. Used by the session to rise an appropriate event.

Overrides:
postConnectExternalConnection in class org.eclipse.persistence.internal.sessions.AbstractSession

preDisconnectExternalConnection

public void preDisconnectExternalConnection(org.eclipse.persistence.internal.databaseaccess.Accessor accessor)
INTERNAL: This method is called in case externalConnectionPooling is used right before the accessor is disconnected. Used by the session to rise an appropriate event.

Overrides:
preDisconnectExternalConnection in class org.eclipse.persistence.internal.sessions.AbstractSession

isExclusiveConnectionRequired

public boolean isExclusiveConnectionRequired()
INTERNAL: This method is called in case externalConnectionPooling is used. If returns true, accessor used by the session keeps its connection open until released by the session.

Overrides:
isExclusiveConnectionRequired in class org.eclipse.persistence.internal.sessions.AbstractSession

EclipseLink1.0 - 20080707 API Reference