com.informix.smartTrigger

## Class IfxSmartTrigger

- java.lang.Object
- - java.lang.Thread
  - - com.informix.smartTrigger.IfxSmartTrigger

All Implemented Interfaces:
  IfmxThreadedSmartTrigger, java.lang.AutoCloseable, java.lang.Runnable

    public class IfxSmartTrigger
    extends java.lang.Thread
    implements IfmxThreadedSmartTrigger

Defines a Smart Trigger interface with the Informix server Using Informix Smart Trigger API (Informix server 12.10.xC9 or higher) this class encapsulates the setup for registering one or more smart triggers on the server Each smart trigger defined will have a callback method that returns data streamed from the Informix server when the specified conditions are met. For details on restrictions for the queries used to define the smart trigger conditions consult the Informix server documentation.

### Nested Class Summary

### Nested classes/interfaces inherited from class java.lang.Thread

`java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler`

### Field Summary

### Fields inherited from class java.lang.Thread

`MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY`

### Constructor Summary

Constructors
Constructor and Description
`IfxSmartTrigger(javax.sql.DataSource source)` Creates a smart trigger object with a connection made by the provided datasource
`IfxSmartTrigger(java.lang.String connectionUrl)` Creates a smart trigger object with a connection made by the provided URL
`IfxSmartTrigger(java.lang.String connectionUrl, java.util.Properties prop)` Creates a smart trigger object with a connection made by the provided URL

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`void` `addTrigger(java.lang.String tableName, java.lang.String tableOwnerName, java.lang.String databaseName, java.lang.String sqlQuery, IfmxSmartTriggerCallback... callback)` Sets a watch on a particular table using a query using the default label
`void` `addTrigger(java.lang.String tableName, java.lang.String tableOwnerName, java.lang.String databaseName, java.lang.String sqlQuery, java.lang.String label, IfmxSmartTriggerCallback... callback)` Sets a watch on a particular table using a query using the default label
`IfmxThreadedSmartTrigger` `buffer(int bufferSize)` Sets the buffer size for the data that will be held here in the client This should be set to a size that will collect the number of records you can get at a time as well as the 2 times the size of the JSON document that will be returned.
`void` `close()` Attempts to shutdown the internal connection that is watching for events If another thread is actively watching for events, this close is queued until an event is triggered (an event can be an operation that the user is watching for or a timeout event from the server).
`IfmxThreadedSmartTrigger` `commitTime(long time)` Advanced option to restart your smart trigger from a commit time that was reported from a prior Smart Trigger session
`java.lang.String` `detach()` Detach from this smart trigger session You must have set `IfmxThreadedSmartTrigger.detachable(boolean)` to true to enable this trigger to be detachable (12.10.xC9W1 or higher)
`IfxSmartTrigger` `detachable(boolean detachable)` Designate whether this session can be detached A detached session has a unique ID which can be referenced if this session closes to restore the session and recover any records that might not have transferred.
`java.lang.String` `getDetachableSesisonID()` Deprecated.
`java.lang.String` `getDetachableSessionID()` Returns the ID for this session if it is detachable If you use the `IfmxThreadedSmartTrigger.detachable(boolean)` option to make this detachable (12.10.xC9W1 or higher) calling this will return the session ID.
`java.util.List<java.lang.String>` `getLabels()` Returns a list of labels currently registered as triggers in this object
`IfmxThreadedSmartTrigger` `label(java.lang.String labelName)` Set a default label for all triggers created by this object
`IfmxThreadedSmartTrigger` `maxRecordsPerRequest(int size)` Sets how many records can be returned in a single event call This sets the maximum number of records returned if more than one record is sitting in the queue.
`void` `open()` Opens this smart trigger Performs initial registration for receiving the smart trigger events from the server.
`IfmxThreadedSmartTrigger` `operationsCacheSize(int size)` Sets the number of events/operations that the server will cache The number set here will be how many events the server will cache waiting on the client to retrieve them.
`java.lang.String` `readTriggerEvent()` Reads a single smart trigger event from the server This does not discriminate by label, calling this gets the next trigger event which could be for any label.

`void`

`registerCallback(java.lang.String label, IfmxSmartTriggerCallback callback)`
Registers a callback against an existing label If you have already created a trigger with a label using `IfmxThreadedSmartTrigger.addTrigger(String, String, String, String, IfmxSmartTriggerCallback...)` or if you are re-connecting to a detached session, you can register just the callback methods against the label you designated.

