org.hsqldb.sample

## Class TriggerSample

- java.lang.Object
- - org.hsqldb.sample.TriggerSample

- All Implemented Interfaces:
    Trigger

      public class TriggerSample
      extends java.lang.Object
      implements Trigger

  Sample code for use of triggers in hsqldb.

  This class org.hsqldb.sample package, but a typical implementation is in users's class hierarchy. SQL to invoke is:

  CREATE TRIGGER triggerSample BEFORE|AFTER INSERT|UPDATE|DELETE ON myTable [FOR EACH ROW] [QUEUE n] [NOWAIT] CALL "myPackage.trigClass"
  This will create a thread that will wait for its firing event to occur; when this happens, the trigger's thread runs the 'trigClass.fire' Note that this is still in the same Java Virtual Machine as the database, so make sure the fired method does not hang.

  There is a queue of events waiting to be run by each trigger thread. This is particularly useful for 'FOR EACH ROW' triggers, when a large number of trigger events occur in rapid succession, without the trigger thread getting a chance to run. If the queue becomes full, subsequent additions to it cause the database engine to suspend awaiting space in the queue. Take great care to avoid this situation if the trigger action involves accessing the database, as deadlock will occur. This can be avoided either by ensuring the QUEUE parameter makes a large enough queue, or by using the NOWAIT parameter, which causes a new trigger event to overwrite the most recent event in the queue. The default queue size is 1024.

  Ensure that "myPackage.trigClass" is present in the classpath which you use to start hsql.

  If the method wants to access the database, it must establish a JDBC connection.

  When the 'fire' method is called, it is passed the following arguments:

  fire (int type, String trigName, String tabName, Object oldRow[], Object[] newRow)

  where 'type' is one of the values enumerated in the Trigger interface and the 'oldRow'/'newRow' pair represents the rows acted on. The first length - 1 array slots contain column values and the final slot contains either null or the value of the internally assigned row identity, if the concerned table has no primary key. The final slot must _never_ be modified.

  The mapping of row classes to database types is specified in /doc/hsqlSyntax.html#Datatypes.

  To be done:

  1. Implement the "jdbc:default:connection: URL to provide transparent and portable access to internal connections for use in triggers and stored procedures.
  2. Implement declarative column to trigger method argument mapping, conditional execution (WHEN clause), etc.
  3. Investigate and refine synchronous and asynchronous trigger models.

     Because certain combinations of trigger create parameters cause the individual triggered actions of a multirow update to run in different threads, it is possible for an 'after' trigger to run before its corresponding 'before' trigger; the acceptability and implications of this needs to be investigated, documented and the behaviour of the engine fully specified.

  4. Investigate and implement the SQL 200n specified execution stack under arbitrary triggered action and SQL-invoked routine call graphs.
  Since:
    1.7.0
  Author:
    Peter Hudson, Campbell Burnet (campbell-burnet@users dot sourceforge.net)

- - ### Field Summary

    - ### Fields inherited from interface org.hsqldb.Trigger

      `DELETE_AFTER, DELETE_AFTER_ROW, DELETE_BEFORE_ROW, INSERT_AFTER, INSERT_AFTER_ROW, INSERT_BEFORE_ROW, UPDATE_AFTER, UPDATE_AFTER_ROW, UPDATE_BEFORE_ROW`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TriggerSample()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `fire(int typ, java.lang.String trn, java.lang.String tn, java.lang.Object[] or, java.lang.Object[] nr)` A sample HSQLDB Trigger interface implementation.
    `static java.lang.String` | `getForEachSpec(int type)`
    `static java.lang.String` | `getOperationSpec(int type)`
    `static java.lang.String` | `getQueueSpec(int qs)`
    `static java.lang.String` | `getTriggerDDL(java.lang.String trn, int typ, java.lang.String tab, int qs, java.lang.String impl)`
    `static java.lang.String` | `getTriggerDescriptor(java.lang.String trn, int typ, java.lang.String tab)`
    `static java.lang.String` | `getWhenSpec(int type)`
    `static void` | `main(java.lang.String[] args)`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### TriggerSample

          public TriggerSample()

  - ### Method Detail

    - #### fire

          public void fire(int typ,
                           java.lang.String trn,
                           java.lang.String tn,
                           java.lang.Object[] or,
                           java.lang.Object[] nr)

      A sample HSQLDB Trigger interface implementation.

      This sample prints information about the firing trigger and records actions in an audit table.

      The techniques used here are simplified dramatically for demonstration purposes and are in no way recommended as a model upon which to build actual installations involving triggered actions.

      Specified by:
        `fire` in interface `Trigger`
      Parameters:
        `typ` - trigger type
        `trn` - trigger name
        `tn` - table name
        `or` - old row
        `nr` - new row

    - #### getWhenSpec

          public static java.lang.String getWhenSpec(int type)

    - #### getOperationSpec

          public static java.lang.String getOperationSpec(int type)

    - #### getQueueSpec

          public static java.lang.String getQueueSpec(int qs)

    - #### getForEachSpec

          public static java.lang.String getForEachSpec(int type)

    - #### getTriggerDDL

          public static java.lang.String getTriggerDDL(java.lang.String trn,
                                                       int typ,
                                                       java.lang.String tab,
                                                       int qs,
                                                       java.lang.String impl)
                                                throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

    - #### getTriggerDescriptor

          public static java.lang.String getTriggerDescriptor(java.lang.String trn,
                                                              int typ,
                                                              java.lang.String tab)

    - #### main

          public static void main(java.lang.String[] args)
                           throws java.sql.SQLException

      Throws:
        `java.sql.SQLException`

Copyright © 2001 - 2018 HSQL Development Group.