public interface DBCGenericPlugin_1
The '1' 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 DBCGenericPlugin_1, the 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.
To access a database to send SMS based on records, it is recommended that the DBCDBPlugin_3
be used, since it includes several database-specific features. This plugin can be used for
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 |
---|---|
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).
|
void |
handleSendResponse(DBCMessageSendStatusType success,
DBCDBOutQueuePrimaryValues prival,
java.lang.String MessageID)
This function should be implemented by descendents to know the status of a previous
sms send request (that was performed through a call to the
DBCPluginUtils.sendSMS(DBCOutSMSPacket, DBCDBOutQueuePrimaryValues) function. |
void |
handleShutdown()
This event is fired on a shutdown of the plugin, typically on a system shutdown or restart.
|
boolean |
init(DBCPluginUtils utils,
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.
|
boolean init(DBCPluginUtils utils, 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.
A typical use of this event is to create a Thread object that will be used for the execution of the plugin code.
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:
void handleSendResponse(DBCMessageSendStatusType success, DBCDBOutQueuePrimaryValues prival, java.lang.String MessageID)
DBCPluginUtils.sendSMS(DBCOutSMSPacket, DBCDBOutQueuePrimaryValues)
function.
Note that messages sent using DBCPluginUtils.sendSMSAndWaitForResponse(DBCOutSMSPacket, DBCDBOutQueuePrimaryValues, long)
do not require use of this
function. Nevertheless, the response for those sent messages will also be received
through this function.
success
- The success or failure of the request.prival
- The identifier passed to sendSMS for this specific message. Can be used to correlate
to the specific sendSMS call if multiple calls to sendSMS were performed.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.
void handleShutdown()
On this event, plugins should notify their main thread (if any) to stop processing and clean up resources.
The main thread should call DBCPluginUtils.pluginHasShutdown()
on completion to signal the system that its shutdown is complete.
The DBCPluginUtils.shouldPluginShutdown()
function will return true on and after the firing of this event. Either this event, or
the DBCPluginUtils.shouldPluginShutdown()
function can be used to ascertain whether the plugin should shutdown.
Plugins that do not process or poll external systems, for example, plugins solely for receiving and replying
to incoming messages, can simply call DBCPluginUtils.pluginHasShutdown()
from this event.
Note that should a plugin ignore this function, or fail to notify the system that it has shutdown in a reasonable
amount of time, the system may forcibly stop the plugin and its threads.