# Platform Development Studio - Developer’s Guide

# Communication Service Description

This chapter provides a description of a Communication Service and its components:

- High-level Components
- Communication Service Common
- Plug-in
- Management
- SLA Enforcement
- Shared libraries

## High-level Components

A Communication Service consists of a set of components:

- A Service Web Service (SOAP or RESTful)
- A Service EJB
- A Callback EJB
- A Call-back client EJB
- A set of network protocol plug-ins

One section of the set handles application-initiated requests, while another handles network-triggered requests, as illustrated in Figure 8-1. Some calls are remote since the modules may be deployed in separate clusters.

Figure 8-1 High-level component of a Communication Service

## Communication Service Common

The Communication Service common parts are auto-generated based on one or more WSDLs. For application-initiated requests, these are referred to as service WSDLs, while for network triggered requests, they are referred to as callback WSDL files.

Based on the service WSDLs, the following common parts of a Communication Service are generated using the Eclipse wizard:

- Service Web Service (SOAP or RESTful)
- Service EJB
- Call-back EJB
- Call-back client EJB

The Service Web Service implements the interfaces defined in the set of WSDL files that define the Web Service for application-initiated requests.

The Web Service is packaged into a single WAR file. An example of this is the SOAP Parlay X 2.1 Short Messaging, which defines the following interfaces for application-initiated requests: SendSms, ReceiveSms, and SmsNotificationManager. The Service Web Service implements all the above interfaces and is packaged into one single WAR file for the Communication Service.

The Web Service makes a Java RMI call to the Service EJB which, using the Plug-in Manager, calls the appropriate plug-in instance. The operations defined between the Service Web Service and the Service EJB are Java realizations of the interfaces defined in the service WSDLs. The Service EJB is packaged into a single JAR file for the Communication Service.

The Callback EJB is a Web Services client that uses a Web Service implemented by an application. It uses the interfaces defined in the set of WSDL files that define the Web Service for network-triggered requests, the callback WSDL files. The Web Service client is packaged into a single JAR file for the Communication Service.

The Callback EJB client is a client library that abstracts the remote call between the plug-in POJO and the Callback EJB and provides an invalidating cache of references to the remote object in order to support in-production redeployment of the EAR file for the access tier. The Callback EJB client is packaged into a single JAR file for the Communication Service.

Module | Description | North interface | South interface
--- | --- | --- | ---
Service Web Service | Implements the interfaces defined in the set of WSDL files that define the Web Service for application-initiated requests. Passes on the requests to the Service EJB. Any Service EJB of the same type can be chosen, regardless of the server on which it is deployed. The requests are load-balanced across the different server instances. Packaged into a single WAR file. Deployed as a part of the access tier EAR for the Communication Service. The Service Web Service is transparent to an extension developer. | SOAP/HTTP representation of the Service WSDLs | Java RMI representation of the Service WSDLs
Service EJB | Accepts requests from the Service Web Service implementation and propagates them to the appropriate plug-in using the Plug-in Manager. The Service EJB is responsible for: Constructing the RequestInfo object. Converting any exception caught to an exception that is defined in the Service WSDLs. This functionality must be implemented in the PluginFactory class, which extends Class: RequestInfo. Packaged in a single JAR file. Deployed as a part of the network tier EAR. | Java RMI representation of the Service WSDLs | Local Java representation of the Service WSDLs.
Callback EJB | A Web Services client that uses a Web Service implemented by an application. Accepts requests from the Service callback client EJB and propagates them to an application. Packaged into a single JAR file for the Communication Service. Deployed as a part of the access tier EAR. | SOAP/HTTP representation of the Service callback WSDLs. | Java RMI representation of the Callback WSDLs
Callback EJB client | A client library that abstracts the remote call between the plug-in and the Callback EJB. Accepts requests from a plug-in and propagates them to the Callback EJB. It provides an invalidating cache of references to the remote object in order to support in-production redeployment of the EAR file for the access tier. Any Callback EJB of the same type can be chosen, regardless of the server on which it is deployed. The requests are load-balanced across the different server instances. See Class: CallbackFactory and Interface: Callback. Packaged into a single JAR file for the Communication Service. Deployed as a part of the network tier EAR. | Java RMI representation of the Service callback WSDLs. | Local Java representation of the Callback WSDLs.

## Plug-in

The `com.bea.wlcp.wlng.api.plugin.*` packages contain a range of interfaces and classes for use by the extension developer.

