DatabaseSession (EclipseLink 2.6.2, API Reference)

All Superinterfaces:

CoreSession<ClassDescriptor,Login,org.eclipse.persistence.internal.databaseaccess.Platform,Project,SessionEventManager>, Session

All Known Subinterfaces:

Server

All Known Implementing Classes:

org.eclipse.persistence.internal.sessions.DatabaseSessionImpl, DistributedSession, RemoteSession, ServerSession, SessionBroker
```
public interface DatabaseSession
extends Session
```
Purpose: Add login and configuration API to that of Session. This interface is to be used during the creation and login of the session only. The Session interface should be used after login for normal reading/writing.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addDescriptor(ClassDescriptor descriptor)` PUBLIC: Add the descriptor to the session.
`void`	`addDescriptors(java.util.Collection descriptors)` PUBLIC: Add the descriptors to the session.
`void`	`addDescriptors(Project project)` PUBLIC: Add the descriptors to the session from the Project.
`void`	`addSequence(Sequence sequence)` PUBLIC: Add the sequence to the session.
`void`	`beginTransaction()` PUBLIC: Begin a transaction on the database.
`void`	`commitTransaction()` PUBLIC: Commit the active database transaction.
`void`	`deleteAllObjects(java.util.Collection domainObjects)` PUBLIC: delete all of the objects and all of their privately owned parts in the database.
`java.lang.Object`	`deleteObject(java.lang.Object domainObject)` PUBLIC: Delete the object and all of its privately owned parts from the database.
`CommandManager`	`getCommandManager()` ADVANCED: Return the CommandManager that allows this session to act as a CommandProcessor and receive or propagate commands from/to the EclipseLink cluster.
`DatabaseEventListener`	`getDatabaseEventListener()` Return the database event listener, this allows database events to invalidate the cache.
`SequencingControl`	`getSequencingControl()` PUBLIC: Return SequencingControl which used for sequencing setup and customization including management of sequencing preallocation.
`ServerPlatform`	`getServerPlatform()` PUBLIC: Answer the server platform defining server-specific behavior for the receiver (Oc4j, WLS, ...).
`java.lang.Object`	`insertObject(java.lang.Object domainObject)` PUBLIC: Insert the object and all of its privately owned parts into the database.
`boolean`	`isInTransaction()` PUBLIC: Return if the session is currently in the progress of a database transaction.
`void`	`login()` PUBLIC: Connect to the database using the predefined login.
`void`	`login(Login login)` PUBLIC: Connect to the database using the given login.
`void`	`login(java.lang.String userName, java.lang.String password)` PUBLIC: Connect to the database using the given user name and password.
`void`	`logout()` PUBLIC: Disconnect from the database.
`java.lang.Object`	`refreshAndLockObject(java.lang.Object object)` PUBLIC: Refresh the attributes of the object and of all of its private parts from the database.
`java.lang.Object`	`refreshAndLockObject(java.lang.Object object, short lockMode)` PUBLIC: Refresh the attributes of the object and of all of its private parts from the database.
`void`	`rollbackTransaction()` PUBLIC: Rollback the active database transaction.
`void`	`setCommandManager(CommandManager commandManager)` ADVANCED: Set the CommandManager that allows this session to act as a CommandProcessor and receive or propagate commands from/to the EclipseLink cluster.
`void`	`setDatabaseEventListener(DatabaseEventListener databaseEventListener)` PUBLIC: Set the database event listener, this allows database events to invalidate the cache.
`void`	`setDatasourceLogin(Login login)` PUBLIC: Set the login.
`void`	`setExternalTransactionController(ExternalTransactionController etc)` PUBLIC: Used for JTS integration.
`void`	`setLogin(Login login)` PUBLIC: Set the login.
`void`	`setServerPlatform(ServerPlatform newServerPlatform)` PUBLIC: Set the server platform defining server-specific behavior for the receiver (Oc4j, WLS, ... ).
`void`	`setShouldPropagateChanges(boolean choice)` ADVANCED: Set if cache changes should be propagated to other sessions or applications in a EclipseLink cluster through the Remote Command Manager mechanism.
`boolean`	`shouldPropagateChanges()` ADVANCED: Return whether changes should be propagated to other sessions or applications in a EclipseLink cluster through the Remote Command Manager mechanism.
`java.lang.Object`	`updateObject(java.lang.Object domainObject)` PUBLIC: Update the object and all of its privately owned parts in the database.
`void`	`writeAllObjects(java.util.Collection domainObjects)` PUBLIC: Write all of the objects and all of their privately owned parts in the database.
`java.lang.Object`	`writeObject(java.lang.Object domainObject)` PUBLIC: Write the object and all of its privately owned parts in the database.

Methods inherited from interface org.eclipse.persistence.sessions.Session
acquireHistoricalSession, acquireUnitOfWork, acquireUnitOfWork, addJPAQuery, addQuery, clearIntegrityChecker, clearProfile, containsQuery, copy, copy, 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, getId, getIdentityMapAccessor, getIntegrityChecker, getJPAQueries, getLog, getLogin, getLogLevel, getLogLevel, getName, getNextSequenceNumberValue, getPartitioningPolicy, getPlatform, getProfiler, getProject, getProperties, getProperty, getQueries, getQuery, getQuery, getSerializer, 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, setPartitioningPolicy, setProfiler, setProperty, setQueryTimeoutDefault, setSerializer, setSessionLog, shouldLog, shouldLogMessages, validateCache

- Method Detail
  - addDescriptor
```
void addDescriptor(ClassDescriptor descriptor)
```
    PUBLIC: Add the descriptor to the session. All persistent classes must have a descriptor registered for them with the session. It is best to add the descriptors before login, if added after login the order in which descriptors are added is dependent on inheritance and references unless the addDescriptors method is used.
    
    See Also:
    addDescriptors(Collection), addDescriptors(Project)
  - addDescriptors
```
void addDescriptors(java.util.Collection descriptors)
```
    PUBLIC: Add the descriptors to the session. All persistent classes must have a descriptor registered for them with the session. This method allows for a batch of descriptors to be added at once so that EclipseLink can resolve the dependencies between the descriptors and perform initialization optimally.
  - addSequence
```
void addSequence(Sequence sequence)
```
    PUBLIC: Add the sequence to the session. Allows to add a new sequence to the session even if the session is connected. If the session is connected then the sequence is added only if there is no sequence with the same name already in use. Call this method before addDescriptor(s) if need to add new descriptor with a new non-default sequence to connected session.
    
    See Also:
    addDescriptor(org.eclipse.persistence.descriptors.ClassDescriptor), addDescriptors(java.util.Collection)
  - addDescriptors
```
void addDescriptors(Project project)
```
    PUBLIC: Add the descriptors to the session from the Project. This can be used to combine the descriptors from multiple projects into a single session. This can be called after the session has been connected as long as there are no external dependencies.
  - beginTransaction
```
void beginTransaction()
                      throws DatabaseException
