org.enhydra.instantdb.db
Class idbTrigger

java.lang.Object
  |
  +--org.enhydra.instantdb.db.idbTrigger

public class idbTrigger

extends java.lang.Object

 ************************************************************
 WARNING - Trigger objects are not part of the JDBC standard.
           Using trigger objects will make it harder to port
           your application to an alternative database.
 ************************************************************
 

Trigger objects provide applications with the opportunity to react to database events.

A Trigger object can be notified of changes to a specified table. Triggers on the system tables are not allowed.

When a trigger is activated, InstantDB provides the row being modified, together with the transaction ID and Connection responsible for the change. It is the responsibility of the application to ensure that a row contains sufficient information to make it uniquely identifiable (such as providing a UNIQUE column).

Field Summary

static int	TRIGGER_ON_ADD Notify the trigger object when a row is added to the database table.
static int	TRIGGER_ON_COMMIT Notify the trigger object when a transaction involving the database table is committed.
static int	TRIGGER_ON_DELETE Notify the trigger object when a row is deleted in the database table.
static int	TRIGGER_ON_ROLLBACK Notify the trigger object when a transaction involving the database table is rolled back.
static int	TRIGGER_ON_UPDATE Notify the trigger object when an update to the database table takes place.

Constructor Summary

idbTrigger(java.lang.String table, int events)
Constructs a new Trigger object.

Method Summary

void	delete() Deletes this trigger.
java.sql.Connection	getConnection() Finds the connection which activated the current trigger activation.
int	getEvents() Returns the bitmap of events that this trigger is notified of.
java.lang.String	getTableName() Returns the name of the table that this trigger is monitoring.
void	onAdd(java.util.Vector row, long transactionID) Callback invoked by InstantDB when a row is added to the table being monitored.
void	onCommit(long transactionID) Callback invoked by InstantDB when a transaction involving the table being monitored is committed.
void	onDelete(java.util.Vector row, long transactionID) Callback invoked by InstantDB when a row is deleted from the table being monitored.
void	onRollback(long transactionID) Callback invoked by InstantDB when a transaction involving the table being monitored is rolled back.
void	onUpdate(java.util.Vector row, long transactionID) Callback invoked by InstantDB when a row in the table being monitored is updated.
void	preUpdate(java.util.Vector row, long transactionID) Callback invoked by InstantDB before a row is updated in the table being monitored.

Methods inherited from class java.lang.Object

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

Field Detail

TRIGGER_ON_UPDATE

public static final int TRIGGER_ON_UPDATE

Notify the trigger object when an update to the database table takes place.

TRIGGER_ON_DELETE

public static final int TRIGGER_ON_DELETE

Notify the trigger object when a row is deleted in the database table.

TRIGGER_ON_ADD

public static final int TRIGGER_ON_ADD

Notify the trigger object when a row is added to the database table.

TRIGGER_ON_ROLLBACK

public static final int TRIGGER_ON_ROLLBACK

Notify the trigger object when a transaction involving the database table is rolled back.

TRIGGER_ON_COMMIT

public static final int TRIGGER_ON_COMMIT

Notify the trigger object when a transaction involving the database table is committed.

Constructor Detail

idbTrigger

public idbTrigger(java.lang.String table,
                  int events)
           throws java.lang.IllegalArgumentException,
                  java.sql.SQLException

Constructs a new Trigger object. The application must specify the table which this Trigger object will monitor.

The application can specify which events on the table are to be notified to the Trigger.

Parameters:

table - The name of a table in the database. This should be of the form url.name, where url is the url used to open the database and name is the table name.

If no url is specified (i.e. table contains no dot) then the first database opened that contains the named table is assumed.

events - A bitmap of the events to trigger on. This can be constructed by adding together one or more of the TRIGGER_ON_xxxx event constants. Must be non-zero.

Throws:

java.lang.IllegalArgumentException - if table does not exist or if events is non-zero.

java.sql.SQLException - if no database has been opened, or the database is closed, or the table specified is one of the system tables.

Method Detail

getTableName

public java.lang.String getTableName()

Returns the name of the table that this trigger is monitoring.

Returns:

The name of the table.

getEvents

public int getEvents()

Returns the bitmap of events that this trigger is notified of.

Returns:

events bitmap.

onUpdate

public void onUpdate(java.util.Vector row,
                     long transactionID)
              throws java.sql.SQLException

Callback invoked by InstantDB when a row in the table being monitored is updated.

Applications should overide this method in order to handle updates. The default method does nothing.

If any exceptions are thrown and not caught, then the current transaction will rollback. Triggers can throw their own SQLException in order to generate a rollback, and so reject the modification.

At the time this trigger is activated, the row affected will appear to be absent from the database.