The first of these is a set of interfaces that define the borders of a plug-in and related helper classes. These borders are used to apply aspects. See JavaDoc for `com.bea.wlcp.wlng.plugin`

### Plug-in Service and Plug-in Instance

A plug-in service is a JEE application that implements com.bea.wlcp.wlng.api.plugin.ManagedPluginService. It has:

- A life-cycle, defined in com.bea.wlcp.wlng.api.plugin.PluginServiceLifecycle.
- A registry, defined in com.bea.wlcp.wlng.api.plugin.PluginService.
- A factory to create plug-in instances, defined in com.bea.wlcp.wlng.api.plugin.PluginInstanceFactory

The plug-in instance is a class that implements com.bea.wlcp.wlng.api.plugin.ManagedPluginInstance. It has:

- A life-cycle defined in com.bea.wlcp.wlng.api.plugin.PluginInstanceLifecycle.
- A set of PluginNorth and PluginSouth interfaces that it implements. These interfaces are defined by the application-facing interfaces and the network-facing interfaces.
- A registry, defined in com.bea.wlcp.wlng.api.plugin.PluginInstance. This registry holds the list of the registered interfaces.
- Logic that examines the data in a request and determines if the instance can handle it or not. The interface for this logic is defined in com.bea.wlcp.wlng.api.plugin.PluginInstance.
- Logic that maintains the state of a connection. The interface for this logic is defined in com.bea.wlcp.wlng.api.plugin.PluginInstance.

Plug-in routing and registration with the Plug-in Manager is done by the plug-in instance. It is the plug-in instance that is part of the traffic flow.

Life-cycle management is performed on the plug-in service.

### States

A plug-in service is in one of a distinct set of states:

- NEW
- STARTED
- ACTIVE (ADMIN)
- ACTIVE (RUNNING)

The plug-in instance is in one of the following states:

- NEW
- ACTIVE
Figure 8-2 States for a plug-in service (left) and a plug-in instance (right)

The state transitions in Table 8-1 are triggered by either the start-up sequence of the server in which the plug-in is deployed or by an explicit deployment of the plug-in using either the weblogic.Deployer, see Oracle WebLogic Server Deploying Applications to WebLogic Server at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/deployment/, or the administration console.

Note: | All deployments are made at the EAR level, which means that individual plug-ins are not targeted, but all plug-ins within the EAR are affected.

Table 8-1 Plug-in service state transitions
Transition | Triggered by | Descriptions
--- | --- | ---
init | Deployment or startup. | The plug-in service has been created and initialized. The only method that will be called in this state is doStarted()
doStarted | Deployment or startup | The plug-in service should perform as much initialization as possible without being externally visible. Examples include: retrieve configuration data, create internal objects, and initialize stores.
doActivated | Deployment or startup | The plug-in service should continue activation and become visible, for example register MBeans, without accepting traffic.
handleResuming | Deployment or startup. | The plug-in service should order all plug-in instances to establish connections with the network node, if applicable, and accept traffic.
handleSuspending | Graceful undeployment/redeployment/stop That is, by invoking weblogic.Deployer with -graceful | The plug-in service should order the plug-in instance to reject new traffic, but to continue processing of in-flight work. A com.bea.wlcp.wlng.api.plugin.CompletionBarrier is provided in the request. When all in-flight work has been processed, the plug-in should get the com.bea.wlcp.wlng.api.plugin.CompletionBarrierCallback from the CompletionBarrier and call completed() on the CompletionBarrierCallback.
handleForceSuspending | Forced undeployment/redeployment/stop That is invoking weblogic.Deployer with -retiretimeout | The plug-in service should order the plug-in instance to reject new traffic and to discard in-flight work.
doDeactivated | Undeployment. | The plug-in service should deactivate itself, unregister any MBeans and become invisible.
doStopped | Undeployment. | The plug-in service should perform cleanup and be available for garbage collection.

The state transitions in Table 8-2 are triggered by either the start-up sequence of the server on which the plug-in instance is created or an explicit creation of a new instance using the Plug-in manager: see Managing and Configuring the Plug-in Manager in the System Administrator’s Guide.