```
    PUBLIC: Begin a transaction on the database. This allows a group of database modification to be committed or rolledback as a unit. All writes/deletes will be sent to the database be will not be visible to other users until commit. Although databases do not allow nested transaction, EclipseLink supports nesting through only committing to the database on the outer commit.
    
    Throws:
    
    DatabaseException - if the database connection is lost or the begin is rejected.
    See Also:
    isInTransaction()
  - commitTransaction
```
void commitTransaction()
                       throws DatabaseException
```
    PUBLIC: Commit the active database transaction. This allows a group of database modification to be committed or rolledback as a unit. All writes/deletes will be sent to the database be will not be visible to other users until commit. Although databases do not allow nested transaction, EclipseLink supports nesting through only committing to the database on the outer commit.
    
    Throws:
    
    DatabaseException - most databases validate changes as they are done, normally errors do not occur on commit unless the disk fails or the connection is lost.
    
    ConcurrencyException - if this session is not within a transaction.
  - deleteAllObjects
```
void deleteAllObjects(java.util.Collection domainObjects)
```
    PUBLIC: delete all of the objects and all of their privately owned parts in the database. The allows for a group of objects to be deleted as a unit. The objects will be deleted through a single transactions.
    
    Throws:
    
    DatabaseException - if an error occurs on the database, these include constraint violations, security violations and general database errors.
    
    OptimisticLockException - if the object's descriptor is using optimistic locking and the object has been updated or deleted by another user since it was last read.
  - deleteObject
```
java.lang.Object deleteObject(java.lang.Object domainObject)
                              throws DatabaseException,
                                     OptimisticLockException
```
    PUBLIC: Delete the object and all of its privately owned parts from the database. The delete operation can be customized through using a delete query.
    
    Throws:
    
    DatabaseException
    
    OptimisticLockException
    See Also:
    DeleteObjectQuery
  - insertObject
```
java.lang.Object insertObject(java.lang.Object domainObject)
                              throws DatabaseException
