org.axonframework.unitofwork
Interface UnitOfWork

All Known Implementing Classes:

DefaultUnitOfWork, DisruptorUnitOfWork, NestableUnitOfWork

public interface UnitOfWork

This class represents a UnitOfWork in which modifications are made to aggregates. A typical UnitOfWork scope is the execution of a command. A UnitOfWork may be used to prevent individual events from being published before a number of aggregates has been processed. It also allows repositories to manage resources, such as locks, over an entire transaction. Locks, for example, will only be released when the UnitOfWork is either committed or rolled back.

The current UnitOfWork can be obtained using CurrentUnitOfWork.get().

Since:

0.6

Author:

Allard Buijze

Method Summary

void	attachInheritedResources(UnitOfWork inheritingUnitOfWork) Attach all inherited resources to the given unitOfWork.
void	attachResource(String name, Object resource) Attaches the given resource to this Unit of Work under the given name.
void	attachResource(String name, Object resource, boolean inherited) Attaches the given resource to this Unit of Work under the given name.
void	commit() Commits the UnitOfWork.
<T> T	getResource(String name) Returns the resource previously attached under given name, or null if no such resource is available.
boolean	isStarted() Indicates whether this UnitOfWork is started.
boolean	isTransactional() Indicates whether this UnitOfWork is bound to a transaction.
void	publishEvent(EventMessage<?> event, EventBus eventBus) Request to publish the given event on the given eventBus.
<T extends AggregateRoot> T	registerAggregate(T aggregateRoot, EventBus eventBus, SaveAggregateCallback<T> saveAggregateCallback) Register an aggregate with this UnitOfWork.
void	registerListener(UnitOfWorkListener listener) Register a listener that listens to state changes in this UnitOfWork.
void	rollback() Clear the UnitOfWork of any buffered changes.
void	rollback(Throwable cause) Clear the UnitOfWork of any buffered changes.
void	start() Starts the current unit of work, preparing it for aggregate registration.

Method Detail

commit

void commit()

Commits the UnitOfWork. All registered aggregates that have not been registered as stored are saved in their respective repositories, buffered events are sent to their respective event bus, and all registered UnitOfWorkListeners are notified.

After the commit (successful or not), the UnitOfWork is unregistered from the CurrentUnitOfWork and has cleaned up all resources it occupied. This effectively means that a rollback is done if Unit Of Work failed to commit.

Throws:

IllegalStateException - if the UnitOfWork wasn't started

rollback

void rollback()

Clear the UnitOfWork of any buffered changes. All buffered events and registered aggregates are discarded and registered UnitOfWorkListeners are notified.

If the rollback is a result of an exception, consider using rollback(Throwable) instead.

rollback

void rollback(Throwable cause)

Clear the UnitOfWork of any buffered changes. All buffered events and registered aggregates are discarded and registered UnitOfWorkListeners are notified.

Parameters:

cause - The cause of the rollback. May be null.

Throws:

IllegalStateException - if the UnitOfWork wasn't started

start

void start()

Starts the current unit of work, preparing it for aggregate registration. The UnitOfWork instance is registered with the CurrentUnitOfWork.

isStarted

boolean isStarted()

Indicates whether this UnitOfWork is started. It is started when the start() method has been called, and if the UnitOfWork has not been committed or rolled back.

Returns:

true if this UnitOfWork is started, false otherwise.

isTransactional

boolean isTransactional()

Indicates whether this UnitOfWork is bound to a transaction.

Returns:

true if this unit of work is bound to a transaction, otherwise false

registerListener

void registerListener(UnitOfWorkListener listener)

Register a listener that listens to state changes in this UnitOfWork. This typically allows components to clean up resources, such as locks, when a UnitOfWork is committed or rolled back. If a UnitOfWork is partially committed, only the listeners bound to one of the committed aggregates is notified.

Parameters:

listener - The listener to notify when the UnitOfWork's state changes.

registerAggregate

<T extends AggregateRoot> T registerAggregate(T aggregateRoot,
                                              EventBus eventBus,
                                              SaveAggregateCallback<T> saveAggregateCallback)

Register an aggregate with this UnitOfWork. These aggregates will be saved (at the latest) when the UnitOfWork is committed. This method returns the instance of the aggregate root that should be used as part of the processing in this Unit Of Work.

If an aggregate of the same type and with the same identifier has already been registered, one of two things may happen, depending on the actual implementation:

• the instance that has already been registered is returned. In which case the given saveAggregateCallback is ignored.
• an IllegalStateException is thrown to indicate an illegal attempt to register a duplicate

.

Type Parameters:

T - the type of aggregate to register

Parameters:

aggregateRoot - The aggregate root to register in the UnitOfWork

eventBus - The event bus on which Events generated by this aggregate must be published

saveAggregateCallback - The callback that is invoked when the UnitOfWork wants to store the registered aggregate

Returns:

The actual aggregate instance to use

Throws:

IllegalStateException - if this Unit Of Work does not support registrations of aggregates with identical type and identifier

publishEvent

void publishEvent(EventMessage<?> event,
                  EventBus eventBus)

Request to publish the given event on the given eventBus. The UnitOfWork may either publish immediately, or buffer the events until the UnitOfWork is committed.

Parameters:

event - The event to be published on the event bus

eventBus - The event bus on which to publish the event

attachResource

void attachResource(String name,
                    Object resource)

Attaches the given resource to this Unit of Work under the given name. The attached resource is not inherited by any nested Unit of Work (see attachResource(String, Object, boolean).

If a resource was already attached under this name, it is overwritten.

By convention, resources should be attached using the fully Qualified name of their type (or main interface). For example, a JDBC Connection should be attached using the name "java.sql.Connection". When there is a requirement to distinguish between different resources of the same type, their name may differ from this convention.

Parameters:

name - The name under which to attach the resource

resource - The resource to attach

attachResource

void attachResource(String name,
                    Object resource,
                    boolean inherited)

Attaches the given resource to this Unit of Work under the given name. The attached resource is inherited as indicated. Inherited resources are automatically attached to a nested Unit of Work.

If a resource was already attached under this name, it is overwritten.

By convention, resources should be attached using the fully Qualified name of their type (or main interface). For example, a JDBC Connection should be attached using the name "java.sql.Connection". When there is a requirement to distinguish between different resources of the same type, their name may differ from this convention.

Parameters:

name - The name under which to attach the resource

resource - The resource to attach

inherited - Whether or not the resource may be inherited by a nested Unit of Work

getResource

<T> T getResource(String name)

Returns the resource previously attached under given name, or null if no such resource is available.

Type Parameters:

T - The type of resource

Parameters:

name - The name under which the resource was attached

Returns:

The resource attached under the given name, or null if no such resource is available.

attachInheritedResources

void attachInheritedResources(UnitOfWork inheritingUnitOfWork)

Attach all inherited resources to the given unitOfWork.

Parameters:

inheritingUnitOfWork - the Unit of Work inheriting the resources from this instance.