Table 8-2 Plug-in instance state transitions
Transition | Triggered by | Descriptions
--- | --- | ---
activate | Creation of the plug-in instance using the Plug-in Manager MBean. | The plug-in instance is created. Depending on the state of the plug-in service, the plug-in instance should take the appropriate action. If the plug-in service is in state: ACTIVE (ADMIN), the plug-in instance shall: instantiate and register the PluginNorth and call-back interfaces with the Plug-in Manager. instantiate and register the PluginSouth interfaces with the Plug-in Manager. instantiate any ConfigurationStore. register the MBean for the instance. ACTIVE (RUNNING), the plug-in shall: connect to the network node, if a connection-oriented protocol is used. register call-backs with the network node, if any.
deactivate | Destruction of the plug-in instance using the Plug-in Manager MBean. | The plug-in instance shall: de-register any call-backs with the network node. disconnect from the network node, if connected. de-register the MBean for the instance. cancel any timers.

The Plug-in Manager maintains a pool of plug-in instances. This pool is provided to the plug-in when init() is called. This pool can be used to iterate over all instances in order to propagate events related to state transitions in the plug-in service.

The Plug-in Manager has a registry of all PluginNorth and PluginSouth interfaces, and it is the responsibility of the plug-in instance to register these interfaces with the Plug-in Manager. The Plug-in Manager uses this list of registered interfaces when routing a request to an appropriate plug-in instance. The Plug-in Manager queries the plug-in instance for information in order to make a routing decision. A plug-in instance maintains:

- A list of PluginNort interfaces
- A list of PluginSouth interfaces
- Whether the plug-in instance has a connection to the network node.
- Custom pattern matching, where the plug-in examines the request and marks the plug-in instance as either a 1) mandatory, 2)optional, or 3) required target for the request.

The plug-in service maintains a:

- Service type, used by all plug-in instances to generate EDRs, CDRs, and Statistics.
- List of supported address schemes, used by the Plug-in Manager when taking a routing decision.

### PluginPool

A collection of PluginInstances. The pool is populated when a plug-in instance is created using the PluginInstanceFactory. Using the pool, the plug-in service can:

- List plug-in instances
- Get a plug-in instance by its plug-in instance ID.

### Interface: Plugin

Superinterface for Interface: PluginNorth, Interface: PluginNorthCallBack, and Interface: PluginSouth.

PluginNorth defines the entry-point for application-initiated requests and is one of the borders at which aspects are woven. This interface must be implemented by all classes that handle application-triggered requests from the service EJB to the plug-in. There must be one class per interface.

Plugin South defines the entry-point for network-triggered requests. PluginNorthCallback defines the limit between the plug-in and the service callback EJB and further on to an application.These interfaces must be implemented by any plug-in that handles network-triggered requests, either new requests or notifications.

### Interface: PluginNorth

All interfaces in the plug-in that implement the traffic interfaces defined in the service WSDLs must implement this interface. A list of the implementations is maintained in the class that implements Interface: ManagedPluginInstance. Statistics aspects are applied for classes that implement this interface and counters for transaction units are increased. See Oracle Communications Services Gatekeeper Licensing, section for more information abut transaction units.

### Interface: PluginNorthCallBack

All interfaces in the plug-in that implement the traffic interfaces defined in the service callback WSDLs must implement this interface. Statistics aspects are applied for classes that implement this interface and counters for transaction units are increased. See Oracle Communications Services Gatekeeper Licensing, section for more information abut transaction units.

### Interface: PluginSouth

This interface must be implemented by the plug-in. Defines the south border of a plug-in, that is the network-facing border.

It contains methods used to rebuild the object defined by Interface: RequestContext for network-initiated requests, using information from the object defined by Interface: ContextMapperInfo, and methods for resolving which application instance the request belongs to.

When a network triggered request arrives at the plug-in, the usual pattern is to correlate the request with a previous subscription for notifications.

By extending PluginSouth in the class that implements the request, aspects that call the method

    public String resolveAppInstanceGroupId(ContextMapperInfo)

are applied.

It is the responsibility of the plug-in instance to extract the information provided in the request and to resolve the application instance that matches this data as a part of the rebuilding of the RequestContext. This is done using the Context Aspect.

After resolving the application instance, the method

    public void prepareRequestContext(RequestContext ctx, ContextMapperInfo info)

is called. In the implementation of this method, the plug-in instance has the option to add additional data to the object defined by Interface: RequestContext.

### Interface: ManagedPluginService

This is the interface a plug-in service must implement.

It extends the interfaces PluginService, PluginInstanceFactory and PluginServiceLifecycle.

#### Interface: PluginService

The interface that defines the plug-in service when registered in the Plug-in Manager.

It defines a set of attributes that must be defined by implementing the following methods:

