org.qi4j.api.unitofwork
Interface UnitOfWork

All Superinterfaces:

MetaInfoHolder

public interface UnitOfWork
extends MetaInfoHolder

All operations on entities goes through an UnitOfWork.

A UnitOfWork allows you to access Entities and work with them. All modifications to Entities are recorded by the UnitOfWork, and at the end they may be sent to the underlying EntityStore by calling complete(). If the UoW was read-only you may instead simply discard() it.

A UoW differs from a traditional Transaction in the sense that it is not tied at all to the underlying storage resource. Because of this there is no timeout on a UoW. It can be very short or very long. Another difference is that if a call to complete() fails, and the cause is validation errors in the Entities of the UoW, then these can be corrected and the UoW retried. By contrast, when a Transaction commit fails, then the whole transaction has to be done from the beginning again.

A UoW can be associated with a Usecase. A Usecase describes the metainformation about the process to be performed by the UoW.

If a code block that uses a UoW throws an exception you need to ensure that this is handled properly, and that the UoW is closed before returning. Because discard() is a no-op if the UoW is closed, we therefore recommend the following template to be used:

     UnitOfWork uow = uowf.newUnitOfWork();
     try
     {
         ...
         uow.complete();
     } finally
     {
         uow.discard();
     }
 

This ensures that in the happy case the UoW is completed, and if any exception is thrown the UoW is discarded. After the UoW has completed the discard() method doesn't do anything, and so has no effect. You can choose to either add catch blocks for any exceptions, including exceptions from complete(), or skip them.

Method Summary

void	addUnitOfWorkCallback(UnitOfWorkCallback callback) Register a callback.
void	complete() Complete this UnitOfWork.
long	currentTime()
void	discard() Discard thie UnitOfWork.
<T> T	get(java.lang.Class<T> type, java.lang.String identity) Find an Entity of the given mixin type with the give identity.
<T> T	get(T entity) If you have a reference to an Entity from another UnitOfWork and want to create a reference to it in this UnitOfWork, then call this method.
boolean	isOpen() Check if the UnitOfWork is open.
boolean	isPaused() Check if the UnitOfWork is paused.
<T> T	newEntity(java.lang.Class<T> type) Create a new Entity which implements the given mixin type.
<T> T	newEntity(java.lang.Class<T> type, java.lang.String identity) Create a new Entity which implements the given mixin type.
<T> EntityBuilder<T>	newEntityBuilder(java.lang.Class<T> type) Create a new EntityBuilder for an EntityComposite which implements the given mixin type.
<T> EntityBuilder<T>	newEntityBuilder(java.lang.Class<T> type, java.lang.String identity) Create a new EntityBuilder for an EntityComposite which implements the given mixin type.
<T> Query<T>	newQuery(QueryBuilder<T> queryBuilder)
void	pause() Pauses this UnitOfWork.
void	remove(java.lang.Object entity) Remove the given Entity.
void	removeUnitOfWorkCallback(UnitOfWorkCallback callback) Unregister a callback.
void	resume() Resumes this UnitOfWork to again become the current UnitOfWork.
void	setMetaInfo(java.lang.Object metaInfo)
UnitOfWorkFactory	unitOfWorkFactory() Get the UnitOfWorkFactory that this UnitOfWork was created from.
Usecase	usecase() Get the Usecase for this UnitOfWork

Methods inherited from interface org.qi4j.api.structure.MetaInfoHolder

metaInfo

Method Detail

unitOfWorkFactory

UnitOfWorkFactory unitOfWorkFactory()

Get the UnitOfWorkFactory that this UnitOfWork was created from.

Returns:

The UnitOfWorkFactory instance that was used to create this UnitOfWork.

currentTime

long currentTime()

usecase

Usecase usecase()

Get the Usecase for this UnitOfWork

Returns:

the Usecase

setMetaInfo

void setMetaInfo(java.lang.Object metaInfo)

newQuery

<T> Query<T> newQuery(QueryBuilder<T> queryBuilder)

newEntity

<T> T newEntity(java.lang.Class<T> type)
            throws EntityTypeNotFoundException,
                   LifecycleException

Create a new Entity which implements the given mixin type. An EntityComposite will be chosen according to what has been registered and the visibility rules for Modules and Layers will be considered. If several EntityComposites implement the type then an AmbiguousTypeException will be thrown.

The identity of the Entity will be generated by the IdentityGenerator of the Module of the EntityComposite.

Parameters:

type - the mixin type that the EntityComposite must implement

Returns:

a new Entity

Throws:

NoSuchEntityException - if no EntityComposite type of the given mixin type has been registered

LifecycleException - if the entity cannot be created

EntityTypeNotFoundException

newEntity

