2 Understanding Communication Service Components

Interface: Plug-in

Plug-in is the superinterface for "Interface: PluginNorth", "Interface: PluginNorthCallBack", and "Interface: PluginSouth".

These interfaces must be implemented by any plug-in that handles network-triggered requests, either new requests or notifications.

Interface: PluginNorth

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. All interfaces in the plug-in that implement the traffic interfaces contained in the service WSDL definitions must implement the PluginNorth interface. There must be one class per 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 Services Gatekeeper Licensing Guide for information about transaction units.

Interface: PluginNorthCallBack

PluginNorthCallback defines the limit between the plug-in and the service callback EJB and further on to an application.

All interfaces in the plug-in that implement the traffic interfaces contained in the service callback WSDL definitions must implement the PluginNorthCallback interface. Statistics aspects are applied for classes that implement this interface and counters for transaction units are increased. See Services Gatekeeper Licensing Guide for information about transaction units.

Interface: PluginSouth

PluginSouth defines the entry-point for network-triggered requests. It defines the south (or the network-facing) border of a plug-in. This interface must be implemented by the plug-in.

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

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

Aspects that call the method

public String resolveAppInstanceGroupId(ContextMapperInfo)

can be applied by extending PluginSouth in the class that implements the request.

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 object. This is done using the Context aspect. See "Understanding the Context Aspect" for more information.

After resolving the application instance, the contextual information about the request is set up by calling the following method

public void prepareRequestContext(RequestContext ctx, ContextMapperInfo info)

In the implementation of this method, the plug-in instance has the option to add additional data to the contextual information about the request in the object defined by RequestContext.

Interface: ManagedPluginService

Every plug-in service must implement the ManagedPluginService interface which extends the PluginService, PluginInstanceFactory and PluginServiceLifecycle interfaces.

Interface: PluginService

PluginService defines a plug-in service registered in the Plug-in Manager.

A set of fields can 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 object. 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

PlugininInstanceFactory allows a plug-in service to create plug-in instances.

It defines the method:

ManagedPluginInstance createInstance(String pluginInstanceId)

This method is triggered by the createPluginInstance method on the Plug-in Manager MBean. When the createInstance method is invoked, the plug-in service is responsible for creating an instance of the class implementing the ManagedPluginInstance interface.

Interface: PluginServiceLifecycle

PluginServiceLifecycle defines the life-cycle for a plug-in service. See "Understanding the Plug-in States".

Interface: ManagedPluginInstance

ManagedPluginInstance extends the PluginInstance and PluginInstanceLifecycle interfaces. It must be implemented by a plug-in instance.

Interface: PluginInstance

PluginInstance defines a plug-in instance 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 lists are arrays of PluginInterfaceHolder. The respective lists are returned when the getNorthInterfaces() and getSouthInterfaces() methods are invoked.

The plug-in instance is also responsible for implementing the customMatch(RequestInfo requestInfo) method. This method examines the RequestInfo object and decides if the plug-in instance can be used to serve the request. It returns the following constants:

• MATCH_OPTIONAL

  The request is completely stateless and can be served by any plug-in instance.

• 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.

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

The Plug-in Manager invokes the methods in this interface to select the plug-in instance to which it must route the request.

Interface: PluginInstanceLifecycle

PluginInstanceLifecycle defines the life cycle for a plug-in service. See "Understanding the Plug-in States".

Class: RequestFactory

The RequestFactory class processes application-initiated requests both before and after a request is processed in the plug-in. Each communication service must have one implementation of the RequestFactory for each application-facing interface, named according to the pattern: interfacename.PluginFactory, where interfacename is the name of the application-facing interface. A skeleton for the factory is generated by the Platform Developer's Studio Wizard plug-in.

The RequestFactory class has two main functions:

• It packages routing information contained in the request into a RequestInfo object that the Plug-in Manager then uses to select an appropriate plug-in to process the request. See "Class: RequestInfo" 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 RequestInfo object is matched to a plug-in. 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.

  For details see RequestFactory in the ”All Classes” section of the Services Gatekeeper Java API Reference.

  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 in the callback WSDL definitions.

The naming pattern is com.acompany.example.callback.interfacenameCallbackFactory

Where interfacename is name of the interface (such as Notification in Example 2-1). The implementation of the interface is fetched using the following pattern:

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

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

The naming pattern is com.acompany.example.callback.interface nameCallback, where interfacename is name of the interface.

Class: RequestInfo

The RequestInfo object is 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

ServiceType 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.

When they are used, aspects make this service type available in the request thread of each plug-in. The service type is used by various services, including the EdrService. See Services Gatekeeper Application Developer's Guide for the current set of supported interfaces and plug-ins.

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 are needed by the plug-in for correlation purposes and places them in this very short-lived object. Arguments are stored by key and defined when the annotation is set, making it possible to retrieve a particular value. For example, if an argument is annotated with @MapperInfo(C), its value can be retrieved using the key ”C”.

Methods in the plug-in can access this ContextMapperInfo object and retrieve the annotated arguments in order to perform a mapping such as associating a notification with the session ID of the request that established it.

The PluginSouth interface includes one such method, resolveAppInstanceGroupdId.

Interface: RequestContext

This interface defines a RequestContext object which is available in all communication services for both application-initiated and network-initiated requests. This object 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.