```
    PUBLIC: Insert the object and all of its privately owned parts into the database. Insert should only be used if the application knows that the object is new, otherwise writeObject should be used. The insert operation can be customized through using an insert query.
    
    Throws:
    
    DatabaseException
    See Also:
    InsertObjectQuery, writeObject(Object)
  - isInTransaction
```
boolean isInTransaction()
```
    PUBLIC: Return if the session is currently in the progress of a database transaction. Because nested transactions are allowed check if the transaction mutex has been acquired.
  - setServerPlatform
```
void setServerPlatform(ServerPlatform newServerPlatform)
```
    PUBLIC: Set the server platform defining server-specific behavior for the receiver (Oc4j, WLS, ... ). This is not permitted after the session is logged in. If the user wants a different external transaction controller class or to provide some different behavior than the provided ServerPlatform(s), we recommend subclassing org.eclipse.persistence.platform.server.ServerPlatformBase (or a subclass), and overriding: ServerPlatformBase.getExternalTransactionControllerClass() ServerPlatformBase.registerMBean() ServerPlatformBase.unregisterMBean() for the desired behavior.
    
    See Also:
    ServerPlatformBase
  - getServerPlatform
```
ServerPlatform getServerPlatform()
```
    PUBLIC: Answer the server platform defining server-specific behavior for the receiver (Oc4j, WLS, ...). If the user wants a different external transaction controller class or to provide some different behavior than the provided ServerPlatform(s), we recommend subclassing org.eclipse.persistence.platform.server.ServerPlatformBase (or a subclass), and overriding: ServerPlatformBase.getExternalTransactionControllerClass() ServerPlatformBase.registerMBean() ServerPlatformBase.unregisterMBean() for the desired behavior.
    
    Specified by:
    
    getServerPlatform in interface Session
    
    See Also:
    ServerPlatformBase
  - getSequencingControl
```
SequencingControl getSequencingControl()
```
    PUBLIC: Return SequencingControl which used for sequencing setup and customization including management of sequencing preallocation.
  - login
```
void login()
           throws DatabaseException
```
    PUBLIC: Connect to the database using the predefined login. The login must have been assign when or after creating the session.
    
    Throws:
    
    DatabaseException
    See Also:
    login(Login)
  - login
```
void login(java.lang.String userName,
         java.lang.String password)
           throws DatabaseException
```
    PUBLIC: Connect to the database using the given user name and password. The additional login information must have been preset in the session's login attribute. This is the login that should be used if each user has their own id, but all users share the same database configuration. Under this login mode the password should not stay within the login definition after login.
    
    Throws:
    
    DatabaseException
  - login
```
void login(Login login)
           throws DatabaseException
```
    PUBLIC: Connect to the database using the given login. The login may also the preset and the login() protocol called. This is the login should only be used if each user has their own database configuration. Under this login mode the password should not stay within the login definition after login.
    
    Throws:
    
    DatabaseException
  - logout
```
void logout()
            throws DatabaseException
```
    PUBLIC: Disconnect from the database.
    
    Throws:
    
    EclipseLinkException - if a transaction is active, you must rollback any active transaction before logout.
    
    DatabaseException - the database will also raise an error if their is an active transaction, or a general error occurs.
  - refreshAndLockObject
```
java.lang.Object refreshAndLockObject(java.lang.Object object)
```
    PUBLIC: Refresh the attributes of the object and of all of its private parts from the database. The object will be pessimistically locked on the database for the duration of the transaction. If the object is already locked this method will wait until the lock is released. A no wait option is available through setting the lock mode.
    
    See Also:
    refreshAndLockObject(Object, short)
  - refreshAndLockObject
```
java.lang.Object refreshAndLockObject(java.lang.Object object,
                                    short lockMode)
```
    PUBLIC: Refresh the attributes of the object and of all of its private parts from the database. The object will be pessimistically locked on the database for the duration of the transaction.
    Lock Modes: ObjectBuildingQuery.NO_LOCK, LOCK, LOCK_NOWAIT
  - rollbackTransaction
```
void rollbackTransaction()
                         throws DatabaseException
