db
Class idbTrigger
java.lang.Object
|
+--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.