- `getNetworkProtocol()`, returns a descriptive name for the supported network protocol. For example "SMPP v3.4"
- getServiceType(), returns a ServiceType. See Class: ServiceType.
- getSupportedSchemes(), returns a list of supported address schemes. This is a String array of URI schemes: for example “tel”, “mailto”, and “sip“.

#### Interface: PluginInstanceFactory

Factory that allows a plug-in service to create plug-in instances.

Defines the method:

    ManagedPluginInstance createInstance(String pluginInstanceId)

The plug-in service is responsible for creating an instance of the class implementing Interface: ManagedPluginInstance when this method is invoked. The method is triggered by the method `createPluginInstance` on the Plug-in Manager MBean.

#### Interface: PluginServiceLifecycle

Defines the life-cycle for a plug-in service. See States.

### Interface: ManagedPluginInstance

Must be implemented by a plug-in instance.

It extends the interfaces PluginInstance and PluginInstanceLifecycle.

#### Interface: PluginInstance

Defines the plug-in instance when registered in the Plug-in Manager.

The plug-in instance is responsible for:

- maintaining a list of north interfaces that the plug-in implements.
- maintaining a list of south interfaces that the plug-in implements.

Both of these lists are arrays of PluginInterfaceHolder.

The lists shall be returned when `getNorthInterfaces()` and `getSouthInterfaces()` are invoked, respectively.

The plug-in instance is also responsible for implementing `customMatch(RequestInfo requestInfo)`. In this request, the plug-in instance examines the RequestInfo object and decides if the plug-in instance can be used to serve the request. By returning:

- MATCH_OPTIONAL: Indicates that the request can be served by any plug-in instance. The request is completely stateless.
- MATCH_REMOVE: The request cannot be served. This situation can occur, for example, if a plug-in service does not implement the method being invoked or if the request relates to a previous request which is known only to a subset of the plug-in instances in the cluster.
- MATCH_REQUIRED: The request must be served by the plug-in instance. This situation can occur, for example, if the request relates to a previous request which is known only to a subset of the plug-in instances in the cluster.

Only these constants can be returned.

The plug-in instance is also responsible for maintaining information on the connection status with the network node it is connected to by returning True or False when `isConnected()` is invoked.

All methods in this interfaces are invoked by the Plug-in Manager when selecting a plug-in instance to route the request to.

#### Interface: PluginInstanceLifecycle

Defines the life-cycle for a plug-in service. See States.

### Class: RequestFactory

The Request Factory is used to perform application-initiated request processing both before and after a request is processed in the plug-in. Each Communication Service must have one implementation of the RequestFactory per each application-facing interface, named according to the pattern: `<myinterfacename>.PluginFactory`. A skeleton for the factory is generated by the Eclipse plug-in.

The RequestFactory has two main functions:

- Packages routing information contained in the request into a `RequestInfo` object that the Plug-in Manager uses to select an appropriate plug-in to process the request. See below for more information on `RequestInfo` objects.

Note: | In order to support sendlists which target multiple plug-ins, the Request Factory implementation must support three methods that are not required for non-sendlist based plug-ins:

- `createRequestInfos:` allows the creation of multiple `RequestInfo` objects. Each instance of a `RequestInfo` object is matched to a plugin. For example if an SMS message request is sent to 3 addresses, the factory should create an array of 3 `AddressRequestInfo` objects.
- `createPartialRequest:` splits a request into multiple requests sent to different plug-ins
- `mergeResults`: merges the results reported back by multiple plug-ins into a single result.

Note: | For more information, see the RequestFactory JavaDoc

Note: | Plug-ins are invoked in sequence and if one of them fails the whole request is considered a failure. In this case, an exception is thrown and the transaction is rolled back.

- Translates any exceptions thrown in the plug-in (or the underlying network) into a form that can be sent back to the application.

### Class: CallbackFactory

This class is used by a plug-in instance to get an implementation of Interface: Callback. There is one CallbackFactory per interface defined in the callback WSDLs.

The naming pattern is `com.acompany.example.callback.<interface name>CallbackFactory`

The implementation of the interface is fetched using the following pattern:

Listing 8-1

    import com.acompany.example.callback.NotificationCallback;

    import com.acompany.example.callback.NotificationCallbackFactory;

    ...

    private NotificationCallback cachedNotificationCallback = null

    ....

    private NotificationCallback getNotificationCallback() {

      if(cachedNotificationCallback == null) {

        cachedNotificationCallback =

        NotificationCallbackFactory.getInstance().create();

      }

      return cachedNotificationCallback;

    }

