public class DBCPluginUtils
extends java.lang.Object
Constructor and Description |
---|
DBCPluginUtils(I_GemGenericPluginAdaptor_1 internaldata) |
Modifier and Type | Method and Description |
---|---|
boolean |
isOutgoingPathAvailable()
This function determines the current status of the link to the external server.
|
void |
pluginHasShutdown()
This function should be called by plugin developers to signal the system that the plugin has shutdown.
|
java.lang.String |
sendSMS(DBCOutSMSPacket packet,
DBCDBOutQueuePrimaryValues prival)
This function should be called by the developer when an outbound message needs to be sent
by the plugin.
|
DBCSendSMSResult |
sendSMSAndWaitForResponse(DBCOutSMSPacket packet,
DBCDBOutQueuePrimaryValues prival,
long timeoutMS)
This function can be called by the developer when an outbound message needs to be sent
by the plugin.
|
boolean |
shouldPluginShutdown()
This function returns the current status of the system, ie, whether it is in the process of shutting down.
|
public final boolean isOutgoingPathAvailable()
It is recommended that this function be called before processing for outbound messages, so that the processing can be deferred until the link is active.
If a thread is used for processing, it is recommended that it be put to sleep for a while.
Thus, unnecessary processing is eliminated when the system is unable to send messages.
Note that even if this function is ignored, and the sendSMS(DBCOutSMSPacket, DBCDBOutQueuePrimaryValues)
function is called, the
sendSMS may either return with a 'Connection not ready' error, or signal through the
DBCGenericPlugin_1.handleSendResponse(DBCMessageSendStatusType, DBCDBOutQueuePrimaryValues, java.lang.String)
event of the failure to send the message.
public final java.lang.String sendSMS(DBCOutSMSPacket packet, DBCDBOutQueuePrimaryValues prival)
For a simpler but synchronous version of this function, see sendSMSAndWaitForResponse(DBCOutSMSPacket, DBCDBOutQueuePrimaryValues, long)
.
The developer should create a DBCOutSMSPacket, load it with the information
about the SMS to be sent, and pass it to this function.
The developer should create a DBCDBOutQueuePrimaryValues, and optionally load it with
identifying information about the SMS request, which will be returned to the plugin in the
DBCGenericPlugin_1.handleSendResponse(DBCMessageSendStatusType, DBCDBOutQueuePrimaryValues, java.lang.String)
event.
The function returns a null string to indicate that the message packet has
been transmitted to the server. This does not mean that the server has accepted
the message - the response will be provided back to your code in the DBCGenericPlugin_1.handleSendResponse(DBCMessageSendStatusType, DBCDBOutQueuePrimaryValues, java.lang.String)
event.
Typical code will look like:
DBCOutSMSPacket outsms=new DBCOutSMSPacket();
outsms.setPhoneNo("441234567");
outsms.setContent("Test msg");
outsms.setRequestReceipt(true);
outsms.setSendAsFlash(false);
outsms.setSenderName("Me");
outsms.setSenderNameIsAlpha(true);
DBCDBOutQueuePrimaryValues id=new DBCDBOutQueuePrimaryValues();
id.PrimaryField4 = 123;
String result= sendSMS(outsms, id);
if(result==null)
{
System.out.println("Message request sent to server. Check handleSendResponse to know if it was accepted");
}
else
{
System.out.println("Message request could not be sent to server:"+result);
}
Multiple calls to sendSMS can be performed without waiting for the responses to be returned through handleSendResponse.
This allows the system to use multiple connections, improving your sending performance. The prival parameter
is used in this scenario to correlate the responses to the appropriate requests.packet
- The message packet to be sent.prival
- The ids uniquely identifying this message.public final DBCSendSMSResult sendSMSAndWaitForResponse(DBCOutSMSPacket packet, DBCDBOutQueuePrimaryValues prival, long timeoutMS)
This function is the synchronous version of the sendSMS(DBCOutSMSPacket, DBCDBOutQueuePrimaryValues)
function.
The developer should create a DBCOutSMSPacket, load it with the information about the SMS to be sent, and pass it to this function. The developer should also create a DBCDBOutQueuePrimaryValues, and load it with identifying information about the SMS request. It is essential that a such an object is provided; failure to provide a proper object can result in responses not being correlated properly with sent requests, resulting in timeouts and/or hangs.
This function blocks, ie, waits, until either the response is received, or the function times out.
In case the function returns due to a response having been returned by the server, the response status will be present in the returned object, alongwith the server-returned MessageID.
Note that the DBCGenericPlugin_1.handleSendResponse(DBCMessageSendStatusType, DBCDBOutQueuePrimaryValues, java.lang.String)
event is also fired. Even though the blocked thread is released
before the handleSendResponse is fired, the actual order of those events is jvm-dependent.
Caution: It should be noted that responses for timed-out request threads may return at unexpected times.
packet
- The message packet to be sent.prival
- The ids uniquely identifying this message.timeoutMS
- The time in milliseconds to wait for a response from the server.DBCSendSMSResult
object that contains the result of this function.public final boolean shouldPluginShutdown()
This function should be called by plugin developers in their thread or timer event, and on finding the system in a shutting down state, should relinquish resources, close files, and stop threads as applicable.
Developers should then call the pluginHasShutdown()
function to signal the system that it has shutdown.
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.
Developers may alternatively use the DBCGenericPlugin_1.handleShutdown()
event to be notified of shutdown events.
public final void pluginHasShutdown()
While this is usually in response to the shouldPluginShutdown()
returning true, or the firing of the
DBCGenericPlugin_1.handleShutdown()
event, it can also be called on the shutdown of a plugin on its own accord.
Multiple calls to this function have no effect.