public interface DBCDBPlugin_3
The '3' represents a version number, and has been embedded in the name so as to make your created plugins immune to changes in future plugin mechanisms.
On implementing DBCDBPlugin_3, the abstract functions in it will have to be implemented. They will be called by the system on various events, and the code in these functions thus implements the plugin mechanism.
The name of your class implementing this interface has to be entered into the Database Connector's browser-based console. The Database Connector will create an instance of the class.
When the Database Connector creates an instance of your class, it uses its no-argument constructor.Thus, a no-argument constructor must be included (or, do not include any constructors; Java will automatically provide a no-argument constructor.)
The Database Connector creates only one instance of this class (unless you have specified the same class for multiple plugin configuration). The instance is typically created at startup of the Database Connector, and destroyed on its shutdown, though the Database Connector can create and destroy the instance dynamically during normal operation (for example, when a plugin is reconfigured from the browser-based interface). Thus, this instance can cache commonly-required information like settings or resources, and can open files in its constructor or init() for later operations.
The Database Connector creates a new thread dedicated to each database plugin, so that long-running operations in the plugin do not affect other plugins or the Database Connector itself. Nevertheless, some functions are still called by the Database Connector's own thread (called the System Thread) - the developer must avoid performing long-running operations in those functions. The documentation of each function details the type of thread that calls it.
Modifier and Type | Method and Description |
---|---|
java.lang.String |
getExemptionSqlForOnePendingRequest(DBCDBOutQueuePrimaryValues val)
This event should return the sql clause part that exempts the record specified by the parameter.
|
DBCOutSMSPacket |
getPacketFromCurrentRecord(DBCSQLQuery q)
This event is called when the system needs to extract SMS packet information from the current database record.
|
java.lang.String |
getPollSqlStatement(java.lang.String paExemptionSqlClause)
This function should return the sql statement that will then be used to query the database.
|
DBCDBOutQueuePrimaryValues |
getPrimaryValuesFromCurrentRecord(DBCSQLQuery q)
This event is used to extract identifying information from the record.
|
boolean |
handleReceivedSMS(DBCInSMSPacket packet)
This event is called when the system receives an incoming (MO) SMS message.
|
boolean |
handleReceivedStatusReport(DBCInStatusReport packet)
This event is called when the system receives an incoming Status Report (Receipt).
|
DBCSQLConnectionTarget |
init(java.lang.String param1,
java.lang.String param2,
java.lang.String param3,
java.lang.String param4,
java.lang.String param5,
java.lang.String param6,
java.lang.String param7,
java.lang.String param8,
java.lang.String param9,
java.lang.String param10)
This event is called for the plugin to initialize itself.
|
void |
updateDatabaseOnSendResponse(DBCMessageSendStatusType success,
DBCDBOutQueuePrimaryValues prival,
java.lang.String MessageID,
java.lang.String[] AllMessageIDs)
This event should update the database regarding the status of the send.
|
DBCSQLConnectionTarget init(java.lang.String param1, java.lang.String param2, java.lang.String param3, java.lang.String param4, java.lang.String param5, java.lang.String param6, java.lang.String param7, java.lang.String param8, java.lang.String param9, java.lang.String param10)
It is called only once during the lifecycle of the plugin. It is guaranteed that it will be the first call to the plugin, and no other calls will take place until it has completed.
This event should typically create a DBCSQLConnectionTarget
object, that represents a target to a database.
This event is called from the Database Connector's own thread (System Thread). Any delays in this function will delay the startup of the Database Connector. Hence, long-running operations should be performed in the other functions, or in a new thread.
param1
- The parameters param1..10 are the values of the parameters specified in the plugin configuration page
of the Database Connector's Administration console.
These parameters can be used for a variety of purposes, mainly as a mechanism for
passing settings to the plugin, or customizing the plugin behaviour by the end-customer. Typical uses are:
Any errors during the plugin initialization because of which this plugin should not be started, can be notified to the Connector by returning a null. The connector will then ignore this plugin until the next restart of the Database Connector.
java.lang.String getPollSqlStatement(java.lang.String paExemptionSqlClause)
The sql statement should return a result of records, ie, it should be a SELECT on a table, view, or other stored procedure that returns results, of which 1 record corresponds to a message to be sent.
It should also include clauses that eliminate unnecessary records, for example, scheduling can be implemented by adding a date checking clause to this statement.
It is compulsary for it to include the exemption clause. Note that the exemption clause starts with an 'AND' when non-blank, so that the developer does not need to add it.
A sample code could be like:
return("SELECT * FROM OUTMSGQ WHERE STATUS='F'"+paExemptionSqlClause);
This event is called from a thread dedicated to this plugin, therefore can perform long-running operations without affecting other plugins or the Database Connector.
paExemptionSqlClause
- This string field holds a part of a WHERE clause which ignores records that are currently being processed.
This clause should be added into the sql statement being returned. This clause typically would look like:
AND (OUTMSGQID<> 1) AND (OUTMSGQID <> 2)
Note that the exemption clause may be blank, but never null.
Note that it starts with a space, to prevent typical sql-statement generation errors. The first word in it will be 'AND', when the statement is non-blank.
Failure to add the exemption clause into your sql statement will result in multiple messages being sent for the same record.
DBCOutSMSPacket getPacketFromCurrentRecord(DBCSQLQuery q) throws java.sql.SQLException
The code in this event should create a DBCOutSMSPacket, read fields from the query object, and place them into the packet.
Typical code will look like:
DBCOutSMSPacket Result=new DBCOutSMSPacket();
Result.setPhoneNo( q.getString("DESTPHONENO") );
Result.setContent( q.getString("CONTENT") );
Result.setRequestReceipt( q.getBoolean("REQUESTRECEIPT") );
Result.setSendAsFlash( q.getBoolean("SENDASFLASH") );
Result.setSenderName( q.getString("SENDERNAME") );
Result.setSenderNameIsAlpha( true );
return(Result);
This event is also free to obtain information from sources other than the query object,
for example, hardcoded information, other sql statements on the same or other databases.
The event may also use additional information present in the query object to correlate on queries on other databases.This event is called from the plugin's dedicated thread.
q
- The DBCSQLQuery query component is passed to the event. The fields in the current record of this object
should be used to generate the SMS packet.
The event can return null if the current record does not need to be sent for any reason.
This can be used to implement last-minute filtering of messages to be sent, though
it is recommended that most filters be implemented through the sql statement clauses
in getPollSqlStatement(String)
for performance reasons.
java.sql.SQLException
- Throwing of an exception causes the plugin to stop processing the existing resultset,
recheck the database connection, and then requery the database.DBCDBOutQueuePrimaryValues getPrimaryValuesFromCurrentRecord(DBCSQLQuery q) throws java.sql.SQLException
This event should generate a DBCDBOutQueuePrimaryValues object, and load it with data from the current record of the query that will be used to uniquely identify the current record. In most cases, the primary key fields of the resultset in the query can be used. The information placed into this object will be used later to identify the record to update its status once the message is succesfully sent, as well as while generating the exemption sql clause (through the getExemptionSqlForOnePendingRequest function).
The DBCDBOutQueuePrimaryValues has several fields, any of which can be used, as long as the same fields are used consistently.
A typical code for this function would be like:
DBCDBOutQueuePrimaryValues Result=new DBCDBOutQueuePrimaryValues();
Result.setPrimaryField4( q.getInt("OUTMSGQID") );
return(Result);
The information posted into this object is used only while the system is operational,
and does not exist beyond a system restart.This event is called from the thread dedicated to this plugin.
q
- The query object is passed to the event.The event can return null if the current record does not need to be sent for any reason. This can be used to implement last-minute filtering of messages to be sent, though for performance reasons it is recommended that most filters be implemented through the sql statement clauses in getPollSqlStatement.
java.sql.SQLException
- This event may throw an exception. Throwing of an exception
causes the plugin to stop processing the existing resultset, recheck the database connection,
and then requery the database.java.lang.String getExemptionSqlForOnePendingRequest(DBCDBOutQueuePrimaryValues val)
The clause can be built out of the fields of the DBCDBOutQueuePrimaryValues object that have been populated in the getPrimaryValuesFromCurrentRecord event.
This event is called from the thread dedicated to this plugin.
val
- The DBCDBOutQueuePrimaryValues object that represents a single unique record.Typically, the return value will be like:
return("OUTMSGQID <> "+val.PrimaryField4);
This event should compulsarily return a valid sql clause.
The clause should be complete by itself, and should not start with an AND or OR.
Note: If the primary values comprise of multiple fields, this function will be written either as
return("FieldX<>"+val.PrimaryFieldX+" OR FieldY<>"+val.PrimaryFieldY );
or as
return("NOT (FieldX="+val.PrimaryFieldX+" AND FieldY="+val.PrimaryFieldY +")");
Specifically, the <> operator is used in coordination with OR, not AND.
void updateDatabaseOnSendResponse(DBCMessageSendStatusType success, DBCDBOutQueuePrimaryValues prival, java.lang.String MessageID, java.lang.String[] AllMessageIDs)
It is also recommended that the MessageID or AllMessageIDs be stored, either in the same table, or a separate one. This is essential for correlating the delivery reports that are received by the system to the send records.
This event can be called by multiple threads, and simultaneously vis-a-vis the main plugin thread. Ensure that your code meets the multithreading requirements listed in the 'Multithreading Notes'.
success
- The DBCMessageSendStatusType object holds the status of the send of the message.prival
- The DBCDBOutQueuePrimaryValues identifies the record for which the message was sent.MessageID
- The String MessageID is the ID generated by the remote server for the message.
This will be valid only if the message send was successful, otherwise it may be blank or null.
If multiple SMSs were generated due to concatenation, it returns the MessageID of
the last SMS, after confirming that all the SMSs were sent successfully.
Its recommended that AllMessageIDs be used instead if your database structure supports it.AllMessageIDs
- An array of strings that contain the message ids of each of
the concatenated parts that this message comprises of. For accurate DLR reconciliation,
its recommended that AllMessageIDs be used instead of MessageID. Note that the last
valid string in AllMessageIDs will match MessageID.The array will always have a fixed number of elements matching the maximum number of parts that the system supports, usually 6. Based on the content of the message, some of those elements may be null. For example, if a message required 4 parts to be sent, AllMessageIDs[0] till AllMessageIDs[3] will have valid strings, while AllMessageIDs[4] and AllMessageIDs[5] will contain nulls.
Note that AllMessageIDs is returned even if the message does not use concatenation, with MessageID having the same value as AllMessageIDs[0]. Also note that servers that perform concatenation transparently will return only a single message id - this will similarly be present in both MessageID as well as AllMessageIDs[0]. Thus, do not use the count of valid elements as an accurate indication of concatenation size.
boolean handleReceivedSMS(DBCInSMSPacket packet)
Since a received message is sent to all plugins until accepted, plugins can be designed to receive and respond to a certain type of message, and ignore others (returning false).
For example, a courier organization may implement a plugin that responds to SMSs having the content 'TRACK' followed by a tracking number. They may then temporarily add another plugin to respond to their raffle draw results, which uses the 'RAFFLE' followed by the raffle ticket number. Thus, multiple plugins that receive messages and respond can coexist in the same system, and are unaffected by the installation of other plugins.
This event can be called by multiple threads, and simultaneously vis-a-vis the main plugin thread. Ensure that your code meets the multithreading requirements listed in the 'Multithreading Notes'.
packet
- The DBCInSMSPacket object that contains the details of the received message.If the event returns false, the message will be sent to the next plugin defined after this one, and so on, until one of the plugins accepts it.
boolean handleReceivedStatusReport(DBCInStatusReport packet)
This event can do one or more of the following:
Since a received status report is sent to all plugins until accepted, plugins can be designed to receive and respond to a certain type of status report, or only status reports whose MessageIDs are found in the database, and ignore others (returning false).
For example, 2 plugins may be present sending messages from 2 separate databases, with MessageIDs being stored in each database for its sent messages. A received status report can poll through the plugins, and the plugin will return true only if it finds the equivalent record in its database.
Note that due to concatenation of outbound messages, there may be multiple status reports received for a single outbound record. Thus, the failure to map a status report to a send record should not be treated as an error condition.
This event can be called by multiple threads, and simultaneously vis-a-vis the main plugin thread. Ensure that your code meets the multithreading requirements listed in the 'Multithreading Notes'.
packet
- The DBCInStatusReport object that contains the details of the received status report.If the event returns false, the status report will be sent to the next plugin defined after this one, and so on, until one of the plugins accepts it.