Package com.sleepycat.je.trigger

This package defines the trigger classes used in JE.

See: Description

Package com.sleepycat.je.trigger Description

This package defines the trigger classes used in JE. Triggers provide a mechanism for automatically executing one or more application defined trigger methods whenever a certain type of operation is performed. The mechanism is automatic in that the method is invoked automatically by JE and not the application.

All the trigger methods are, in the terminology generally associated with RDBMS triggers, after triggers. An after trigger method is only invoked after the successful completion of the associated operation. It is not invoked if the operation associated with the trigger method fails.

The trigger interfaces are organized so that the application can easily choose to implement the minimal set of methods that meet their needs.

Each of the interfaces described above defines a set of trigger methods that must all work together to achieve a common purpose. The application must typically supply non-null implementations for all the methods in an interface or the application will likely be incomplete.

Configuring Triggers

Triggers are configured via the get/set methods defined on DatabaseConfig. They are stored persistently in the database. If the database is replicated, the association is replicated at each node, so that the triggers can be run there as well.

Trigger Invocation

Multiple uniquely named Trigger instances may be associated with the same database. In such cases, the triggers are invoked in the order specified by the list argument to the trigger setting methods defined by DatabaseConfig.

If the invocation of a trigger results in a runtime exception, the transaction (if one was associated with the method) is invalidated and any subsequent triggers also associated with the operation are skipped. It's the caller's responsibility to handle the exception and abort the invalidated transaction.

The implementation of a trigger method may result in the invocation of additional trigger methods. It's the application's responsibility to ensure that the use of cascading triggers does not create an infinite recursion.

Trigger methods are not synchronized. It's up to the application to make any necessary provisions for synchronization. On a related note, a trigger method should not make any assumptions about the thread of control in which it is invoked. That is, it may be invoked in the same thread of control as the triggering operation, or it may be invoked in a different thread.

Trigger methods are expected to be lightweight. If they are required to do substantial work, it may be best to queue the work so that the method returns quickly and the bulk of the work is accomplished asynchronously.

Trigger Methods and Transactions

A trigger method takes a transaction as its first argument. The argument is not null if the environment is transactional. The non-null transaction argument to trigger methods defined by Trigger is always valid and can be used by the method to make transactional changes. The non-null transaction argument passed to the commit and abort triggers associated with TransactionTrigger is no longer valid and cannot be used to make transactional changes.

The transactional context associated with the code executing in a trigger is exactly the same as that associated with any JE application code; it is subject to exactly the same restrictions. For example, a trigger method associated with a DatabaseTrigger executed on a replica cannot make any modifications to a replicated database using the transaction supplied to it. It can however modify local databases.

Copyright (c) 2004-2012 Oracle. All rights reserved.