Parameters:

row - The row in the table which is being modified. This consists of a vector of objects ordered according to column position. Objects can be of type:

1. java.lang.Integer for Byte and Int columns.
2. java.lang.Long for Long, Currency and Date columns.
3. java.lang.Float for Float columns.
4. java.lanf.Double for Double columns.
5. java.lang.String for Char columns.
6. byte[] for Blob columns.

transactionID - The transactionID of the transaction modifying the table.

onAdd

public void onAdd(java.util.Vector row,
                  long transactionID)
           throws java.sql.SQLException

Callback invoked by InstantDB when a row is added to the table being monitored.

Applications should overide this method in order to handle row adds. The default method does nothing.

If any exceptions are thrown and not caught, then the current transaction will rollback. Triggers can throw their own SQLException in order to generate a rollback, and so reject the modification.

At the time this trigger is activated, the row will not yet have been added to the database.

Parameters:

row - The row in the table which is being modified. This consists of a vector of objects ordered according to column position. Objects can be of type:

1. java.lang.Integer for Byte and Int columns.
2. java.lang.Long for Long, Currency and Date columns.
3. java.lang.Float for Float columns.
4. java.lanf.Double for Double columns.
5. java.lang.String for Char columns.
6. byte[] for Blob columns.

transactionID - The transactionID of the transaction modifying the table.

onDelete

public void onDelete(java.util.Vector row,
                     long transactionID)
              throws java.sql.SQLException

Callback invoked by InstantDB when a row is deleted from the table being monitored.

Applications should overide this method in order to handle row deletes. The default method does nothing.

If any exceptions are thrown and not caught, then the current transaction will rollback. Triggers can throw their own SQLException in order to generate a rollback, and so reject the modification.

At the time this trigger is activated, the row will not yet have been deleted from the database.

Parameters:

row - The row in the table which is being modified. This consists of a vector of objects ordered according to column position. Objects can be of type:

1. java.lang.Integer for Byte and Int columns.
2. java.lang.Long for Long, Currency and Date columns.
3. java.lang.Float for Float columns.
4. java.lanf.Double for Double columns.
5. java.lang.String for Char columns.
6. byte[] for Blob columns.

transactionID - The transactionID of the transaction modifying the table.

preUpdate

public void preUpdate(java.util.Vector row,
                      long transactionID)
               throws java.sql.SQLException

Callback invoked by InstantDB before a row is updated in the table being monitored.

Applications should overide this method in order to trap the before image of a row being updated. The default method does nothing.

If any exceptions are thrown and not caught, then the current transaction will rollback. Triggers can throw their own SQLException in order to generate a rollback, and so reject the modification.

At the time this trigger is activated, the row will not yet have been updated.

Parameters:

row - The row in the table which is being modified. This consists of a vector of objects ordered according to column position. Objects can be of type:

1. java.lang.Integer for Byte and Int columns.
2. java.lang.Long for Long, Currency and Date columns.
3. java.lang.Float for Float columns.
4. java.lanf.Double for Double columns.
5. java.lang.String for Char columns.
6. byte[] for Blob columns.

transactionID - The transactionID of the transaction modifying the table.

onRollback

public void onRollback(long transactionID)

Callback invoked by InstantDB when a transaction involving the table being monitored is rolled back.

Applications should overide this method in order to handle rollbacks. The default method does nothing.

If the onAdd, onUpdate and onDelete methods restrict themselves to database activity, then there is no need to override this method. However, if the application is maintaining data structures which are unknown to the database, then there is a need to inform the application when a rollback takes place. This gives the application an opportunity to make its data structures consistent with the database after the rollback.

Applications may not access the database during this method. Any attempt to do so will result in an immediate SQLException and the rollback will continue.

Parameters:

transactionID - The transaction ID of the transaction being rolled back.

onCommit

public void onCommit(long transactionID)

Callback invoked by InstantDB when a transaction involving the table being monitored is committed.

Applications should overide this method in order to handle commits. The default method does nothing.

If the onAdd, onUpdate and onDelete methods restrict themselves to database activity, then there is no need to override this method. However, if the application is maintaining data structures which are unknown to the database, then there is a need to inform the application when a commit takes place. This gives the application an opportunity to note that any updated data structures are now consistent with the database.

Applications may not access the database during this method. Any attempt to do so will result in an immediate SQLException and the rollback will continue.

Parameters:

transactionID - The transaction ID of the transaction being rolled back.

delete

public final void delete()

Deletes this trigger.

The trigger is removed from the monitored table. No further notifications will be delivered to this trigger object.

getConnection

public java.sql.Connection getConnection()

Finds the connection which activated the current trigger activation.

Only valid during a trigger activation.