| Oracle® Communications Services Gatekeeper Platform Development Studio Developer's Guide Release 5.1 E37535-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Communications Services Gatekeeper Platform Development Studio Developer's Guide Release 5.1 E37535-01 |
|
|
PDF · Mobi · ePub |
This chapter provides an overview of the Oracle Communications Services Gatekeeper (Services Gatekeeper) Universal Computer Protocol (UCP) API Java interface. It also contains some guidance on how to develop a customized UCP plug-in using the Services Gatekeeper Platform Development Studio and the UCP APIs.
The UCP protocol APIs enable platform developers to create custom UCP plug-ins without having to set up and manage connections from Services Gatekeeper to applications and SMSCs.
The UCP Protocol Server Service manages the low-level connectivity details, in conjunction with a configurable Connection Information Manager service, which stores mappings between plug-in instances and the hosts and ports and mappings between application instances and network node credentials.
Using the Protocol Server Service APIs, a plug-in obtains a connection to an application or SMSC and sends a protocol data unit (PDU) or acknowledgement on that connection. The APIs include classes for constructing UCP PDUs.
Figure 8-1 shows the UCP architecture.
A client-side connection is a connection between Services Gatekeeper and the SMSC, since Services Gatekeeper acts as client in this relationship. In the context of this architecture, a server-side connection is a connection between an application and Services Gatekeeper, since Services Gatekeeper acts as server in this relationship.
The UCP Protocol Server Service provides connection services on behalf of UCP plug-ins. It communicates with external applications and SMSCs using UCP over TCP/IP. This service:
Sends and receives UCP data from the socket.
Constructs the UCP PDU.
Associates the current PDU with the correct application instance.
Calls the plug-in.
All requests from a plug-in instance to the Protocol Server Service contain a plug-in instance ID. The Protocol Server Service performs connection and network credential mapping based on the configuration set up in the Connection Information Manager.
The UCP Protocol Service API defines the interface between the UCP Protocol Server Service and UCP plug-ins. See the oracle.ocsg.protocol.ucp and oracle.ocsg.protocol.ucp.pdu packages in Services Gatekeeper Java API Reference for documentation on this API.
The Protocol Server Service is a standard Services Gatekeeper WLS service. You can access it from the Administration console as UCPService under Container Services.
The Connection Information Manager is a standard Services Gatekeeper service, which creates and stores connection and credential mappings that UCP plug-in instances need to connect to network elements and applications.
The UCP Protocol Service uses the Connection Information Manager to map plug-instance IDs to SMSC IP addresses and ports.
You can also optionally configure in the Connection Information Manager the local address and port to bind to when setting up a client-side connection to an SMSC. When Services Gatekeeper connects to the remote network node, it uses the specified local host IP address and port combination to bind the socket on the Services Gatekeeper side of the connection. The Protocol Service uses the specified port as a starting offset and increments the port number by one for each additional connection additional associated with the same plug-in instance ID. If the local host address is not configured, an ephemeral port is used.
You manage connection information settings from the Administration console. See ConnectInfoManager under Container Services, as shown in Figure 8-2. See the discussion of managing and configuring connection information in Services Gatekeeper System Administrator's Guide for information about specific operations.
Figure 8-2 UCP Protocol Server Service and Connection Information Manager in the Administration Console
A plug-in implements the PluginNorth interface to perform the following tasks on behalf of application-initiated requests:
Send a mobile-terminated (MT) SMS message
Open a UCP session
Send an ACK to the SMSC
Send a NACK to the SMSC
You would extend and implement this interface to add a new application-facing UCP protocol plug-in.
A plug-in implements the PluginSouth interface to perform the following tasks on behalf of network-triggered requests:
Deliver a mobile-originated (MO) SMS message
Deliver a message delivery notification associated with a previously-sent MT SMS
Send an ACK to the application
Send a NACK to the application
You would extend and implement this interface to add a new network-facing UCP protocol plug-in.
In addition to the information in this chapter, developers should consult the following documents for information on how to build a UCP plug-in:
Services Gatekeeper Java API Reference
Of special interest are the following packages, which include the interfaces and classes for the UCP Protocol Server Service:
oracle.ocsg.protocol.ucp
oracle.ocsg.protocol.ucp.pdu
oracle.ocsg.protocol.common
The following packages include the plug-in interfaces and classes for the Native SMPP plug-in, which is part of the standard Services Gatekeeper Native UCP communication service. They can serve as a reference for developing customized north and south UCP plug-ins.
oracle.ocsg.plugin.nativefacade.ucp.north
oracle.ocsg.plugin.nativefacade.ucp.south
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
com.bea.wlcp.wlng.api.plugin.common
com.bea.wlcp.wlng.api.plugin.context
com.bea.wlcp.wlng.api.util
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 UCP chapter. This chapter provides an overview of the Services Gatekeeper Native UCP communication service. It documents the attributes and operations provided to manage the UCP Protocol Server Service. The protocol server service is available for any UCP plug-in to access using the UCP Protocol Server Service APIs.
Services Gatekeeper System Administrator's Guide
See the connection information chapter. The Connection Information Manager creates and stores connection and credential mappings used by UCP plug-ins.
The following procedure outlines the basic steps to perform to add a custom UCP plug-in.
Using the Services Gatekeeper SCE PDS Eclipse wizard, generate a customized network plug-in for the UCP communication service.
You can also use this wizard to create a custom interceptor, if necessary.
See the description of a generated project in Services Gatekeeper 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 and determines whether the plug-in instance is capable of servicing the current request.
See the discussion of communication services in Services Gatekeeper Platform Development Studio Developer's Guide.
If you are implementing an application-facing UCP module, extend and implement the PluginNorth interface: SubmitSm, openSession, ack and nack.
If you are implementing a network-facing UCP module, extend and implement the PluginSouth interface: deliverSm, deliveryNotification, ack and nack.
Create CDRs and EDRs to trace the message flow, if necessary.
From the Administration console, configure the connection and credential mappings in the Connection Information Manager.
See the discussion of managing and configuring connection information in System Administrator's Guide.
Build the plug-in project and create the EAR package, which will be deployed to Services Gatekeeper.
Use the Platform Test Environment (PTE) to test and debug the plug-in.
See Services Gatekeeper Platform Test Environment Guide.
The packages for the protocol server service are:
Using the UCP Protocol Server Service API, you can develop a custom UCP plug-in without having to implement the low-level connection functionality. The API provides a wrapper to bind, send, and receive messages and allows customization of PDUs.
The oracle.ocsg.protocol.common.package provides four basic interfaces from which the UCP Protocol Server Service APIs are derived:
AbstractProtocolService
This is the base class for the getProtocolServiceNorth and getProtocolServiceSouth methods. The UCPNetworkingServiceImpl class inherits from AbstractProtocolService to implement these methods.
ProtocolServiceProxyFactory
Gets references to the getProtocolServiceNorth and getProtocolServiceSouth methods for use by the plug-in.
ProtocolServiceNorth
This is the base interface for creating server-side connections.
ProtocolServiceSouth
This is the base interface for creating client-side connections.
The main protocol server service interfaces used by a UCP plug-in are:
UCPNetworkingService
The UCPNetworkingService interface provides methods to add, remove, list and otherwise manage server-side and client-side connections. See the UCPNetworkingService interface in the oracle.ocsg.protocol.ucp package in the Services Gatekeeper Java API Reference for a list of the methods in this interface.
In addition to accessing these methods programmatically, a System Administrator can also access most of the methods in the UCPNetworkingService interface as OAM operations from the UCPService pane of the Administration console.
Figure 8-3 shows how to access the UCPService pane.
Figure 8-3 Protocol Service Operations in Administration Console
UCPNetworkingServiceClient
This interface implements methods for sending PDUs, ACKs, and NACKs on a client-side connection. It extends the Services Gatekeeper oracle.ocsg.protocol.common.ProtocolServiceSouth interface.
The plug-in uses this interface's sendPDUOnClientConnection method to send the plug-in instance ID and the PDU. The method returns a connection ID that identifies the connection to the SMSC on which the request was sent.
UCPNetworkingServiceServer
This interface implements methods for sending PDUs, ACKs, and NACKs on a server-side connection. It extends the Services Gatekeeper oracle.ocsg.protocol.common.ProtocolServiceNorth interface.
The plug-in uses the sendPDUOnServerConnection method to send the connection ID and the PDU. The method returns a connection ID that identifies the connection to the application on which the request was sent.
This package provides utility classes for building UCP PDUs for the supported UCP operations. This package provides classes for all of the supported UCP abstract data types (ADTs), as well as a generic UCP ADT, UCP constants, headers, and parameters
The Protocol Server Service uses mappings between application instances to network nodes configured in the Connection Information Manager to set up the connections that are used by the plug-ins.
At a minimum you need to configure the credential map, host address, and user password using these operations:
createOrUpdateCredentialMap
createOrUpdateRemoteHostAddress or createOrUpdateLocalHostAddress
createOrUpdateListenAddress
createOrUpdateUserPasswordCredentialEntry
There are various possible mapping logics; for example:
One connection to the SMSC for all Services Gatekeeper applications
One connection to the SMSC for a group of Services Gatekeeper applications
One connection to the SMSC for each Services Gatekeeper application
The simplest scenario is to configure a plug-in always to use the same application instance for all UCP requests. This requires only one connection to the SMSC. You would create the application instance in Services Gatekeeper and dedicate it to UCP southbound requests in the Connection Information Manager. Before making the call to the UCP Protocol Server Service, the plug-in can switch context to the UCP-dedicated application instance
Another scenario would configure the plug-in to use the current application instance to send requests through the service. This results in multiple connections to the SMSC, at least one per application instance. In this case, you must configure the Connection Information Manager with connection credentials and SMSC address and port mappings for all application instances.
There is no single correct solution. The mapping logic that you choose depends on the demands of your situation.
The UCPProtocol read-only attribute contains the UCP protocol string. This value is set to the listen address defined by the createOrUpdateListenAddress operation in the Connection Information Manager.
In the Administration console, you can configure two attributes that control how the Protocol Server Service handles reconnection attempts:
MaxReconnectAttempts: Specifies the maximum number of reconnection attempts permitted. Set to -1 for no maximum, 0 for no reconnection attempts, or a positive integer indicating the maximum number of reconnections to attempt.
TimeBetweenReconnectAttempts: Specifies the time in milliseconds between reconnection attempts.
The first three examples in this section provide some guidance related to common tasks using the UCP APIs that would be performed by a custom application-facing UCP plug-in that implements and extends PluginNorth. The examples are based on a prototype for a ParlayX2.1 SMS plug-in. The last example is for a PluginSouth implementation processing a DELIVER_SM request.
The tasks include:
When a plug-in receives a SUBMIT_SM request from an application, the PluginNorth implementing class processes the parameters in the request, constructs the PDU, and sends it to the SMSC using the UCPNetworkingServiceClient APIs.
The plug-in:
Gets the UCP NetworkingService object. For example:
UCPNetworkingService ucpService = PX21UCPPluginInstanceImpl.getUCPNetworkingService();
Gets any outstanding standing SUBMIT_SM requests.
Creates the submit PDU, using the classes in the oracle.ocsg.protocol.ucp.pdu package. See "Creating a UCP PDU".
Gets the source connection ID.
Gets the UCP NetworkingService protocol interface for sending data on a client connection. For example:
UCPNetworkingServiceClient client = ucpService.getProtocolServiceSouth(UCPNetworkingServiceClient.class);
Sends the PDU on the client connection, using the UCPNetworkingServiceClient sendPDUOnClientConnection method. For example:
clientConnectionID = client.sendPDUOnClientConnection
(
px21UCPPluginInstanceImpl.getPluginInstanceId(),
px21UCPPluginInstanceImpl.getSourceServerPort(),
submitSMPDU,
outstandingSubmitSMRequests,
sourceConnectionID
);
To create a UCP PDU, you can use the classes in the oracle.ocsg.protocol.ucp.pdu package.
The following method creates the submitSM PDU used in "Sending a submitSm Request to the SMSC". It uses the using the UcpHeader, UcpParameter, GenericUcpAdt classes defined in the pdu package.
private UcpPDU createSubmitSMPDU(SendSms parameters) {
UcpHeader ucpHeader = new UcpHeader();
UcpParameter orParam = new UcpParameter("O");
ucpHeader.setParameter(UcpHeader.PARAM_OR, orParam);
UcpParameter otParam = new UcpParameter(UcpConstants.OT_SUBMIT_SHORT_MESSAGE);
ucpHeader.setParameter(UcpHeader.PARAM_OT, otParam);
UcpParameter trnParam = new UcpParameter("01");
ucpHeader.setParameter(UcpHeader.PARAM_TRN, trnParam);
UcpParameter lenParam = new UcpParameter("00000");
ucpHeader.setParameter(UcpHeader.PARAM_LEN, lenParam);
GenericUcpAdt data = new GenericUcpAdt(33);
//ADC
URI[] destAddresses = parameters.getAddresses();
String uriStringDestAddress = destAddresses[0].toASCIIString();
//Strip "tel:"
String destAddressString = stripURIPrefix(uriStringDestAddress);
UcpParameter adcParam = new UcpParameter(destAddressString);
data.setParameter(Ucp50Adt.PARAM_ADC, adcParam);
//OADC
String senderName = parameters.getSenderName();
UcpParameter oadcParam = new UcpParameter(senderName);
data.setParameter(Ucp50Adt.PARAM_OADC, oadcParam);
//NRQ and NT
SimpleReference simpleRef = parameters.getReceiptRequest();
String nrq = "";
String nt = "";
if(simpleRef != null){
nrq = "0"; //0 == NADC not used
nt = "7"; // 7 == all
}
UcpParameter nrqParam = new UcpParameter(nrq);
data.setParameter(Ucp50Adt.PARAM_NRQ, nrqParam);
UcpParameter ntParam = new UcpParameter(nt);
data.setParameter(Ucp50Adt.PARAM_NT, ntParam);
//If LRq is empty, the contents of LRAd and LPID are ignored
//Message type 3 == "Alphanumeric message encoded into IRA characters."
UcpParameter mtParam = new UcpParameter("3");
data.setParameter(Ucp50Adt.PARAM_MT, mtParam);
String message = parameters.getMessage();
String iraEncodedMessage = iraEncodeMessage(message);
UcpParameter msgParam = new UcpParameter(iraEncodedMessage);
data.setParameter(Ucp50Adt.PARAM_MSG, msgParam);
return new UcpPDU(ucpHeader, data);
}
A connection from the UCP plug-in to the SMSC is implicitly established on receipt of the openSession request. Upon receiving the openSession request, the Protocol Server Service uses the current context as a key to determine the connection and credential mapping to use for the new connection that it is creating. The user and plug-in instance ID must therefore be configured in the Connection Information Manager before the openSession request is sent; otherwise the openSession request will fail.
The APIs do not provide a specific open session method.
To create a new session to the SMSC, create an openSession PDU using the pdu package and use the sendPDUOnClientConnection with a that openSessionPDU as the PDU parameter:
UCPNetworkingServiceClient client = ucpService.getProtocolServiceSouth(UCPNetworkingServiceClient.class);
String connectionID = client.sendPDUOnClientConnection
(myUCPPluginInstanceImpl.getPluginInstanceId(),
sourceServerPort,
openSessionPDU,
outstandingOpenSessionRequests,
sourceConnectionId);
A UCP plug-in uses the Protocol Server Service API after it receives an openSession PDU. The UCP Protocol Server Service creates a new socket connection for each session management operation of subtype openSession that is sent. The created connections are later used for sending SUBMIT_SM requests.
When a plug-in receives a DELIVER_SM request from the SMSC, the PluginSouth implementing class processes the parameters in the request.
If the plug-in is communicating with a web services-based application, it typically analyzes the parameters in the request to find the correct application callback reference (URL) to which the mobile-originated SMS message should be sent and then sends it.
If the plug-in is communicating with a UCP-based application, it typically constructs a DELIVER_SM PDU, which it sends to the application-facing UCP NetworkingServerService APIs.
After notifying the application of the message, the plug-in should send an ACK or NACK to the SMSC to report whether the notification was successful.
The following process flow is for a plug-in communicating with a web services-based application:
Gets the UCP NetworkingService object. For example:
UCPNetworkingService ucpService = PX21UCPPluginInstanceImpl.getUCPNetworkingService();
Processes the incoming deliverSM PDU to get the source and destination addresses. This implementation uses the UCP50Adt class to extract the data from the PDU:
String destinationAddress = deliverSMPDU.getData().getParameter(Ucp50Adt.PARAM_ADC).getValueAsString(); String originatingAddress = deliverSMPDU.getData().getParameter(Ucp50Adt.PARAM_OADC).getValueAsString();
Gets the notification callback references.
Implements support for using criteria and storing the mobile-originated message.
Creates the deliverSM PDU.
Send the deliverSM notification PDU. For example:
boolean notificationOK = sendDeliverSMNotification(callbackRef, destinationAddress, originatingAddress, deliverSMPDU);
Send ACK or NACK to the SMSC depending on the outcome of the notification. For example:
if(notificationOK){
sendAck(ucpService, connectionId, deliverSMPDU);
}else{
sendNack(ucpService, connectionId,deliverSMPDU, UcpConstants.ERROR_CODE_SYNTAX_ERROR);
}
|
 Copyright © 2007, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|