<T> T newEntity(java.lang.Class<T> type,
                java.lang.String identity)
            throws EntityTypeNotFoundException,
                   LifecycleException

Create a new Entity which implements the given mixin type. An EntityComposite will be chosen according to what has been registered and the visibility rules for Modules and Layers will be considered. If several EntityComposites implement the type then an AmbiguousTypeException will be thrown.

Parameters:

type - the mixin type that the EntityComposite must implement

identity - the identity of the new Entity

Returns:

a new Entity

Throws:

NoSuchEntityException - if no EntityComposite type of the given mixin type has been registered

LifecycleException - if the entity cannot be created

EntityTypeNotFoundException

newEntityBuilder

<T> EntityBuilder<T> newEntityBuilder(java.lang.Class<T> type)
                                  throws EntityTypeNotFoundException

Create a new EntityBuilder for an EntityComposite which implements the given mixin type. An EntityComposite will be chosen according to what has been registered and the visibility rules for Modules and Layers will be considered. If several EntityComposites implement the type then an AmbiguousTypeException will be thrown.

Parameters:

type - the mixin type that the EntityComposite must implement

Returns:

a new Entity

Throws:

NoSuchEntityException - if no EntityComposite type of the given mixin type has been registered

LifecycleException

EntityTypeNotFoundException

newEntityBuilder

<T> EntityBuilder<T> newEntityBuilder(java.lang.Class<T> type,
                                      java.lang.String identity)
                                  throws EntityTypeNotFoundException

Create a new EntityBuilder for an EntityComposite which implements the given mixin type. An EntityComposite will be chosen according to what has been registered and the visibility rules for Modules and Layers will be considered. If several mixins implement the type then an AmbiguousTypeException will be thrown.

Parameters:

type - the mixin type that the EntityComposite must implement

identity - the identity of the new Entity

Returns:

a new Entity

Throws:

NoSuchEntityException - if no EntityComposite type of the given mixin type has been registered

LifecycleException

EntityTypeNotFoundException

get

<T> T get(java.lang.Class<T> type,
          java.lang.String identity)
      throws EntityTypeNotFoundException,
             NoSuchEntityException

Find an Entity of the given mixin type with the give identity. This method verifies that it exists by asking the underlying EntityStore.

Parameters:

type - of the entity

identity - of the entity

Returns:

the entity

Throws:

EntityTypeNotFoundException - if no entity type could be found

NoSuchEntityException

get

<T> T get(T entity)
      throws EntityTypeNotFoundException

If you have a reference to an Entity from another UnitOfWork and want to create a reference to it in this UnitOfWork, then call this method.

Parameters:

entity - the Entity to be dereferenced

Returns:

an Entity from this UnitOfWork

Throws:

EntityTypeNotFoundException - if no entity type could be found

remove

void remove(java.lang.Object entity)
            throws LifecycleException

Remove the given Entity.

Parameters:

entity - the Entity to be removed.

Throws:

LifecycleException - if the entity could not be removed

complete

void complete()
              throws UnitOfWorkCompletionException,
                     ConcurrentEntityModificationException

Complete this UnitOfWork. This will send all the changes down to the underlying EntityStore's.

Throws:

UnitOfWorkCompletionException - if the UnitOfWork could not be completed

ConcurrentEntityModificationException - if entities have been modified by others

discard

void discard()

Discard thie UnitOfWork. Use this if a failure occurs that you cannot handle, or if the usecase was of a read-only character. This is a no-op of the UnitOfWork is already closed.

isOpen

boolean isOpen()

Check if the UnitOfWork is open. It is closed after either complete() or discard() methods have been called successfully.

Returns:

true if the UnitOfWork is open.

isPaused

boolean isPaused()

Check if the UnitOfWork is paused. It is not paused after it has been create through the UnitOfWorkFactory, and it can be paused by calling pause() and then resumed by calling resume().

Returns:

true if this UnitOfWork has been paused.

pause

void pause()

Pauses this UnitOfWork.

Calling this method will cause the underlying UnitOfWork to become the current UnitOfWork until the the resume() method is called. It is the client's responsibility not to drop the reference to this UnitOfWork while being paused.

resume

void resume()

Resumes this UnitOfWork to again become the current UnitOfWork.

addUnitOfWorkCallback

void addUnitOfWorkCallback(UnitOfWorkCallback callback)

Register a callback. Callbacks are invoked when the UnitOfWork is completed or discarded.

Parameters:

callback - a callback to be registered with this UnitOfWork

removeUnitOfWorkCallback

void removeUnitOfWorkCallback(UnitOfWorkCallback callback)

Unregister a callback. Callbacks are invoked when the UnitOfWork is completed or discarded.

Parameters:

callback - a callback to be unregistered with this UnitOfWork