com.sleepycat.je.trigger
Interface Trigger

All Known Subinterfaces:
PersistentTrigger, ReplicatedDatabaseTrigger
All Known Implementing Classes:
SyncCleanerBarrier.SyncTrigger

public interface Trigger

Trigger defines the trigger methods associated with a database. They provide a mechanism to track the database definition operations used to manage the lifecycle of the database itself, as well as the record operations used to modify the contents of the database.

WARNING: Only transient triggers are currently supported, and the documention below has not yet been updated to reflect this fact. The bottom line is that triggers are currently only useful and known to be reliable for maintaining a cache of database information on a replica, where the cache is initialized after opening the database (and configuring the trigger), and where only the TransactionTrigger.commit method is used. More specifically:

The trigger methods put and delete are used to track all record operations on the database.

A trigger method takes a transaction as its first argument. If the environment is not transactional, the argument is null. In all other cases, it's a valid transaction (Transaction.isValid is true) and the trigger can use this transaction to make it's own set of accompanying changes.

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 associated with the operation are skipped. It's the caller's responsibility to handle the exception and abort the invalidated transaction. If the exception is thrown during the replay of a transaction on a replica in an HA application, the environment is invalidated and a new environment handle must be created.

A Trigger is associated with a database via DatabaseConfig.setTriggers.


Method Summary
 void addTrigger(Transaction txn)
          The trigger method invoked when this trigger is added to the database.
 void delete(Transaction txn, DatabaseEntry key, DatabaseEntry oldData)
          The trigger method invoked after a successful delete, that is, one that actually resulted in a key/value pair being removed.
 String getDatabaseName()
          Returns the result of the setDatabaseName(String) operation.
 String getName()
          Returns the name associated with the trigger.
 void put(Transaction txn, DatabaseEntry key, DatabaseEntry oldData, DatabaseEntry newData)
          The trigger method invoked after a successful put, that is, one that actually results in a modification to the database.
 void removeTrigger(Transaction txn)
          The trigger method invoked when this trigger is removed from the database, either as a result of opening the database with a different trigger configuration, or because the database it was associated with it has been removed.
 Trigger setDatabaseName(String databaseName)
          Sets the database name associated with this trigger.
 

Method Detail

getName

String getName()
Returns the name associated with the trigger. All the triggers associated with a particular database must have unique names.

Returns:
the Trigger's name

setDatabaseName

Trigger setDatabaseName(String databaseName)
Sets the database name associated with this trigger. The JE trigger mechanism invokes this method to ensure that the trigger knows the name it's associated with across a rename of the database.

This method is also invoked each time the trigger is de-serialized, so that the trigger does not need to store this information as part of it's serialized representation.

Parameters:
databaseName - the name of the database associated with this trigger
Returns:
this

getDatabaseName

String getDatabaseName()
Returns the result of the setDatabaseName(String) operation.

Returns:
the name of the database associated with this trigger

addTrigger

void addTrigger(Transaction txn)
The trigger method invoked when this trigger is added to the database. This is the very first trigger method that is invoked and it's invoked exactly once. If the database is replicated, it's invoked once per node on each node.

Parameters:
txn - the active transaction associated with the operation. The argument is null if the database is not transactional.

removeTrigger

void removeTrigger(Transaction txn)
The trigger method invoked when this trigger is removed from the database, either as a result of opening the database with a different trigger configuration, or because the database it was associated with it has been removed. In the latter case, this trigger method follows the invocation of the Persistent#remove remove trigger. If the transaction is committed, there will be no subsequent trigger method invocations for this trigger.

Parameters:
txn - the active transaction associated with the operation. The argument is null if the database is not transactional.

put

void put(Transaction txn,
         DatabaseEntry key,
         DatabaseEntry oldData,
         DatabaseEntry newData)
The trigger method invoked after a successful put, that is, one that actually results in a modification to the database.

If a new entry was inserted, oldData will be null and newData will be non-null. If an existing entry was updated, oldData and newData will be non-null.

Parameters:
txn - the active transaction associated with the operation. The argument is null if the database is non-transactional.
key - the non-null primary key
oldData - the data before the change, or null if the record did not exist.
newData - the non-null data after the change

delete

void delete(Transaction txn,
            DatabaseEntry key,
            DatabaseEntry oldData)
The trigger method invoked after a successful delete, that is, one that actually resulted in a key/value pair being removed.

Truncating a database does not invoke this trigger; PersistentTrigger.truncate(com.sleepycat.je.Transaction) is invoked upon truncation.

Parameters:
txn - the active transaction associated with the operation. The argument is null if the database is non-transactional.
key - the non-null primary key
oldData - the non-null data that was associated with the deleted key


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