oracle.toplink.sessions
Interface DatabaseSession

All Superinterfaces:

Session

All Known Subinterfaces:

Server

All Known Implementing Classes:

oracle.toplink.publicinterface.DatabaseSession

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

void	addDescriptor(Descriptor descriptor) PUBLIC: Add the descriptor to the session.
void	addDescriptors(Project project) PUBLIC: Add the descriptors to the session from the Project.
void	addDescriptors(java.util.Vector descriptors) PUBLIC: Add the descriptors 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.
void	deleteAllObjects(java.util.Vector 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.
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	setExternalTransactionController(ExternalTransactionController etc) PUBLIC: Used for JTS integration.
void	setLogin(DatabaseLogin login) PUBLIC: Set the login.
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.
void	writeAllObjects(java.util.Vector 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 oracle.toplink.sessions.Session

acquireUnitOfWork, addQuery, clearIntegrityChecker, clearProfile, containsObjectInIdentityMap, containsObjectInIdentityMap, containsQuery, copyObject, copyObject, doesObjectExist, dontLogMessages, executeNonSelectingCall, executeNonSelectingSQL, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeQuery, executeSelectingCall, executeSQL, getActiveSession, getActiveUnitOfWork, getAllFromIdentityMap, getAllFromIdentityMap, getCacheSynchronizationManager, getCommandManager, getDescriptor, getDescriptor, getDescriptors, getEventManager, getExceptionHandler, getExternalTransactionController, getFromIdentityMap, getFromIdentityMap, getFromIdentityMap, getFromIdentityMap, getIntegrityChecker, getLog, getLogin, getName, getNextSequenceNumberValue, getProfiler, getProject, getProperties, getProperty, getQueries, getQuery, getSessionLog, getWriteLockValue, getWriteLockValue, handleException, hasCacheSynchronizationManager, hasDescriptor, hasExceptionHandler, hasExternalTransactionController, initializeAllIdentityMaps, initializeIdentityMap, initializeIdentityMaps, isClientSession, isConnected, isDatabaseSession, isDistributedSession, isInProfile, isProxySession, isRemoteSession, isServerSession, isSessionBroker, isUnitOfWork, keyFromObject, log, logDebug, logDebug, logException, logMessage, logMessage, logMessages, printIdentityMap, printIdentityMaps, putInIdentityMap, putInIdentityMap, putInIdentityMap, readAllObjects, readAllObjects, readAllObjects, readAllObjects, readObject, readObject, readObject, readObject, readObject, refreshObject, release, removeFromIdentityMap, removeFromIdentityMap, removeProperty, removeQuery, setCacheSynchronizationManager, setCommandManager, setExceptionHandler, setIntegrityChecker, setLog, setName, setProfiler, setProperty, setSessionLog, setShouldLogMessages, shouldLogMessages, updateWriteLockValue, updateWriteLockValue, usesExternalTransactionController, validateCache

Method Detail

addDescriptor

public void addDescriptor(Descriptor 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 dependant on inheritice and references unless the addDescriptors method is used.

See Also:

addDescriptors(Vector), addDescriptors(Project)

addDescriptors

public void addDescriptors(java.util.Vector 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 TopLink can resolve the dependancies between the descriptors and perform initialization optimially.

addDescriptors

public 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

public void beginTransaction()
                      throws DatabaseException

PUBLIC: Begin a transaction on the database. This allows a group of database modification to be commited 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, TopLink 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

public void commitTransaction()
                       throws DatabaseException

PUBLIC: Commit the active database transaction. This allows a group of database modification to be commited 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, TopLink 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

public 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 erros.

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.

deleteAllObjects

public void deleteAllObjects(java.util.Vector 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 erros.

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

public 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

public 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

public 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 aquired.

login

public 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

public 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 withint the login definition after login.

Throws:

DatabaseException

login

public 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 withint the login definition after login.

Throws:

DatabaseException

logout

public void logout()
            throws DatabaseException

PUBLIC: Disconnect from the database.

Throws:

TopLinkException - 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

public 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 pessimisticly 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, lockMode)

refreshAndLockObject

public 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 pessimisticly locked on the database for the duration of the transaction.

Lock Modes: ObjectLevelReadQuery.NO_LOCK, LOCK, LOCK_NOWAIT

rollbackTransaction

public void rollbackTransaction()
                         throws DatabaseException

PUBLIC: Rollback the active database transaction. This allows a group of database modification to be commited 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, TopLink 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

public void setExternalTransactionController(ExternalTransactionController etc)

PUBLIC: Used for JTS integration. If your application requires to have JTS control transactions instead of TopLink an external transaction controler must be specified. TopLink provides JTS controlers for JTS 1.0 and Weblogic's JTS.

Specified by:

setExternalTransactionController in interface Session

See Also:

JTSExternalTransactionController

setLogin

public void setLogin(DatabaseLogin login)

PUBLIC: Set the login.

updateObject

public 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

public 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 commited as a unit. The objects will be commited through a single transactions.

Throws:

DatabaseException - if an error occurs on the database, these include constraint violations, security violations and general database erros.

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.

writeAllObjects

public void writeAllObjects(java.util.Vector 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 commited as a unit. The objects will be commited through a single transactions.

Throws:

DatabaseException - if an error occurs on the database, these include constraint violations, security violations and general database erros.

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

public 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)