```
    PUBLIC: Rollback the active database transaction. This allows a group of database modification to be committed or rolled back as a unit. All writes/deletes will be sent to the database be will not be visible to other users until commit. Although databases do not allow nested transaction, EclipseLink supports nesting through only committing to the database on the outer commit.
    
    Throws:
    
    DatabaseException - if the database connection is lost or the rollback fails.
    
    ConcurrencyException - if this session is not within a transaction.
  - setExternalTransactionController
```
void setExternalTransactionController(ExternalTransactionController etc)
```
    PUBLIC: Used for JTS integration. If your application requires to have JTS control transactions instead of EclipseLink an external transaction controller must be specified. EclipseLink provides JTS controllers for JTS 1.0 and Weblogic's JTS.
    
    Specified by:
    
    setExternalTransactionController in interface Session
    
    See Also:
    JTATransactionController, CustomServerPlatform
  - getCommandManager
```
CommandManager getCommandManager()
```
    ADVANCED: Return the CommandManager that allows this session to act as a CommandProcessor and receive or propagate commands from/to the EclipseLink cluster. This can be set to enable cache synchronization in a clustered environment where multiple servers in the cluster update the same database.
    
    Returns:
    The CommandManager instance that controls the remote command service for this session.
    See Also:
    CommandManager
  - setCommandManager
```
void setCommandManager(CommandManager commandManager)
```
    ADVANCED: Set the CommandManager that allows this session to act as a CommandProcessor and receive or propagate commands from/to the EclipseLink cluster. This can be used to enable cache synchronization in a clustered environment where multiple servers in the cluster update the same database. To enable cache synchronization you must also set, setShouldPropagateChanges to true.
    
    Parameters:
    commandManager - The CommandManager instance to control the remote command service for this session.
    See Also:
    setShouldPropagateChanges(boolean), CommandManager
  - setShouldPropagateChanges
```
void setShouldPropagateChanges(boolean choice)
```
    ADVANCED: Set if cache changes should be propagated to other sessions or applications in a EclipseLink cluster through the Remote Command Manager mechanism. This can be used to enable cache synchronization in a clustered environment where multiple servers in the cluster update the same database. In order for this to occur the CommandManager must be set.
    
    Parameters:
    choice - If true (and the CommandManager is set) then propagation will occur.
    See Also:
    setCommandManager(CommandManager)
  - shouldPropagateChanges
```
boolean shouldPropagateChanges()
```
    ADVANCED: Return whether changes should be propagated to other sessions or applications in a EclipseLink cluster through the Remote Command Manager mechanism. In order for this to occur the CommandManager must be set.
    
    Returns:
    true if propagation is set to occur, false if not.
    See Also:
    setCommandManager(CommandManager)
  - setLogin
```
void setLogin(Login login)
```
    PUBLIC: Set the login.
  - setDatasourceLogin
```
void setDatasourceLogin(Login login)
```
    PUBLIC: Set the login.
  - updateObject
```
java.lang.Object updateObject(java.lang.Object domainObject)
                              throws DatabaseException,
                                     OptimisticLockException
```
    PUBLIC: Update the object and all of its privately owned parts in the database. Update should only be used if the application knows that the object is new, otherwise writeObject should be used. The update operation can be customized through using an update query.
    
    Throws:
    
    DatabaseException
    
    OptimisticLockException
    See Also:
    UpdateObjectQuery, writeObject(Object)
  - writeAllObjects
```
void writeAllObjects(java.util.Collection domainObjects)
```
    PUBLIC: Write all of the objects and all of their privately owned parts in the database. The allows for a group of objects to be committed as a unit. The objects will be committed through a single transactions.
    
    Throws:
    
    DatabaseException - if an error occurs on the database, these include constraint violations, security violations and general database errors.
    
    OptimisticLockException - if the object's descriptor is using optimistic locking and the object has been updated or deleted by another user since it was last read.
  - writeObject
```
java.lang.Object writeObject(java.lang.Object domainObject)
                             throws DatabaseException,
                                    OptimisticLockException
```
    PUBLIC: Write the object and all of its privately owned parts in the database. Write will determine if an insert or an update should be done, it may go to the database to determine this (by default will check the identity map). The write operation can be customized through using an write query.
    
    Throws:
    
    DatabaseException
    
    OptimisticLockException
    See Also:
    WriteObjectQuery, insertObject(Object), updateObject(Object)
  - getDatabaseEventListener
```
DatabaseEventListener getDatabaseEventListener()
```
    Return the database event listener, this allows database events to invalidate the cache.
  - setDatabaseEventListener
```
void setDatabaseEventListener(DatabaseEventListener databaseEventListener)
```
    PUBLIC: Set the database event listener, this allows database events to invalidate the cache.

Interface DatabaseSession

Method Summary

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

Method Detail

addDescriptor

addDescriptors

addSequence

addDescriptors

beginTransaction

commitTransaction

deleteAllObjects

deleteObject

insertObject

isInTransaction

setServerPlatform

getServerPlatform

getSequencingControl

login

login

login

logout

refreshAndLockObject

refreshAndLockObject

rollbackTransaction

setExternalTransactionController

getCommandManager

setCommandManager

setShouldPropagateChanges

shouldPropagateChanges

setLogin

setDatasourceLogin

updateObject

writeAllObjects

writeObject

getDatabaseEventListener

setDatabaseEventListener