This section describes the example network protocol plug-in for SIP connectivity provided in the Platform Development Studio:
The SIP Plug-in example demonstrates the following:
The example is based on an end-to-end Communication Service, with a set of simple interfaces
The SendData and NotificationManager interfaces are used by an application and implemented by the Communication Service.
The Notification interface is used by the Communication Service and implemented by an application.
The Communication Service to network node interface is a simple SIP based interface that defines the two commands:
Figure 6-1 illustrates the flow for these operations.
The flow marked A* is for sendData
, the flow marked B* is for startNotification
and stopNotification
, and the flow marked C* is for notifyDataReception
.
The modules marked with 1 are automatically generated based on the WSDL files that defines the application-facing interface and code generation templates provided by the Platform Development Studio. The modules marked with 2 are skeletons generated at build time.
sendData
.sendData
method in the class SendDataPluginNorth. It will always invoke a class named PluginNorth, that has a prefix that is the same as the Java representation of the Web Service interface.The initial steps (B1-B3) are similar to flow A*. Instead of translating the request to a command on the network node, NotificationManagerNorth uses the StoreHelper to either store a new or remove a previously registered subscription for notifications. The data stored, the NotificationData, is used in network-triggered requests to resolve which application started the notification and the destination to which to send it. In the example the notification is started on an address, so the address is stored together with information to which endpoint the application wants the notification to be sent.
The SIP plug-in translates between an application-facing interface, defined in WSDL, see Web Service Interface Definition and a SIP network interface, see Network Interface Definition.
The WSDL, and Service Facade used is the same as for the Example Communication Service, see Web Service Interface Definition in Communication Service Example.
The network interface is SIP and the plug-in uses the Oracle Converged Application Server SIP Servlet container to process and create SIP messages.
Application-initiated requests are converted to regular SIP messages. It is configurable whether to send it to a SIP Proxy or not.
All SIP messages that arrive to the plug-in are processed and passed on the application that has subscribed for notifications that matches the network-triggered request.
The directory structure is similar to the directory structure for the example Communication Service, see Directory Structure in Communication Service Example but adds a set of classes, descriptors, and artifacts as described below:
| +- plugins
| | +- sip
| | | +- config
| | | | +- sip
| | | | | +- WEB-INF
| | | | | | +- sip.xml
| | | | | | +- web.xml
| | | +- dist
| | | | +- com.acompany.plugin.example.sip.store_4.0.jar
| | | | +-
example_sip_plugin.jar
| | | | +- example_sip.war
| | | +- src/com/acompany/plugin/example/sip/
| | | | +- context
| | | | +- management
| | | | +- notification
| | | | +- notificationmanager
| | | | +- senddata
| | | | +- servlet
| | | | +- store
| | | +- storage
| | | | +- wlng-cachestore-config-extensions.xml
The source for the example SIP plug-in is very similar to the netex plug-in described in Communication Service Example. Below is a list of the classes that are added or changed.
The SIP plug-in has a different package structure compared to the netex plug-in:
package com.acompany.plugin.example.sip.*
The following classes are new, and relates to the SIP protocol:
The class com.acompany.plugin.example.netex.senddata.south.SendDataPluginToNetworkAdapter
has been replaced by direct calls from SendDataPluginNorth
to SendDataPluginSouth
.
The class com.acompany.plugin.example.netex.notification.south.SendDataPluginToNetworkAdapter
has been replaced by com.acompany.plugin.example.sip.notification.south.NotificationHandlerSouth
. The class also does a lookup for matching subscriptions. In the netex plug-in, this is done by NotificationHandlerNorth.
The class com.acompany.plugin.example.sip.senddata.south.SendDataPluginSouth
has been updated to use ExampleSipHelper
.
The MBean com.acompany.plugin.example.sip.management.ExampleMBean
has been changed to contain SIP-related attributes.
and the storage service configuration wlng-cachestore-config-extensions.xml
is updated to use another store.
Configuration files for the SIP Servlet has been added:
The build artifacts have been changed to:
The SIP Servlet-defined configuration files for the SIP application is added to WEB-INF/sip.xml
in example_sip.war
.
The Java EE standard configuration file for the Web application is added to WEB-INF/application.xml
in example_sip.war
.
Both configuration files are found in $PDS_Home/example/communication_service/example/plugins/sip/config/sip
.
The following artifacts are generated when the plug-in is built:
The build artifacts are created in $PDS_Home/example/communication_service/example/plugins/sip/dist
The deployable Service Enabler is created when the Communication Service is built. It is packaged in the EAR file example_enabler.ear
in $PDS_Home/example/communication_service/example/dis
t.
The store definition JAR file is also generated to this directory.
Note that both the netex plug-in and the SIP plug-in will be packaged in example_enabler.ear
.
are provided in $PDS_Home/example/communication_service/example/plugins/sip/config/edr
Add the contents of these files to Oracle Communications Services Gatekeeper when deploying the Service Enabler.
Below is a description of classes that are new or have been changed compared to the netex plug-in described in Communication Service Example.
Package: com.acompany.plugin.example.sip.servlet
Extends javax.servlet.sip.SipServle
The SIP Servlet part of the plug-in. Uses ExampleSipHelper to manage network-triggered requests.
Initialization for the SIP Servlet.
Calls init() on ExampleSipHelper and provides the ServletContext to ExampleSipHelper.
Handles network-initiated SIP messages.
Returns a SIP 200 OK Response to the network.
Extracts the to and from URIs, and the content of the SIP message and calls notifyCallbacks with these parameters on ExampleSipHelper.
Package: com.acompany.plugin.example.sip
Singleton class that holds the SIPFactory, the SipSessionsUtil, and list of plug-in instances that can be used to process network-triggered messages.
Initialization for ExampleSipHelper.
Called by ExampleSIPServlet, when it is being deployed.
Fetches the SipFactory and the SipSessionsUtil from the ServletContext and stores them in member variables.
Get method for SipSessionsUtil.
Called by the plug-in instance when it is being activated. Registers NotificationHandlerSouth in ExampleSipHelper. NotificationHandlerSouth is responsible for processing of network-triggered requests.
Called by the plug-in instance when it is being deactivated. Unregisters NotificationHandlerSouth from ExampleSipHelper.
Called by ExampleSipHelper when a network-triggered SIP message arrives.
Resolves a plug-in instance to deliver a network-triggered request to. Since all plug-in instances register their own instance of NotificationHandlerSouth, there are as many possible plug-in instances to use as there are plug-in instances. In the example, only one instance is picked since they all have the same logic and access to the same notification data.
An alternative way to implement it is to call all instances. The notification data in the store may or may not be shared among plug-in instances. It is up to the designer of the plug-in to decide which pattern to use. If the notification data is tied to the plug-in instance, the alternatives are to call all plug-in instances or to establish communication channels between the different plug-in instances in order to resolve which instance that shall be targeted for the request.
Sends data to the SIP network.
Creates a SipApplicationSession and a SipServletRequest and sends the request to the SIP network.
The SipServletRequest is created as a SIP Message, with the From: address set to identify Oracle Communications Services Gatekeeper, and the To: address to the address provided by the application.
The content of the SIP message contains the SIP Proxy URI fetched from the configuration store.
The method is annotated with @Edr.
Empty implementation that returns null. This method has meaning, and is used, only in network-triggered requests.
The application instance ID is already known in the RequestContext, since the class only handles application-initiated requests.
From interface com.bea.wlcp.wlng.api.plugin.PluginSouth
Gives the plug-in an opportunity to add additional values to the RequestContext before the application-initiated requests is passed on to public void send(String address, String data).
Empty in this example. Normally all data about the request should be known at this point, so no additional data needs to be set.
Implements PluginSouth, NetworkCallback.
Handles network-triggered requests from ExampleSipHelper.
Generates EDRs, finds the application instance that has subscribed for notifications, and passes on the request to NotificationHandlerNorth.
Resolves which application instance that has subscribed for notifications that matches the data in the network-triggered request. Use StoreHelper to find the subscription for notifications.
From interface com.bea.wlcp.wlng.api.plugin.PluginSouth
Empty implementation in this example. Normally all data about the request should be known at this point, so no additional data needs to be set. This method has meaning, and is used, only in network-triggered requests.
Gives the plug-in an opportunity to add additional values to the RequestContext before the network-triggered requests are passed on to NotificationHandlerNorth...
It defines the following methods:
Implemented by ExampleMBeanImpl.
Stores the URI to the SIP proxy to send application-initiated requests to in the configuration store for the plug-in instance.
All MBean methods should throw com.bea.wlcp.wlng.api.management.ManagementException or a subclass thereof if the management operation fails.
The SLA is on Communication Service level and identical to the one for the example Communication Service, see Communication Service Example.