| Oracle® Communications Services Gatekeeper Patch Release Notes Release 5.0.0.1 Part Number E24004-03 |
|
|
View PDF |
| Oracle® Communications Services Gatekeeper Patch Release Notes Release 5.0.0.1 Part Number E24004-03 |
|
|
View PDF |
This chapter provides an overview of the Services Gatekeeper Short Messaging Peer to Peer Protocol (SMPP) API Java interface. It also contains some guidance on how to develop a custom SMPP plug-in using the Services Gatekeeper Platform Development Studio and the SMPP APIs.
The Services Gatekeeper SMPP implementation depends on a core module, the SMPP Service, which provides connectivity services for SMPP plug-ins. The SMPP API defines the interfaces between the plug-ins and the SMPP Service.
Using this API, platform developers can create SMPP plug-ins without having to manage the low-level tasks of connecting from Services Gatekeeper to applications and to SMSCs.
Figure 6-1 illustrates the basic Services Gatekeeper SMPP architecture.
The SMPP Service performs connection services on behalf of the standard SMPP plug-ins – Native SMPP and ParlayX 2.1 SMPP – as well as any custom SMPP plug-ins.
The SMPP Service handles the following tasks:
Receives SMPP data from the socket.
Constructs the SMPP protocol data unit (PDU).
Associates the current PDU with the correct application instance.
Invokes the plug-in.
Manages connections between Services Gatekeeper and applications.
Manages connections between Services Gatekeeper and Short Message Service Centers (SMSCs).
See the oracle.ocsg.protocol.smpp.service package in the Services Gatekeeper Java API Reference for documentation of the SMPP Services interfaces.
The SMPPServiceNorth interface processes requests received from an application-facing plug-in and sends them to the application.
The SMPPServiceSouth interface processes requests received from a network-facing plug-in and sends them to the SMSC.
The SMPP Service is a standard Services Gatekeeper WebLogic Server (WLS) service. You can access its Operations, Administration, and Maintenance (OAM) functions from the Administration console as SMPPService under Container Services.
Figure 6-2 SMPP Service in the Administration Console
The SMPPluginSouth interface processes network-triggered operations received from SMPPServiceSouth and sends them to SMPPServiceNorth. You would extend and implement this interface to add a new network-facing SMPP protocol.
The SMPPluginNorth interface processes requests received from SMPPServiceNorth and sends them to SMPPServiceSouth. You would extend and implement this interface to add a new application-facing SMPP protocol.
In addition to the information in this chapter, developers should consult the following documents for information on how to build an SMPP plug-in:
Services Gatekeeper Java API Reference
Of special interest are the following packages, which include the interfaces and classes for the SMPP service and plug-ins:
oracle.ocsg.protocol.smpp.service
oracle.ocsg.protocol.smpp.plugin
oracle.ocsg.protocol.smpp.event
oracle.ocsg.protocol.smpp.common
oracle.ocsg.protocol.common
In addition, you will need resources from various generic packages such as:
com.bea.wlcp.wlng.api.edr
com.bea.wlcp.wlng.api.management
com.bea.wlcp.wlng.api.plugin
Services Gatekeeper Platform Development Studio Developer's Guide
This guide explains how to use the Platform Development Studio to create a communication service or plug-in. See the following topics:
Understanding communication services
Using the Eclipse wizard
Description of a generated project
Services Gatekeeper Communication Service Guide
See the Native SMPP chapter. This chapter provides an overview of the Services Gatekeeper Native SMPP communication service, which uses the SMPP Service. This chapter includes general information about how the SMPP Service handles connectivity and documents the configurable attributes and operations of the SMPP Service.
The most common task is to add a custom network-facing SMPP plug-in using the south interfaces. It is also possible to create a custom application-facing SMPP module using the north interfaces. The following procedures cover both scenarios.
The basic steps for creating a custom SMPP plug-in are as follows:
Using the Services Gatekeeper SCE PDS Eclipse wizard, generate a customized network plug-in for the SMPP communication service.
You can also use this wizard to create a custom interceptor, if necessary.
See the description of a generated project in Platform Development Studio Developer's Guide.
Create the service type for the customized plug-in by extending the ServiceType class.
When the plug-in registers itself, an object of this type is passed to the Plug-in Manager.
Implement the ManagedPluginService interface.
This class activates, deactivates and initializes the plug-in service. It implements the PluginService, PluginServiceLifecycle and PluginInstanceFactory interfaces.
See the discussions of communication services and generated projects in Services Gatekeeper Platform Development Studio Developer's Guide.
Implement the ManagedPluginInstance interface.
This class activates a plug-in instance that has been created with the Plug-in Manager, after which the plug-in should register its MBeans and prepare to accept traffic. The plug-in service that activates this plug-in instance must be in the ACTIVE (ADMIN) or ACTIVE (RUNNING) state when the activate method is called.
This class also initializes and deactivates the plug-in instance, determines whether the plug-in instance is capable of servicing the current request, and sets up the session information cache.
See the discussion of communication services in Services Gatekeeper Platform Development Studio Developer's Guide.
Extend and implement the SMPPPluginMBean interface and register the MBean using the SMPP API.
If you are implementing a network-facing SMPP module, extend and implement the SMPPPluginSouth interface to process network-triggered events received from SMPPServiceSouth. See the oracle.ocsg.protocol.smpp.plugin package in Services Gatekeeper Java API Reference for the list of methods in this interface. See also Using the SMPP APIs.
Send the processed requests and responses to the application using the SMPPServiceNorth interface.
If you are implementing an application-facing SMPP module, extend and implement the SMPPPluginNorth interface to process application-initiated events received from SMPPServiceNorth. See the oracle.ocsg.protocol.smpp.plugin package in Services Gatekeeper Java API Reference for the list of methods in this interface. See also Using the SMPP APIs.
Send the processed requests and responses to the SMSC using the SMPPServiceSouth interface.
Maintain a session information class to cache session values such as client and server connection IDs, source and destination addresses, whether a delivery notification is required, and so on.
Create CDRs and EDRs to trace the message flow, if necessary.
See the discussion of annotations, EDRs, alarms, and CDRs in Services Gatekeeper Platform Development Studio Developer's Guide.
Build the plug-in project and create EAR package, which will be deployed to Services Gatekeeper.
Make sure that the smpp_api.jar is in the build class path; for example:
<path path="${target.dir}/protocol/modules/smpp_api/oracle.ocsg.protocol.smpp_api_5.0.0.0.jar"/>
Use the Platform Test Environment (PTE) to test and debug the plug-in.
See Services Gatekeeper Platform Test Environment Guide.
The System Administrator can configure several attributes that control how the SMPP Service manages connections.
The System Administrator can also set some parameters on how the SMPP Service behaves on a per application basis, such as whether certain operations are allowed after sending a short message or whether network-triggered notification is enabled. These parameters are set using the addApplicationSpecificSettings operation.
These settings can affect how requests and responses should be processed before they are sent. The SMPP Service API provides methods for querying some of these settings. See "SMPPService" for more information.
For a complete list of the SMPP Service attributes and operations, see the reference material for the SMPP server service in the Native SMPP chapter in Services Gatekeeper Communication Service Guide.
The packages for developing an SMPP plug-in are:
The oracle.ocsg.protocol.common package includes the ProtocolServiceProxyFactory interface, which is derived from the AbstractProtocolService class. This is the base class for the getProtocolServiceNorth and getProtocolServiceSouth methods.
The SMPP plug-in implementations use the getProtocolServiceNorth method to get a reference to the interface used to send PDUs to applications on server connections and the getProtocolServiceSouth method to get a reference to the interface used to send PDUs to SMSCs on client connections.
This package also includes the ProtocolServiceNorth and ProtocolServiceSouth interfaces from which the SMPPServiceNorth and SMPPServiceSouth interfaces are derived.
The oracle.ocsg.protocol.smpp.service package includes the interfaces for the SMPP Service:
This interface provides methods for generic SMPP Service tasks. These include checking whether available or active client connections exist for a plug-in instance, registering the SMPP work manager, and registering the plug-in MBean object, which exposes configurable attributes and operations to the SMPP Service.
It provides methods for querying the following SMPP Service configuration settings:
ConnectionBasedRouting: an attribute in the SMPP service
LooseBinding: an attribute in the SMPP service
notificationEnabled: an application-specific setting in the SMPP Service
subsequentOperationsAllowed: an application-specific setting in the SMPP Service
For details about these settings, see s the reference material for the SMPP server service in the Native SMPP chapter in Communication Service Guide.
The SMPPServiceNorth interface maintains a server connection pool that provides connections between Services Gatekeeper and applications. Services Gatekeeper is a server in this relationship.
When the application sends a successful BIND request to Services Gatekeeper, the plug-in obtains a server connection from the server connection pool and uses the implementation of the SMPPServiceNorth interface to send messages to the application.
The server connection:
Receives messages from the application.
Invokes the SMPPPluginNorth interface through a proxy.
Sends messages to the application.
Manages SMPP timers and windowing toward the application.
Stores transaction mapping information in cache.
This interface provides the following methods to send northbound requests and responses submitted by the plug-in: cancelSmResponse, dataSm, dataSmResponse, deliverSm, querySmResponse, replaceSmResponse, submitSmMultiResponse, submitSmResponse.
The SMPPServiceSouth interface maintains a client connection pool that provides connections between Services Gatekeeper and Short Message Service Centers (SMSCs). Services Gatekeeper is a client in this relationship.
The service processes BIND and UNBIND requests from the plug-in and obtains client connections on which to perform SMPP operations toward the SMSC.
The client connection:
Receives messages from the SMSC.
Invokes the SMPPPluginSouth interface through a proxy.
Sends messages to the SMSC.
Manages SMPP timers and windowing toward the SMSC.
Stores transaction mapping information in cache.
This interface provides the following methods to send southbound requests and responses submitted by the plug-in: bind, cancelSm, dataSm, dataSmResponse, deliverSmResponse, querySm, replaceSm, submitSm, submitSmMulti, unbind.
The oracle.ocsg.protocol.smpp.plug-in package defines the interfaces between the SMPP service and the SMPP plug-ins:
The plug-in developer extends and implements these interfaces for a custom plug-in.
A plug-in extends and implements the SMPPluginNorth interface to process the following supported application-initiated operations:
BIND
CANCEL_SM
DATA_SM
DATA_SM_RESPONSE
DELIVER_SM_RESPONSE
QUERY_SM
REPLACE_SM
SUBMIT_SM
SUBMIT_SM_MULTI
The SMPPPluginNorth implementation uses the SMPPServiceSouth interface to send these operations to the SMSC.
The plug-in extends and implements the SMPPluginSouth interface to process supported network-triggered operations, such as:
CANCEL_SM_RESPONSE
DATA_SM
DATA_SM_RESPONSE
DELIVER_SM
QUERY_SM_RESPONSE
REPLACE_SM_RESPONSE
SUBMIT_SM_MULTI_RESPONSE
SUBMIT_SM_RESPONSE
UNBIND
The SMPPPluginSouth implementation uses the SMPPServiceNorth interface to send these operations to the application.
This interface defines the network-facing connection attributes of the plug-in. A custom plug-in extends and implements this interface to provide the facilities to manage and query the plug-in.
The SMPPPluginNorth and SMPPPluginSouth implementations use this interface to query values in the plug-in while processing requests and responses.
This package provides the SMPPException class.
This package provides classes for SMPP events.
The basic procedure for processing and sending an incoming request or response through the SMPP Service is as follows:
Get the SMPPService object.
Process the fields in the incoming request or response.
Depending on the particular request or response typical processing may involve setting various fields in the request or response. For a response, you may need to process event data from the original request.
It may be necessary to query some SMPP Service configuration settings using the SMPPService methods. See "SMPPService" for more information.
Get the SMPPService object's protocol interface for sending data.
For sending data to the SMSC, you need the interface for SMPPServiceSouth to get a client-side connection. For sending data to the application, you need the interface for SMPPServiceNorth to get a server-side connection.
Send the request or response using the methods provided by the SMPPServiceNorth or SMPPServiceSouth.
The following sections illustrate how the SMPP Server APIs and settings are used in processing some requests and responses. They focus on sample tasks involving the SMPP API. Logging, exception handling, session information management, alarm creation, and other tasks not using the SMPP APIs are not considered.
These are among the tasks performed in custom SMPPPluginNorth and SMPPPluginSouth implementations.
When the plug-in receives a BIND request from an application, the SMPPPluginNorth class processes the request and sends it to the SMSC.
The SMPPPluginNorth bind method:
Gets the plug-in instance id and sets it in the request.
Gets the SMPP Service object.
Gets the service object's protocol interface for sending data on a client connection.
Sends the request using the SMPPServiceSouth's bind method.
For example:
public BindResponse bind(Bind request) {
BindResponse bindResp = null;
// Set the plug-in instance id
request.setPluginInstanceId(plugin.getPluginInstanceId());
// Get the SMPP service object
SMPPService smppService = plugin.getSMPPService();
// Get the interface for sending data on a client-side connection
SMPPServiceSouth serviceSouth = smppService.getProtocolServiceSouth(SMPPServiceSouth.class);
// Send the request
bindResp = serviceSouth.bind(request);
return bindResp;
}
When a plug-in receives a SUBMIT_SM request from an application, the SMPPPluginNorth class processes the request and sends it to the SMSC.
The SMPPPluginNorth submitSm method:
Gets the plug-in instance and application instance IDs and sets them in the request.
Queries the SMPP Service's application-specific notificationEnabled setting and sets the registeredDelivery field in the request accordingly.
if (request.getRegisteredDelivery() != 0 && !plugin.isNotificationAllowed(aigId)) {
request.setRegisteredDelivery(0);
}
Gets the SMPP Service object.
SMPPService smppService = plugin.getSMPPService();
Gets the service object's protocol interface for sending data on a client connection.
SMPPServiceSouth serviceSouth = smppService.getProtocolServiceSouth(SMPPServiceSouth.class)
Process any extra parameters (xparams) in the request.
Sends the request using the SMPPServiceSouth's submitSm method.
serviceSouth.submitSm(request);
When a plug-in receives a SUBMIT_SM_RESPONSE from the SMSC, the SMPPPluginSouth class processes the response and sends it to the application.
The SMPPPluginSouth submitSmResponse method:
Gets the SMPP Service object.
SMPPService smppService = plugin.getSMPPService();
Gets the plug-in message ID and sets it in the response.
Gets and processes the request event data from the original request to which this is the response.
Queries the SMPP Service and application-specific settings to determine whether a delivery receipt will be provided. For example, the following example checks the notificationEnabled and isSubsequentOperationsAllowed application-specific settings and the ConnectionBasedRouting SMPP Service attribute.
boolean needDR = plugin.isNotificationAllowed(aigId) && originalRequest.getRegisteredDelivery() != 0 &&
!plugin.isConnectionBasedRoutingEnabled();
if (plugin.isSubsequentOperationsAllowed(aigId) || needDR) {
// Set the session information accordingly . . .
}
Gets the SMPP Service object's interface for sending data on a server-side connection.
SMPPServiceNorth serviceNorth = smppService.getProtocolServiceNorth(SMPPServiceNorth.class);
Sends the response on that connection using SMPPService North's submitSmResponse method.
serviceNorth.submitSmResponse(response);
A DELIVER_SM request from the SMSC can be a simple SMS message from the network, or it can be the SMSC sending a delivery receipt for a previously submitted SUBMIT_SM request.
When a plug-in receives a DELIVER_SM request from the SMSC, the SMPPPluginSouth deliverSm method first examines the isDeliveryReceipt field in the request to determine whether the request is for a delivery receipt or a network-triggered SMS message. For example:
public void deliverSm(final DeliverSm request) {
request.setPluginInstanceId(plugin.getPluginInstanceId());
final boolean isDeliverReceipt = request.isDeliverReceipt();
if (isDeliverReceipt) {
deliverSmForDeliveryReceipt(request);
} else {
deliverSmForMO(request);
}
}
If the DELIVER_SM request is not for a delivery receipt, the processing is simple. The SMPPPluginSouth's method for processing the request:
Gets the SMPP Service object.
Gets the SMPP Service object's interface for sending data on a server-side connection.
SMPPServiceNorth serviceNorth = smppService.getProtocolServiceNorth(SMPPServiceNorth.class);
Sends the request using the SMPPServiceNorth's deliverSm method.
serviceNorth.deliverSm(request)
If the request requires a delivery receipt, the SMPPPluginSouth method for processing the request performs some additional tasks before sending the request:
Gets and sets the receipted message ID in the request.
String msgId = createPluginMessageId(request.getReceiptedMessageId()); request.setReceiptedMessageId(msgId);
Using the plug-in's implementation of the SMPPPluginMBean, gets the response command status.
failureCommandStatus = plugin.getManagement().getMySMPPPluginMBean().getDeliverSmRespCommandStatus();
You would implement the getDeliverSmCommandStatus method in your SMPPPluginMBean class to get the outcome of the DELIVER_SM request. The status should indicate whether the application was reached.
Uses the SMPPService isConnectionBasedRouting method to establish whether connection-based routing is enabled in the SMPP Service and processes the request accordingly.
If connection-based routing is enabled, the operator can send a delivery receipt to a site other than the one through which the original message was submitted. See the discussion of connection-based routing in Services Gatekeeper Communication Service Guide for information about how connection-based routing works in combination with other configuration settings.
Queries any additional relevant configuration settings for the plug-in using the custom management methods implemented by the plug-in in the SMPPPluginMBean and processes accordingly. For example, you may want to query whether to delete SMPP session information after the delivery receipt is received.
Uses the SMPPService isSubsequentOperationsAllowed method to query whether subsequent operations are allowed for the application instance and sets the session information accordingly.
Gets an SMPP Service object.
Gets the SMPPService object's interface for sending data on a server-side connection.
Sends the request using the SMPPServiceNorth's deliverSm method.
A DELIVER_SM response from an application can be the response for the receipt of an mobile-originated SMS message or of a delivery receipt.
The SMPPPluginNorth deliverSmReponse method gets the original request event associated with the response, determines whether the response if for a delivery receipt, and passes the request as well as the response to the method that will process and send the response.
public void deliverSmResponse(DeliverSmResponse response) {
DeliverSm originalRequest = (DeliverSm)response.getRequestEvent();
if (originalRequest != null && !originalRequest.isDeliverReceipt()) {
deliverSmResponseForMO(response, originalRequest);
} else {
deliverSmResponseForDeliveryReceipt(response, originalRequest);
}
}
The appropriate deliverSmResponse method processes any information needed from the response and its associated request.
A method that processes a response for a mobile-originated SMS message may need to construct EDR data before sending the response to the SMSC using the SMPPServiceSouth deliverSmResponse method.
|
 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|