|
|
This chapter provides a description of a Communication Service and its components:
A Communication Service consists of a set of components:
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.
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:
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.
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.
|
|||
Accepts requests from the Service Web Service implementation and propagates them to the appropriate plug-in using the Plug-in Manager.
This functionality must be implemented in the PluginFactory class, which extends Class: RequestInfo.
|
|||
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. |
|||
|
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.
Packaged into a single JAR file for the Communication Service. |
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:
The plug-in instance is a class that implements com.bea.wlcp.wlng.api.plugin.ManagedPluginInstance. It has:
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.
A plug-in service is in one of a distinct set of states:
The plug-in instance is in one of the following states:
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. |
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.
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:
The plug-in service maintains a:
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:
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)
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"Factory that allows a plug-in service to create plug-in instances.
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 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:
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:
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 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: <myinterfacename>.PluginFactory. A skeleton for the factory is generated by the Eclipse plug-in.
The RequestFactory has two main functions:
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-insmergeResults: 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. |
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:
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 name>Callback
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:
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.
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.
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 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.
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 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:
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
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.
|