com.amazon.carbonado
Class Trigger<S>

java.lang.Object
  com.amazon.carbonado.Trigger<S>

Direct Known Subclasses:

ResyncCapability.Listener, TriggerManager

public abstract class Trigger<S>
extends Object

Callback mechanism to allow custom code to run when a storable is persisted. By default, the methods defined in this class do nothing. Subclass and override trigger conditions of interest, and then register it. Each overridden trigger method is called in the same transaction scope as the persist operation. Trigger implementations are encouraged to override the equals method, to prevent accidental double registration.

To ensure proper nesting, all "before" events are run in the opposite order that the trigger was registered. All "after" and "failed" events are run in the same order that the trigger was registered. In other words, the last added trigger is at the outermost nesting level.

Triggers always run within the same transaction as the triggering operation. The exact isolation level and update mode is outside the trigger's control. If an explicit isolation level or update mode is required, create a nested transaction within a trigger method. A trigger's nested transaction can also be defined to span the entire triggering operation. To do this, enter the transaction in the "before" method, but return the transaction object without exiting it. The "after" method is responsible for exiting the transaction. It extracts (or simply casts) the transaction from the state object passed into it. When creating spanning transactions like this, it is critical that the "failed" method be defined to properly exit the transaction upon failure.

Author:

Brian S O'Neill

Nested Class Summary

static class

Trigger.Abort

Constructor Summary

Trigger()

Method Summary

protected Trigger.Abort	abortTry() Call to quickly abort a "try" operation, returning false to the caller.
void	afterDelete(S storable, Object state) Called right after a storable has been successfully deleted.
void	afterInsert(S storable, Object state) Called right after a storable has been successfully inserted.
void	afterLoad(S storable) Called right after a storable has been successfully loaded or fetched.
void	afterTryDelete(S storable, Object state) Called right after a storable has been successfully deleted via tryDelete.
void	afterTryInsert(S storable, Object state) Called right after a storable has been successfully inserted via tryInsert.
void	afterTryUpdate(S storable, Object state) Called right after a storable has been successfully updated via tryUpdate.
void	afterUpdate(S storable, Object state) Called right after a storable has been successfully updated.
Object	beforeDelete(S storable) Called before a storable is to be deleted.
Object	beforeInsert(S storable) Called before a storable is to be inserted.
Object	beforeTryDelete(S storable) Called before a storable is to be deleted via tryDelete.
Object	beforeTryInsert(S storable) Called before a storable is to be inserted via tryInsert.
Object	beforeTryUpdate(S storable) Called before a storable is to be updated via tryUpdate.
Object	beforeUpdate(S storable) Called before a storable is to be updated.
void	failedDelete(S storable, Object state) Called when an delete operation failed because the record was missing or an exception was thrown.
void	failedInsert(S storable, Object state) Called when an insert operation failed due to a unique constraint violation or an exception was thrown.
void	failedUpdate(S storable, Object state) Called when an update operation failed because the record was missing or an exception was thrown.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Trigger

public Trigger()

Method Detail

beforeInsert

public Object beforeInsert(S storable)
                    throws PersistException

Called before a storable is to be inserted. The default implementation does nothing.

Any exception thrown by this method will cause the insert operation to rollback and all remaining triggers to not run. The exception is ultimately passed to the caller of the insert method.

Parameters:

storable - storable before being inserted

Returns:

arbitrary state object, passed to afterInsert or failedInsert method

Throws:

PersistException

beforeTryInsert

public Object beforeTryInsert(S storable)
                       throws PersistException

Called before a storable is to be inserted via tryInsert. The default implementation simply calls beforeInsert(S). Only override if trigger needs to distinguish between different insert variants.

Any exception thrown by this method will cause the tryInsert operation to rollback and all remaining triggers to not run. The exception is ultimately passed to the caller of the tryInsert method.

Parameters:

storable - storable before being inserted

Returns:

arbitrary state object, passed to afterTryInsert or failedInsert method

Throws:

PersistException

See Also:

abortTry()

afterInsert

public void afterInsert(S storable,
                        Object state)
                 throws PersistException

Called right after a storable has been successfully inserted. The default implementation does nothing.

Any exception thrown by this method will cause the insert operation to rollback and all remaining triggers to not run. The exception is ultimately passed to the caller of the insert method.

Parameters:

storable - storable after being inserted

state - object returned by beforeInsert method

Throws:

PersistException

afterTryInsert

public void afterTryInsert(S storable,
                           Object state)
                    throws PersistException

Called right after a storable has been successfully inserted via tryInsert. The default implementation simply calls afterInsert(S, java.lang.Object). Only override if trigger needs to distinguish between different insert variants.

Any exception thrown by this method will cause the tryInsert operation to rollback and all remaining triggers to not run. The exception is ultimately passed to the caller of the tryInsert method.

Parameters:

storable - storable after being inserted

state - object returned by beforeTryInsert method

Throws:

PersistException

See Also:

abortTry()

failedInsert

public void failedInsert(S storable,
                         Object state)

Called when an insert operation failed due to a unique constraint violation or an exception was thrown. The main purpose of this method is to allow any necessary clean-up to occur on the optional state object.

Any exception thrown by this method will be passed to the current thread's uncaught exception handler.

Parameters:

storable - storable which failed to be inserted

state - object returned by beforeInsert method, but it may be null

beforeUpdate

public Object beforeUpdate(S storable)
                    throws PersistException

Called before a storable is to be updated. The default implementation does nothing.

Any exception thrown by this method will cause the update operation to rollback and all remaining triggers to not run. The exception is ultimately passed to the caller of the update method.

Parameters:

storable - storable before being updated

Returns:

arbitrary state object, passed to afterUpdate or failedUpdate method

Throws:

PersistException

beforeTryUpdate

public Object beforeTryUpdate(S storable)
                       throws PersistException

Called before a storable is to be updated via tryUpdate. The default implementation simply calls beforeUpdate(S). Only override if trigger needs to distinguish between different update variants.

Any exception thrown by this method will cause the tryUpdate operation to rollback and all remaining triggers to not run. The exception is ultimately passed to the caller of the tryUpdate method.

Parameters:

storable - storable before being updated

Returns:

arbitrary state object, passed to afterTryUpdate or failedUpdate method

Throws:

PersistException

See Also:

abortTry()

afterUpdate

public void afterUpdate(S storable,
                        Object state)
                 throws PersistException

Called right after a storable has been successfully updated. The default implementation does nothing.

Any exception thrown by this method will cause the update operation to rollback and all remaining triggers to not run. The exception is ultimately passed to the caller of the update method.

Parameters:

storable - storable after being updated

state - optional object returned by beforeUpdate method

Throws:

PersistException

afterTryUpdate

public void afterTryUpdate(S storable,
                           Object state)
                    throws PersistException

Called right after a storable has been successfully updated via tryUpdate. The default implementation simply calls afterUpdate(S, java.lang.Object). Only override if trigger needs to distinguish between different update variants.

Any exception thrown by this method will cause the tryUpdate operation to rollback and all remaining triggers to not run. The exception is ultimately passed to the caller of the tryUpdate method.

Parameters:

storable - storable after being updated

state - object returned by beforeTryUpdate method

Throws:

PersistException

See Also:

abortTry()

failedUpdate

public void failedUpdate(S storable,
                         Object state)

Called when an update operation failed because the record was missing or an exception was thrown. The main purpose of this method is to allow any necessary clean-up to occur on the optional state object.

Any exception thrown by this method will be passed to the current thread's uncaught exception handler.

Parameters:

storable - storable which failed to be updated

state - optional object returned by beforeUpdate method, but it may be null

beforeDelete

public Object beforeDelete(S storable)
                    throws PersistException

Called before a storable is to be deleted. The default implementation does nothing.

Any exception thrown by this method will cause the delete operation to rollback and all remaining triggers to not run. The exception is ultimately passed to the caller of the delete method.

Parameters:

storable - storable before being deleted

Returns:

arbitrary state object, passed to afterDelete or failedDelete method

Throws:

PersistException

beforeTryDelete

public Object beforeTryDelete(S storable)
                       throws PersistException

Called before a storable is to be deleted via tryDelete. The default implementation simply calls beforeDelete(S). Only override if trigger needs to distinguish between different delete variants.

Any exception thrown by this method will cause the tryDelete operation to rollback and all remaining triggers to not run. The exception is ultimately passed to the caller of the tryDelete method.

Parameters:

storable - storable before being deleted

Returns:

arbitrary state object, passed to afterTryDelete or failedDelete method

Throws:

PersistException

See Also:

abortTry()

afterDelete

public void afterDelete(S storable,
                        Object state)
                 throws PersistException

Called right after a storable has been successfully deleted. The default implementation does nothing.

Any exception thrown by this method will cause the delete operation to rollback and all remaining triggers to not run. The exception is ultimately passed to the caller of the delete method.

Parameters:

storable - storable after being deleted

state - optional object returned by beforeDelete method

Throws:

PersistException

afterTryDelete

public void afterTryDelete(S storable,
                           Object state)
                    throws PersistException

Called right after a storable has been successfully deleted via tryDelete. The default implementation simply calls afterDelete(S, java.lang.Object). Only override if trigger needs to distinguish between different delete variants.

Any exception thrown by this method will cause the tryDelete operation to rollback and all remaining triggers to not run. The exception is ultimately passed to the caller of the tryDelete method.

Parameters:

storable - storable after being deleted

state - object returned by beforeTryDelete method

Throws:

PersistException

See Also:

abortTry()

failedDelete

public void failedDelete(S storable,
                         Object state)

Called when an delete operation failed because the record was missing or an exception was thrown. The main purpose of this method is to allow any necessary clean-up to occur on the optional state object.

Any exception thrown by this method will be passed to the current thread's uncaught exception handler.

Parameters:

storable - storable which failed to be deleted

state - optional object returned by beforeDelete method, but it may be null

afterLoad

public void afterLoad(S storable)
               throws FetchException

Called right after a storable has been successfully loaded or fetched. The default implementation does nothing.

Parameters:

storable - storable after being loaded or fetched

Throws:

FetchException

Since:

1.2

abortTry

protected Trigger.Abort abortTry()
                          throws Trigger.Abort

Call to quickly abort a "try" operation, returning false to the caller. This method should not be called by a non-try trigger method, since the caller gets thrown an exception with an incomplete stack trace.

This method never returns normally, but as a convenience, a return type is defined. The abort exception can be thrown by throw abortTry(), but the throw keyword is not needed.

Throws:

Trigger.Abort