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 java.lang.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

Nested Classes

Modifier and Type	Class and Description
static class	Trigger.Abort

Constructor Summary

Constructors

Constructor and Description
Trigger()

Method Summary

Methods

Modifier and Type	Method and Description
protected Trigger.Abort	abortTry() Call to quickly abort a "try" operation, returning false to the caller.
void	afterDelete(S storable, java.lang.Object state) Called right after a storable has been successfully deleted.
void	afterInsert(S storable, java.lang.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, java.lang.Object state) Called right after a storable has been successfully deleted via tryDelete.
void	afterTryInsert(S storable, java.lang.Object state) Called right after a storable has been successfully inserted via tryInsert.
void	afterTryUpdate(S storable, java.lang.Object state) Called right after a storable has been successfully updated via tryUpdate.
void	afterUpdate(S storable, java.lang.Object state) Called right after a storable has been successfully updated.
java.lang.Object	beforeDelete(S storable) Called before a storable is to be deleted.
java.lang.Object	beforeDelete(Transaction txn, S storable) Called before a storable is to be deleted.
java.lang.Object	beforeInsert(S storable) Called before a storable is to be inserted.
java.lang.Object	beforeInsert(Transaction txn, S storable) Called before a storable is to be inserted.
java.lang.Object	beforeTryDelete(S storable) Called before a storable is to be deleted via tryDelete.
java.lang.Object	beforeTryDelete(Transaction txn, S storable) Called before a storable is to be deleted via tryDelete.
java.lang.Object	beforeTryInsert(S storable) Called before a storable is to be inserted via tryInsert.
java.lang.Object	beforeTryInsert(Transaction txn, S storable) Called before a storable is to be inserted via tryInsert.
java.lang.Object	beforeTryUpdate(S storable) Called before a storable is to be updated via tryUpdate.
java.lang.Object	beforeTryUpdate(Transaction txn, S storable) Called before a storable is to be updated via tryUpdate.
java.lang.Object	beforeUpdate(S storable) Called before a storable is to be updated.
java.lang.Object	beforeUpdate(Transaction txn, S storable) Called before a storable is to be updated.
void	failedDelete(S storable, java.lang.Object state) Called when an delete operation failed because the record was missing or an exception was thrown.
void	failedInsert(S storable, java.lang.Object state) Called when an insert operation failed due to a unique constraint violation or an exception was thrown.
void	failedUpdate(S storable, java.lang.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 java.lang.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

beforeInsert

public java.lang.Object beforeInsert(Transaction txn,
                            S storable)
                              throws PersistException

Called before a storable is to be inserted. The default implementation simply calls beforeInsert(Object). Only override if access to the transaction is required.

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:

txn - nested transaction which trigger runs in

storable - storable before being inserted

Returns:

arbitrary state object, passed to afterInsert or failedInsert method

Throws:

PersistException

beforeTryInsert

public java.lang.Object beforeTryInsert(S storable)
                                 throws PersistException

Called before a storable is to be inserted via tryInsert. The default implementation simply calls beforeInsert(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 before being inserted

Returns:

arbitrary state object, passed to afterTryInsert or failedInsert method

Throws:

PersistException

See Also:

abortTry()

beforeTryInsert

public java.lang.Object beforeTryInsert(Transaction txn,
                               S storable)
                                 throws PersistException

Called before a storable is to be inserted via tryInsert. The default implementation simply calls beforeTryInsert(Object). Only override if trigger needs access to the transaction and 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:

txn - nested transaction which trigger runs in

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,
               java.lang.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,
                  java.lang.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,
                java.lang.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 java.lang.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

beforeUpdate

public java.lang.Object beforeUpdate(Transaction txn,
                            S storable)
                              throws PersistException

Called before a storable is to be updated. The default implementation simply calls beforeUpdate(Object). Only override if access to the transaction is required.

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:

txn - nested transaction which trigger runs in

storable - storable before being updated

Returns:

arbitrary state object, passed to afterUpdate or failedUpdate method

Throws:

PersistException

beforeTryUpdate

public java.lang.Object beforeTryUpdate(S storable)
                                 throws PersistException

Called before a storable is to be updated via tryUpdate. The default implementation simply calls beforeUpdate(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 before being updated

Returns:

arbitrary state object, passed to afterTryUpdate or failedUpdate method

Throws:

PersistException

See Also:

abortTry()

beforeTryUpdate

public java.lang.Object beforeTryUpdate(Transaction txn,
                               S storable)
                                 throws PersistException

Called before a storable is to be updated via tryUpdate. The default implementation simply calls beforeTryUpdate(Object). Only override if trigger needs access to the transaction and 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:

txn - nested transaction which trigger runs in

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,
               java.lang.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,
                  java.lang.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,
                java.lang.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 java.lang.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

beforeDelete

public java.lang.Object beforeDelete(Transaction txn,
                            S storable)
                              throws PersistException

Called before a storable is to be deleted. The default implementation simply calls beforeDelete(Object). Only override if access to the transaction is required.

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:

txn - nested transaction which trigger runs in

storable - storable before being deleted

Returns:

arbitrary state object, passed to afterDelete or failedDelete method

Throws:

PersistException

beforeTryDelete

public java.lang.Object beforeTryDelete(S storable)
                                 throws PersistException

Called before a storable is to be deleted via tryDelete. The default implementation simply calls beforeDelete(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 before being deleted

Returns:

arbitrary state object, passed to afterTryDelete or failedDelete method

Throws:

PersistException

See Also:

abortTry()

beforeTryDelete

public java.lang.Object beforeTryDelete(Transaction txn,
                               S storable)
                                 throws PersistException

Called before a storable is to be deleted via tryDelete. The default implementation simply calls beforeTryDelete(Object). Only override if trigger needs access to the transaction and 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:

txn - nested transaction which trigger runs in

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,
               java.lang.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,
                  java.lang.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,
                java.lang.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