de.xima.fc.interfaces.plugin.param.entities

Interface IPluginEmManager

All Known Implementing Classes:

PluginEmManager

public interface IPluginEmManager

A manager for EntityManagers that can be used by an entities plugin. This manager takes care of creating a new entity manager when required and reuses an existing one if possible. It also provides a method to create an IBaseEntityContext that you can use with the DAO API provided by FORMCYCLE (eg IAbstractDao).

If you are within the context of the FORMCYCLE backend, the entity manager will be closed automatically. Otherwise, you are responsible for closing it yourself, such as with a try-finally statement. "Within the backend" means that your code is run in response to an HTTP request to an URL that starts with /formcycle/ui, /formcycle/designer, /formcycle/inbox, or /formcycle/portal (with /formcycle replace by the context path where FORMCYCLE is running). Conversely, you are not within a backend context when the user opens any other URL, such as /formcycle/form/provide. Note that there are some plugins that run outside a backend context, such as form pre-render plugins.

If you only use newEntityContext(), you can always wrap this call in a try-with statement. Then, if you are within a backend context, the entity manager is created only once for each request and closed when the request ends. Outside a backend context, the entity manager is closed at the end of the try-with statement. To illustrate:

 try (final IBaseEntityContext ec = pluginEmManager.newEntityContext()) {
   // use entity context with some DAO
   // this fetches all existing MyEntity
   new AbstractDao(MyEntity.class) {}.all(null, new QueryCriteriaManager());
 }
 

To get an implementation of this interface, use the method IPluginEntitiesParams.getPluginEmManager() on the parameters that are passed to the entities plugin.

Author:

XIMA MEDIA GmbH

Method Summary

Modifier and Type	Method and Description
void	beginTransaction() Begins a new transation, if no transaction is currently active.
void	closeEntityManager() If the EntityManager associated with the current thread is open, close it.
void	commit() If a transaction is currently active, commits it.
javax.persistence.EntityManager	getEntityManager()
javax.persistence.EntityManager	getOrCreateEntityManager()
boolean	isEntityDetached(Object entity) Checks whether a given entity is currently detached, ie not managed by the entity manager.
boolean	isTransactionActive()
de.xima.cmn.dao.interfaces.IBaseEntityContext	newEntityContext() This creates a new IBaseEntityContext you can use to read or write plugin entities.
void	rollback() If a transaction is currently active, performs a rollback of that transaction.

Method Detail

beginTransaction

void beginTransaction()

Begins a new transation, if no transaction is currently active. Creates a new entity manager if no EntityManager is associated with the current thread.

closeEntityManager

void closeEntityManager()

If the EntityManager associated with the current thread is open, close it. Otherwise, does nothing.

commit

void commit()

If a transaction is currently active, commits it. Otherwise, does nothing.

getEntityManager

javax.persistence.EntityManager getEntityManager()

Returns:

The EntityManager associated with the current thread. If no entity manager exists yet, returns null.

getOrCreateEntityManager

javax.persistence.EntityManager getOrCreateEntityManager()

Returns:

The EntityManager associated with the current thread. If no entity manager exists yet, creates a new one.

isEntityDetached

boolean isEntityDetached(Object entity)

Checks whether a given entity is currently detached, ie not managed by the entity manager.

Parameters:

entity - An entity to check.

Returns:

Whether the given entity is currently managed by the entity manager.

isTransactionActive

boolean isTransactionActive()

Returns:

Whether a transaction is currently active.

newEntityContext

de.xima.cmn.dao.interfaces.IBaseEntityContext newEntityContext()

This creates a new IBaseEntityContext you can use to read or write plugin entities. Make sure you always wrap this call in a try-with statement to ensure it is properly closed. This will take care of closing the underlying EntityManager at the appropriate time. Note that when you are within a backend context (eg a backend configuration menu or a portal page), the underlying entity manager is created only once for each HTTP request and reused during the request.

You should use this method as follows:

 try (final IBaseEntityContext ec = pluginEmManager.newEntityContext()) {
   // use entity context with some DAO
   // this fetches all existing MyEntity
   new AbstractDao(MyEntity.class) {}.all(null, new QueryCriteriaManager());
 }
 

Returns:

A new IBaseEntityContext that can be used with the DAO API of FORMCYCLE.

rollback

void rollback()

If a transaction is currently active, performs a rollback of that transaction. Otherwise, does nothing.