`void` `registerTriggers()` Registers all triggers that have been added/removed This must be called before any calls to readTriggerEvent() as this method make the server side calls to enable us to read the triggered events
`void` `removeTrigger(java.lang.String label)` Removes one or more triggers based on the label provided If you have already started the smart trigger, removing triggers will be queued until a timeout or a trigger is executed.
`void` `removeTrigger(java.lang.String tableName, java.lang.String tableOwnerName, java.lang.String databaseName)` Stops a trigger on a particular table/owner/database If you have already started the smart trigger, removing triggers will be queued until a timeout or a trigger is executed.
`void` `run()`
`IfmxThreadedSmartTrigger` `sessionID(java.lang.String id)` Sets the Smart Trigger session ID for us to connect to.
`IfmxThreadedSmartTrigger` `timeout(int timeout)` Sets the timeout for waiting for events from the server If no event is triggered after this timeout, a timeout event is fired, allowing the class to check if the user has made any changes to it's watch list or requested the connection to the server to be closed.
`IfmxThreadedSmartTrigger` `transactionID(long id)` Advanced option to restart your smart trigger from a transaction id that was reported from a prior Smart Trigger session
`void` `watch()` Starts watching for smart triggers You must call this (or run() if you are executing this as a thread) to actually start watching for smart triggers This method will block forever, until the thread is interrupted or another thread calls the close() method.

### Methods inherited from class java.lang.Thread

`activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield`

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

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

### Constructor Detail

#### IfxSmartTrigger

    public IfxSmartTrigger(javax.sql.DataSource source)
                    throws java.sql.SQLException

Creates a smart trigger object with a connection made by the provided datasource

Parameters:
  `source` - A datasource object to make a connection with
Throws:
  `java.sql.SQLException`

#### IfxSmartTrigger

    public IfxSmartTrigger(java.lang.String connectionUrl)
                    throws java.sql.SQLException

Creates a smart trigger object with a connection made by the provided URL

Parameters:
  `connectionUrl` - String URL which can be used to make a connection
Throws:
  `java.sql.SQLException`

#### IfxSmartTrigger

    public IfxSmartTrigger(java.lang.String connectionUrl,
                           java.util.Properties prop)
                    throws java.sql.SQLException

Creates a smart trigger object with a connection made by the provided URL

Parameters:
  `connectionUrl` - String URL which can be used to make a connection
  `prop` - Connection properties you want passed into the connection that is created
Throws:
  `java.sql.SQLException`

### Method Detail

#### run

    public void run()

Specified by:
  `run` in interface `java.lang.Runnable`
Overrides:
  `run` in class `java.lang.Thread`

#### detachable

    public IfxSmartTrigger detachable(boolean detachable)

Description copied from interface: `IfmxThreadedSmartTrigger`
Designate whether this session can be detached A detached session has a unique ID which can be referenced if this session closes to restore the session and recover any records that might not have transferred. The server will hold (up to the limit set) a number of records that can be recovered when the session is re-attached.

Specified by:
  `detachable` in interface `IfmxThreadedSmartTrigger`
Parameters:
  `detachable` - whether the session is detachable (default false)

#### label

    public IfmxThreadedSmartTrigger label(java.lang.String labelName)

Set a default label for all triggers created by this object

Specified by:
  `label` in interface `IfmxThreadedSmartTrigger`
Parameters:
  `labelName` - A default label name
Returns:
  this object

#### timeout

    public IfmxThreadedSmartTrigger timeout(int timeout)

Sets the timeout for waiting for events from the server If no event is triggered after this timeout, a timeout event is fired, allowing the class to check if the user has made any changes to it's watch list or requested the connection to the server to be closed. The default timeout value is 60 seconds

Specified by:
  `timeout` in interface `IfmxThreadedSmartTrigger`
Parameters:
  `timeout` - The timeout used for waiting for events
Returns:
  this object

#### buffer

    public IfmxThreadedSmartTrigger buffer(int bufferSize)

Sets the buffer size for the data that will be held here in the client This should be set to a size that will collect the number of records you can get at a time as well as the 2 times the size of the JSON document that will be returned. Plus an addition 1024 bytes for metadata For Example: Given you expect 10 rows back that the JSON representation will be at most 150 bytes Your buffer should be AT LEAST 150 * 2 * 10 + 1024 bytes. By default the buffer size is 64 * 1024 + 1024 which means you can get 64 rows of a 512 byte JSON documents at a time.

Specified by:
  `buffer` in interface `IfmxThreadedSmartTrigger`
Parameters:
  `bufferSize` - Size in bytes for the buffer for this class
Returns:
  this object

#### operationsCacheSize

    public IfmxThreadedSmartTrigger operationsCacheSize(int size)

Sets the number of events/operations that the server will cache The number set here will be how many events the server will cache waiting on the client to retrieve them. Any addition events over this cache size will be lost if the client does not retrieve them quickly enough

Specified by:
  `operationsCacheSize` in interface `IfmxThreadedSmartTrigger`
Parameters:
  `size` - size of server side operations cache
Returns:
  this object

#### maxRecordsPerRequest

    public IfmxThreadedSmartTrigger maxRecordsPerRequest(int size)

Sets how many records can be returned in a single event call This sets the maximum number of records returned if more than one record is sitting in the queue. If you set to 0, then you get back all that are available.

Specified by:
  `maxRecordsPerRequest` in interface `IfmxThreadedSmartTrigger`
Parameters:
  `size` - records in a single request
Returns:
  this object

#### commitTime

    public IfmxThreadedSmartTrigger commitTime(long time)

Advanced option to restart your smart trigger from a commit time that was reported from a prior Smart Trigger session

Specified by:
  `commitTime` in interface `IfmxThreadedSmartTrigger`
Parameters:
  `time` - time value from a prior operations JSON document returned from a smart trigger object
Returns:
  this object

#### transactionID

    public IfmxThreadedSmartTrigger transactionID(long id)

Advanced option to restart your smart trigger from a transaction id that was reported from a prior Smart Trigger session

Specified by:
  `transactionID` in interface `IfmxThreadedSmartTrigger`
Parameters:
  `id` - transaction id
Returns:
  this object

#### close

    public void close()
               throws java.sql.SQLException

Attempts to shutdown the internal connection that is watching for events If another thread is actively watching for events, this close is queued until an event is triggered (an event can be an operation that the user is watching for or a timeout event from the server). If another thread is not watching for events (is not currently in the watch() method) this method will attempt to close the underlying SQL connection

Specified by:
  `close` in interface `java.lang.AutoCloseable`
Throws:
  `java.sql.SQLException`

#### detach

    public java.lang.String detach()
                            throws java.sql.SQLException

Description copied from interface: `IfmxThreadedSmartTrigger`
Detach from this smart trigger session You must have set `IfmxThreadedSmartTrigger.detachable(boolean)` to true to enable this trigger to be detachable (12.10.xC9W1 or higher)

Specified by:
  `detach` in interface `IfmxThreadedSmartTrigger`
Returns:
  sessionID The session ID for this trigger that you can reconnect with via `IfmxThreadedSmartTrigger.sessionID(String)`
Throws:
  `java.sql.SQLException`

#### addTrigger

    public void addTrigger(java.lang.String tableName,
                           java.lang.String tableOwnerName,
                           java.lang.String databaseName,
                           java.lang.String sqlQuery,
                           IfmxSmartTriggerCallback... callback)
                    throws java.sql.SQLException

Sets a watch on a particular table using a query using the default label

Sets up a watch to a given table/owner/database using a simple SQL query. See the corresponding Informix documentation on which SQL Queries are valid.

You can pass in callback objects here or register callbacks later against a label using registerCallback(...) The user who is connected to the database from this class must have read permission on the table you are attempting to watch as well as sysadmin databse access. For details see the Informix server documentation. If you have already started the smart trigger, adding additional triggers will be queued until a timeout or a trigger is executed.

Specified by:
  `addTrigger` in interface `IfmxThreadedSmartTrigger`
Parameters:
  `tableName` - name of the table to watch
  `tableOwnerName` - owner of the table
  `databaseName` - database the table resides in
  `sqlQuery` - the SQL query that will validate if a change should trigger a message
  `callback` - a list of zero or more callback objects that will be executed when a trigger is fired.
Throws:
  `java.sql.SQLException`

#### addTrigger

    public void addTrigger(java.lang.String tableName,
                           java.lang.String tableOwnerName,
                           java.lang.String databaseName,
                           java.lang.String sqlQuery,
                           java.lang.String label,
                           IfmxSmartTriggerCallback... callback)
                    throws java.sql.SQLException

Sets a watch on a particular table using a query using the default label

Sets up a watch to a given table/owner/database using a simple SQL query. See the corresponding Informix documentation on which SQL Queries are valid.

You can pass in callback objects here or register callbacks later against a label using registerCallback(...) The user who is connected to the database from this class must have read permission on the table you are attempting to watch as well as sysadmin databse access. For details see the Informix server documentation. If you have already started the smart trigger, adding additional triggers will be queued until a timeout or a trigger is executed.

Specified by:
  `addTrigger` in interface `IfmxThreadedSmartTrigger`
Parameters:
  `tableName` - name of the table to watch
  `tableOwnerName` - owner of the table
  `databaseName` - database the table resides in
  `sqlQuery` - the SQL query that will validate if a change should trigger a message
  `label` - the label you want to use to identify/correlate one or more triggers
  `callback` - a list of zero or more callback objects that will be executed when a trigger is fired.
Throws:
  `java.sql.SQLException`

#### removeTrigger

    public void removeTrigger(java.lang.String tableName,
                              java.lang.String tableOwnerName,
                              java.lang.String databaseName)
                       throws java.sql.SQLException

