EclipseLink Core 4.0.2 · org.eclipse.persistence.sessions.factories.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.

Modifier and Type	Field and Description
private String	sessionName
private String	sessionXMLPath Location for the sessions.xml file.

Constructor Summary

Access	Constructor and Description
public	SessionFactory(String - resource path of the sessions configuration xml. sessionsXMLPath, String - name of the session to use. sessionName) Constructor for creating a new EclipseLinkSessionHelper instance.
public	SessionFactory(String sessionName)

Method Summary

Modifier and Type	Method and Description
public Session	acquireSession() Returns the Session active for this specified helper.
public UnitOfWork	acquireUnitOfWork() Looks up the active UnitOfWork using either the global JTA TX or acquires a new one from the active session.
public UnitOfWork	acquireUnitOfWork(Session session) Looks up the active UnitOfWork using either the global JTA TX or acquires a new one from the active session.
public Object	Returns: a copy of the entity for use in a local client that may make changes to it detach(Object an existing persistent entity entity) Build a detached copy using a one-off UnitOfWork.
public Collection<E>	detach(Collection<E> entities)
protected ClassLoader	getClassLoader() The class-loader returned form this call will be used when loading the EclipseLink configuration.
public String	getSessionName()
public String	getSessionXMLPath()
public DatabaseSession	getSharedSession() Helper method that looks up the singleton session and ensure that if the application has been hot-deployed it gets a fresh version of the server.
public DatabaseSession	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.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

sessionName	back to summary
private String sessionName

sessionXMLPath	back to summary
private String sessionXMLPath Location for the sessions.xml file. The default here is the most common. If none is provided then EclipseLink's default locations of 'sessions.xml' and 'META-INF/sessions.xml' will be tried.

Constructor Detail

SessionFactory	back to summary
public SessionFactory(String sessionsXMLPath, String sessionName) Constructor for creating a new EclipseLinkSessionHelper instance. Parameters sessionsXMLPath:String - resource path of the sessions configuration xml. sessionName:String - name of the session to use.

SessionFactory

back to summary

public SessionFactory(String sessionsXMLPath, String sessionName)

Constructor for creating a new EclipseLinkSessionHelper instance.

Parameters

sessionsXMLPath:String: - resource path of the sessions configuration xml.
sessionName:String: - name of the session to use.

SessionFactory	back to summary
public SessionFactory(String sessionName)

Method Detail

acquireSession	back to summary
public Session 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.

acquireSession

back to summary

public Session 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	back to summary
public UnitOfWork acquireUnitOfWork() Looks up the active UnitOfWork using either the global JTA TX or acquires a new one from the active session.

acquireUnitOfWork	back to summary
public UnitOfWork acquireUnitOfWork(Session session) 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	back to summary
public Object detach(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:Object an existing persistent entity Returns:Object a copy of the entity for use in a local client that may make changes to it

detach

back to summary

public Object detach(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:Object: an existing persistent entity

Returns:Object

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

detach	back to summary
public Collection<E> detach(Collection<E> entities)

getClassLoader	back to summary
protected 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.

getSessionName	back to summary
public String getSessionName()

getSessionXMLPath	back to summary
public String getSessionXMLPath()

getSharedSession	back to summary
public DatabaseSession getSharedSession() Helper method that looks up the singleton session and ensure that if the application has been hot-deployed it gets a fresh version of the server.

getSharedSession	back to summary
public DatabaseSession 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. 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.

getSharedSession

back to summary

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

public Class SessionFactory

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail