com.informix.smartTrigger

Interface IfmxThreadedSmartTrigger

All Superinterfaces:

java.lang.AutoCloseable, java.lang.Runnable

All Known Implementing Classes:

IfxSmartTrigger

public interface IfmxThreadedSmartTrigger
extends java.lang.AutoCloseable, java.lang.Runnable

Represents a Threadable Smart Trigger object This object allows you to interact with an Informix server (12.10.xC9 or higher) in order to register and receive Smart Trigger push notifications when certain events happen on the server

Since:

4.10.9

Method Summary

Methods

Modifier and Type	Method and Description
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.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.
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.
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.
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 interface java.lang.Runnable

run

Method Detail

label

IfmxThreadedSmartTrigger label(java.lang.String labelName)

Set a default label for all triggers created by this object

Parameters:

labelName - A default label name

Returns:

this object

timeout

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

Parameters:

timeout - The timeout used for waiting for events

Returns:

this object

buffer

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.

Parameters:

bufferSize - Size in bytes for the buffer for this class

Returns:

this object

operationsCacheSize

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

Parameters:

size - size of server side operations cache

Returns:

this object

maxRecordsPerRequest

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.

Parameters:

size - records in a single request

Returns:

this object

commitTime

IfmxThreadedSmartTrigger commitTime(long time)

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

Parameters:

time - time value from a prior operations JSON document returned from a smart trigger object

Returns:

this object

transactionID

IfmxThreadedSmartTrigger transactionID(long id)

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

Parameters:

id - transaction id

Returns:

this object

close

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

addTrigger

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.

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

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.

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

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.

Parameters:

tableName - table to stop watching

tableOwnerName - owner of the table

databaseName - database where the table resides

Throws:

java.sql.SQLException

removeTrigger

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.

Parameters:

label - label to remove

Throws:

java.sql.SQLException

getLabels

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

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

Returns:

list list of labels

watch

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

Throws:

java.sql.SQLException