| Oracle® Communications Services Gatekeeper Platform Development Studio Developer's Guide Release 5.0 Part Number E16619-02 |
|
|
View PDF |
| Oracle® Communications Services Gatekeeper Platform Development Studio Developer's Guide Release 5.0 Part Number E16619-02 |
|
|
View PDF |
This chapter describes the components, management, and use of the Communication Services used by Oracle Communications Services Gatekeeper:
A Communication Service consists of:
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
Some of these componenents handle application-initiated requests, while others handle network-triggered requests as illustrated in Figure 2-1. Some calls are remote since the modules may be deployed in separate clusters.
The Communication Service common parts are auto-generated based on one or more WSDLs. Application-initiated requests use service WSDLs, while network triggered requests use 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.
Table 2-1 Common Parts of a 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:
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 file. |
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 file. |
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 file. |
Java RMI representation of the Service callback WSDLs. |
Local Java representation of the Callback WSDLs. |
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
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.
Plug-in services have these states:
NEW
STARTED
ACTIVE (ADMIN)
ACTIVE (RUNNING)
The plug-in instances have these states:
NEW
ACTIVE
The state transitions in Figure 2-2 are triggered by:
The start-up sequence of the server in which the plug-in is deployed.
An explicit deployment of the plug-in using the weblogic.Deployer. For details, see “Deploying Applications and Modules with weblogic.Deployer” in Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server at:
http://download.oracle.com/docs/cd/E15523_01/web.1111/e13702/deploy.htm
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 2-2 Plug-in Service State Transitions
| Transition | Triggered by | Descriptions |
|---|---|---|
|
|
Deployment or startup. |
The plug-in service has been created and initialized. The only method that will be called in this state is |
|
|
Deployment or startup |
The plug-in service should perform as much initialization as possible without being externally visible. Examples include: retrieving configuration data, creating internal objects, and initializing stores. |
|
|
Deployment or startup |
The plug-in service should continue activation and become visible, for example register MBeans, without accepting traffic. |
|
|
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. |
|
|
Graceful undeployment/redeployment/stopping That is, by invoking |
The plug-in service should order the plug-in instance to reject new traffic, but continue processing of in-flight work. A When all in-flight work has been processed, the plug-in should get the |
|
|
Forced undeployment/redeployment/stopping That is invoking |
The plug-in service should order the plug-in instance to reject new traffic and to discard in-flight work. |
|
|
Undeployment. |
The plug-in service should deactivate itself, unregister any MBeans and become invisible. |
|
|
Undeployment. |
The plug-in service should perform cleanup and be available for garbage collection. |
The state transitions in Table 2-3 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, a separate document in this set.
Table 2-3 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:
|
|
deactivate |
Destruction of the plug-in instance using the Plug-in Manager MBean. |
The plug-in instance shall:
|
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.
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.
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.
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.
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.
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.
This is the interface a plug-in service must implement.
It extends the interfaces PluginService, PluginInstanceFactory and PluginServiceLifecycle.
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“.
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.
Defines the life-cycle for a plug-in service. See "Plug-in States".
Must be implemented by a plug-in instance.
It extends the interfaces PluginInstance and PluginInstanceLifecycle.
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.
Defines the life-cycle for a plug-in service. See "Plug-in States".
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: interfacename.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 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.
For more information, see the RequestFactory JavaDoc
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.
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.interfacenameCallbackFactory
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;
}
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 nameCallback.
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.
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 2-4 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 |
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, defined when the annotation is set, that makes 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.
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.
Deprecated. Use ManagedPluginService instead.
Allows the plug-in to register itself in the Plug-in Manager. See "Class: AbstractManagedPlugin".
Deprecated. Use ManagedPluginService instead.
Extends ManagedPlugin, implements ServiceDeployable. It makes the plug-in deployable as a service in 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.
These are base classes and annotations for giving the Oracle Communications Services Gatekeeper Administration Console or other JMX tools management access to Communication Services. See Chapter 15, "Making Communication Services Manageable" for more information. Also see the JavaDoc for the packages: com.bea.wlcp.wlng.api.management.*
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 <scs> element defined in the <serviceContract> element 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:
argn.parameter name
where 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.
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.
|
 Copyright © 2007, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|