org.eclipse.persistence.sessions.factories
Class SessionFactory

Helper class to simplify the development and generation of code that accesses
TopLink through the SessionManager (sessions config XML).
Responsibilities:

Lookup of a session by name using default or provided sessions config location

Support lookup of active UnitOfWork and Session in JTA environments

Hot/Re-deployment handling of applications

Detachment helpers to simplify usage within a local session bean

Basic usage example:
SessionFactory = sessionFactory = new SessionFactory("session-name");
...
public List read(Vector args) {
Session session = sessionFactory.acquireSession();
List results = (List) session.executeQuery("query-name", MyClass.class, args);
session.release();
return results;
}
public void write(MyClass detachedInstance) {
UnitOfWork uow = sessionFactory.acquireUnitOfWork();
MyClass workingCopy = (MyClass) uow.readObject(detachedInstance);
if (workingCopy == null) {
throw new MyException("Cannot write changes. Object does not exist");
}
uow.deepMergeClone(detachedInstance);
uow.commit();
}
Detachment: The detach helper methods are provided to assist with the
construction of applications. This helper class was designed for use within
session beans (SB) and in the case of local SBs the objects returned are not
serialized. Since EclipseLink's default behavior is to return the shared instance
from the cache and rely on developers to only modify instances within a
UnitOfWork this may be an issue. The client to the local session bean may
try to modify the instance and thus corrupt the cache. By detaching the object
the client to the session bean gets its own isolated copy that it can freely
modify. This provides the same functionality as with a remote session bean
and allows the developer the choice in how/when objects are detached.
Note: The above code example shows how a detached instance can have
changes made to it persisted through use of the UnitOfWork merge API.

getSharedSession(boolean login,
boolean refresh)
Used in place of getSharedSession() when the calling application needs
access to the session prior to login or it wishes to force the session
configuration to be re-loaded an applied.

SessionFactory

getSessionName

public java.lang.String getSessionName()

getSessionXMLPath

public java.lang.String getSessionXMLPath()

getClassLoader

protected java.lang.ClassLoader getClassLoader()

The class-loader returned form this call will be used when loading the
EclipseLink configuration. By default this is the current thread's loader.
If this is not the case users can subclass this session factory and
override this method to provide a different loader.

getSharedSession

Used in place of getSharedSession() when the calling application needs
access to the session prior to login or it wishes to force the session
configuration to be re-loaded an applied. This also makes use of the
current class-loader return from getClassLoader() and a SessionManager
class-loader check to see if the application was loaded by another
class-loader and is should this be refreshed as the application has been
hot deployed.

acquireSession

Returns the Session active for this specified helper. If the EclipseLink
session does not have an external transaction controller or there is
not an active JTA transaction then a newly acquire client session is
returned on each call.
This method also properly handles acquire a client session from a broker
as well as returning the shared session in the case it is a database
session.

acquireUnitOfWork

Looks up the active UnitOfWork using either the global JTA TX or acquires
a new one from the active session. THis method should be used if a session
has already been acquired.

detach

public java.lang.Object detach(java.lang.Object entity)

Build a detached copy using a one-off UnitOfWork.
This simulates creation of a copy through serialization when using a
remote session bean if this copy process is not done the user of this
helper would return the shared copy from the cache that should not be
modified. These detachment methods *MUST* be used for local session
beans where the returned objects can be modified by the client.

Parameters:

entity - an existing persistent entity

Returns:

a copy of the entity for use in a local client that may make changes to it