Trigger (Carbonado 1.2.3 API)

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
+

Nested Classes
Modifier and Type	Class and Description
`static class`	`Trigger.Abort`

+ +

+ + +
Constructor Summary
+ + + + + + + + +
Constructors
Constructor and Description
Trigger()
+

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
    +
  +
+

Class Trigger<S>

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Trigger

Method Detail

beforeInsert

beforeInsert

beforeTryInsert

beforeTryInsert

afterInsert

afterTryInsert

failedInsert

beforeUpdate

beforeUpdate

beforeTryUpdate

beforeTryUpdate

afterUpdate

afterTryUpdate

failedUpdate

beforeDelete

beforeDelete

beforeTryDelete

beforeTryDelete

afterDelete

afterTryDelete

failedDelete

afterLoad

abortTry