### Interface: Callback

This interface is used by a plug-in to propagate a network-triggered request from the plug-in to the callback EJB. The interface defines a Java representation of the methods defined in the callback WSDLs. There is one of these per interface defined in the callback WSDLs.

The naming pattern is `com.acompany.example.callback.<interface name>Callback`

### Class: RequestInfo

The object created by the RequestFactory to hold information from the application-initiated request. There are four sub-classes of `RequestInfo` that can be used depending on the request:

- `AddressRequestInfo`, if the request contains an address.
- `CorrelatorRequestInfo`, if the request contains a correlator.
- `RegistrationIdentifierRequestInfo`, if the request contains a registration identifier.
- `RequestIdentifierRequestInfo`, if the request contains a request identifier.

### Class: ServiceType

This is an abstract utility class that each plug-in must implement. An object of this type is passed to the Plug-in Manager when the plug-in registers itself, so that the Plug-in Manager can query for service type.

Aspects take care of making this service type available in the request thread of each plug-in. The service type is used by various services, including the `EdrService`.

Table 8-3 Existing ServiceTypes
ServiceType | Plugin
--- | ---
AccessServiceType | Access
ThirdPartyCallServiceType | Third-party Call
CallNotificationServiceType | Call Notification
SmsServiceType | Sms
MultimediaMessagingServiceType | Mms
TerminalLocationServiceType | Terminal Location
AudioCallServiceType | Audio Call
PresenceServiceType | Presence

### Interface: ContextMapperInfo

This interface defines a `ContextMapperInfo` object. When network-initiated traffic enters the plug-in from the network-facing (south) side, aspects take any annotated arguments from the network call that will be needed by the plug-in for correlation purposes and places them in this very short-lived object. Arguments are stored by key, defined when the annotation is set, that make it possible to retrieve a particular value. So if an argument is annotated with `@MapperInfo(C)`, its value can be retrieved using the key “C”. Methods in the plug-in that need to retrieve these arguments in order to perform a mapping (for example, associating a notification with the session ID of the request that established it) can use this object. The `PluginSouth` interface includes one such method, `resolveAppInstanceGroupdId.`

### Interface: RequestContext

Defines a `RequestContext` object. A `RequestContext` object is available in all Communication Services for both application-initiated and network-initiated requests. It contains contextual information about the request, including the service provider account ID, application account ID, and application instance of the application that initiated either the request or the notification, as well as the session ID.

### Class: ManagedPlugin

Deprecated. Use ManagedPluginService instead.

Allows the plug-in to register itself in the Plug-in Manager. See Class: AbstractManagedPlugin.

### Class: AbstractManagedPlugin

Deprecated. Use ManagedPluginService instead.

Extends `ManagedPlugin`, implements `ServiceDeployable`. It makes the plug-in deployable as a service in Oracle Communications Services Gatekeeper, and assists in registering the plug-in with the Manager. See the `com.bea.wlcp.wlng.api.plugin.common` package JavaDoc for details.

## Management

These are base classes and annotations for giving the Oracle Communications Services Gatekeeper Management Console or other JMX tools management access to Communication Services. See Making Communication Services Manageable for more information. Also see the JavaDoc for the packages: `com.bea.wlcp.wlng.api.management.*`

## SLA Enforcement

SLA enforcement operates on methods identified by the Java representation of the interface, and the operation of the application-facing interface for the Communication Service

The content of the tag <scs> defined in the <serviceContract> tag in the SLA is the plug-in type for the plug-in.

An operation on the application-facing interface is represented in the rules according to the following scheme: <service name> and <operation name>.

Parameters in the operation are represented in the rules according to the following scheme:

arg<n>.<parameter name>

where <n> in arg<n> depends on the WSDL that defines the application-facing interface, normally this is arg0.

If the parameter in <parameter name > is

- a composed parameter, the notation is according to the Java Bean notation for that parameter.
- an enumeration, the notation is according to the Java-representation of that parameter, <parameter name >.<enumeration value>. The <enumeration value> is the String representation. See Using the Platform Test Environment for information about the SLA Editor.

## Shared libraries

It is possible for multiple plug-ins to share common libraries: for example, a third party library or custom code that can be shared.

If there are such parts, these should preferably not be packaged into the plug-in jar but instead be copied into the `APP-INF/lib` directory of the Communication Service EARs that utilizes this shared library. All jars in this directory are available for each of the plug-ins in the EAR.