Stops a trigger on a particular table/owner/database If you have already started the smart trigger, removing triggers will be queued until a timeout or a trigger is executed.

Specified by:
  `removeTrigger` in interface `IfmxThreadedSmartTrigger`
Parameters:
  `tableName` - table to stop watching
  `tableOwnerName` - owner of the table
  `databaseName` - database where the table resides
Throws:
  `java.sql.SQLException`

#### removeTrigger

    public void removeTrigger(java.lang.String label)
                       throws java.sql.SQLException

Removes one or more triggers based on the label provided If you have already started the smart trigger, removing triggers will be queued until a timeout or a trigger is executed.

Specified by:
  `removeTrigger` in interface `IfmxThreadedSmartTrigger`
Parameters:
  `label` - label to remove
Throws:
  `java.sql.SQLException`

#### registerTriggers

    public void registerTriggers()
                          throws java.sql.SQLException

Registers all triggers that have been added/removed This must be called before any calls to readTriggerEvent() as this method make the server side calls to enable us to read the triggered events

Throws:
  `java.sql.SQLException`

#### getLabels

    public java.util.List<java.lang.String> getLabels()

Returns a list of labels currently registered as triggers in this object

Specified by:
  `getLabels` in interface `IfmxThreadedSmartTrigger`
Returns:
  list list of labels

#### watch

    public void watch()
               throws java.sql.SQLException

Starts watching for smart triggers You must call this (or run() if you are executing this as a thread) to actually start watching for smart triggers This method will block forever, until the thread is interrupted or another thread calls the close() method. Note if you set your timeout() to zero, this will block until interrupted only. It will never close on it's own. It's recommended to always have some timeout so the loop here has a chance to take any actions, including adding/removing triggers or closing down. As smart triggers are caught from the server, this call will route them to the appropriate callback object you specified when you set up the smart trigger. Missed records or timeouts are automatically sent to all callback objects

Specified by:
  `watch` in interface `IfmxThreadedSmartTrigger`
Throws:
  `java.sql.SQLException`

#### readTriggerEvent

    public java.lang.String readTriggerEvent()
                                      throws java.sql.SQLException

Reads a single smart trigger event from the server This does not discriminate by label, calling this gets the next trigger event which could be for any label.

Returns:
  String json of the event
Throws:
  `java.sql.SQLException`

#### open

    public void open()
              throws java.sql.SQLException

Opens this smart trigger Performs initial registration for receiving the smart trigger events from the server. This is automatically called from watch()

Throws:
  `java.sql.SQLException`

#### getDetachableSesisonID

    @Deprecated
    public java.lang.String getDetachableSesisonID()

Deprecated.

Specified by:
  `getDetachableSesisonID` in interface `IfmxThreadedSmartTrigger`
Returns:

#### sessionID

    public IfmxThreadedSmartTrigger sessionID(java.lang.String id)

Description copied from interface: `IfmxThreadedSmartTrigger`
Sets the Smart Trigger session ID for us to connect to. This will re-establish the connection that was disconnected or lost when you call `IfmxThreadedSmartTrigger.watch()` or `Runnable.run()` Calling this method automatically sets `IfmxThreadedSmartTrigger.detachable(boolean)` to `true`

Specified by:
  `sessionID` in interface `IfmxThreadedSmartTrigger`
Parameters:
  `id` - Smart Trigger/Push Data session ID to connect to
Returns:
  IfmxThreadedSmartTrigger this object

#### registerCallback

    public void registerCallback(java.lang.String label,
                                 IfmxSmartTriggerCallback callback)

Description copied from interface: `IfmxThreadedSmartTrigger`
Registers a callback against an existing label If you have already created a trigger with a label using `IfmxThreadedSmartTrigger.addTrigger(String, String, String, String, IfmxSmartTriggerCallback...)` or if you are re-connecting to a detached session, you can register just the callback methods against the label you designated. This can also be used to attach multiple callback methods to a single trigger

Specified by:
  `registerCallback` in interface `IfmxThreadedSmartTrigger`
Parameters:
  `label` - The existing label for an existing trigger
  `callback` - Callback method/interface which will get executed when a trigger with the matching label is received.

#### getDetachableSessionID

    public java.lang.String getDetachableSessionID()

Description copied from interface: `IfmxThreadedSmartTrigger`
Returns the ID for this session if it is detachable If you use the `IfmxThreadedSmartTrigger.detachable(boolean)` option to make this detachable (12.10.xC9W1 or higher) calling this will return the session ID. You can save this ID and reconnect to the session if you close or get disconnected

Specified by:
  `getDetachableSessionID` in interface `IfmxThreadedSmartTrigger`
Returns:
  sessionID or null if the session is non-detachable or if the session is not open