Extension SDK for BEA WebLogic Network Gatekeeper
|
 |
 |
|
 |
 |
The following sections describe how to extend WebLogic Network Gatekeeper and the different actors involved when creating extensions:
The WebLogic Network Gatekeeper provides an modular software architecture that allows for extensions to the traffic flow stack of the product, all the way from the northbound, application-facing, interface implementations to network protocol plug-ins. See the Product Description for information Architecture and functionality provided by the WebLogic Network Gatekeeper.
The base software modules for a traffic flow stack are:
When extending Network Gatekeeper, several options are available:
Also, a combination of the two latter cases can be an option.
Which option to use depends on several factors.
If a custom northbound, application-facing, interface implementation is being created, it may be sufficient to create just the implementation of the interface and map it to an existing Stateless adapter or Service capability module as outlined in option 2. Things to consider when doing this is that CDRs generated will be identified to come from the Service Capability and SLA data and rules will be the ones offered by the Service Capability.
If the implementation of the northbound, application-facing, interfaces does not sit comfortably on an existing Stateless adapter, it may be necessary to create a whole new traffic path, as outlined in the first option.
If the northbound, application-facing, interfaces provided per default are sufficient, option 3 is suitable.
Since the software module executes in the execution environment offered by the SLEE, the software module needs to implement the interfaces provided by the SLEE and use SLEE utility services as outlined in Interacting with the SLEE and the SLEE Utility Services.
When creating new plug-ins and ESPA Service capabilities, it is also necessary to interact with the Plug-in manager and the SC manager.
The network protocol plug-in implements the protocol specifics, and acts as the telecom network-facing part of the traffic stack in WebLogic Network Gatekeeper.
A plug-in is directly associated with a Service capability, so the plug-in interfaces with one and only one plug-in interface, there are plug-in interfaces for:
If a new service capability is introduced, it has a plug-in interface specific to that service capability.
A plug-in has a set of properties:
All these properties are taken into account by the Plug-in manager when the Service Capability is provided with a plug-in.
Note: Additional parameters, such as routing criteria and policy based routing settings are also taken into consideration when routing a request from a Service Capability to a plug-in. These parameters are configurable in contrast to the properties listed above.
Below is a table outlining the properties.
All plug-ins extends the base module com.incomit.resources.defined in resource_common.idl.
The following modules are mapped to the service capabilities.
All modules contains a set of interfaces to be implemented or used by the plug-in. Refer to the IDL definitions for the plug-in interfaces for detailed information. The IDL files are located in bea\wlng21\esdk\idl\plugin_if.
The following diagram shows the states of a plug-in as defined in the Plug-in Manager.
When the plug-in is in the Active state, the SCs are able to retrieve references to the plug-in and initiate new traffic. When the plug-in is in the Inactive state the SCs will not be able to retrieve any new plug-in references. The plug-in should set itself to inactive when it has lost contact with the underlying network node.
It is possible for the SCs to use existing references (for example call objects) to continue processing any active traffic.
The state of a plug-in does not prevent it from using the SCs to initiate network-triggered events. It only prevents the SCs to create application-initiated events.
Different mechanisms are used when a plug-in changes between the active and inactive states. The state change from active to inactive is only checked when an SC requests to obtain a plug-in. In other words the plug-in have to make sure that the isActive method returns false when it is not active. When a plug-in moves from inactive state to active state it must explicitly invoke the resourceIsActive method. The plug-in must also make sure that the isActive method returns true when active.
It is possible to suspend a plug-in, which means that no new traffic will be sent to the plug-in. For example for call control this means that no new calls will be created, but all active calls will work as normal. This is for instance useful when making a graceful shutdown of a plug-in.
To suspend a plug-in it should simply return false when the isActive method is invoked. To resume from suspended state the plug-in should call resourceIsActive in the PluginRegistration interface. In order for a plug-in to be suspended it must implement ServiceDeploymentExt interface.
It is possible to use the states of a plug-in, see Plug-in states, to perform a HA switch when using an active-standby system. See details about this in section High availability.
This chapter contains common details on the plug-in interfaces. Specific details for each service type (call control, user interaction, etc) are described in separate sections.
To reduce the number of active CORBA objects, a plug-in may use the session id parameter. For example, when a new call is created (either network-triggered or application initiated) the plug-in sends a session id associated with that call. Whenever the proxy communicates with the plug-in it sends this id to the plug-in. This means that only one CORBA instance of the call object will be required. But in this case the plug-in must have some internal dispatching of invocations. Session id works in the same way with, for instance call legs of user interaction calls.
It is up to the developer of the plug-in to decide if session id or multiple objects are to be used. The call back interfaces that the SC implement are always newly created CORBA objects.
Always use timers (SLEETimer) to be able to detect and cleanup resources when no response is received. This is relevant for all layers, not only plug-in
For each method invocation that is made from the SC to the plug-in it is recommended that the plug-in creates a separate thread (or thread pool mechanism) that handles the invocation. This will allow the CORBA thread to return as soon as possible, which reduces the duration that the CORBA threads are blocked in the SC proxy. Most method calls are asynchronous (that is has a request and a response method), which makes this possible.
The SCs use a thread pool to implement this functionality, use the SLEE task manager as described in SLEETaskManager and.SLEETask.
There is a set of help classes for plug-ins that simplifies the implementation. The template for the SLEE service part of a plug-in provided in the extension SDK module templates uses these classes.
The help classes for the network protocol plug-ins simplifies the interaction with the Service Deployable and Service Accessible interface by implementing the general parts of a SLEE Service in help classes.
In the package com.bea.wlcp.wlng.esdk there are two help classes for general SLEE Services. First there is an abstract help class, com.bea.wlcp.wlng.esdk.SleeService that implements the ServiceDeployableExt interface. The purpose of this class is to serve as a base class for general services executing in the SLEE. There is also an abstract help class, com.bea.wlcp.wlng.esdk.Context, that provides methods for getting and setting the POA and for getting the Service Context.
For network protocol plug-ins, there is an abstract base class, com.bea.wlcp.wlng.esdk.plugin.PluginSleeService, that implements the ServiceAccessible interface. It also implements the ServiceDeployableExt interface implicitly through the SLEEService class.
Figure 2-2 SleeService and PluginSleeService inheritance structure
PluginSleeService handles the registration of the plug-in in the plug-in manager. It extends the the abstract class com.bea.wlcp.wlng.esdk.SleeService. There is also an abstract class, com.bea.wlcp.wlng.esdk.plugin.PluginContext, that provides methods for getting and setting the resourceID, as well as declaring methods that should be implemented in the sub-context class.
When using these help classes, there is no need for the implementation classes for a plug-in to implement the ServiceAccessible and ServiceDeployableExt interfaces, instead they should extend the class PluginSleeService.
When a plug-in that extends the PluginSleeService class is started, the method doStarted(...) will be called.
When a plug-in that extends the PluginSleeService class is activated, the method doActivated(...) will be called. The help class PluginSleeService will then handle the registration of the plug-in in the plug-in manager.
When a plug-in that extends the PluginSleeService class is deactivated, the method doDeactivated(...) will be called.
The implementation of the traffic interfaces shall be implemented in a separate class. Whenever the method getTrafficObject() is called on the class the extends the PluginSleeService help class, the class that implements the traffic interfaces shall be instantiated, if the member-variable which holds the reference to the class that implements the traffic interface is not yet instantiated.
The Plug-in Manager is retrieved from the SLEEContext and a task is scheduled that will be performed in a separate thread when the plug-in manager has resolved a suitable plug-in based on the parameters provided. When scheduling the task, information on the type of plug-in to use, priority and so on are defined together with an object that implements the request that shall be forwarded to the plug-in. The object must implement SLEEResourceTask
In the example below this object is task. task implements the method dotask(...), and when the plug-in manager has retrieved a suitable plugin, the plug-in manager invokes the method doTask(...) on this object. The plug-in is provided as an argument to doTask(...). See MyServiceCapabilityManager_impl.java in \module_templates\espa_sc_module_impl\src\com\incomit\espa\my_espa_sc\ for an example.
Listing 2-1 Example of how to get a matching plug-in and to schedule a task
MyServiceCapabilityContext.getServiceContext().getSLEEContext().getResourceManager().scheduleResourceTask(new TrProperty[0],
MyServiceCapabilityContext.PLUGIN_TYPE,
rAddress,
resourceContext,
0, // prio
MyServiceCapabilityContext.POLICY_SERVICE_GROUP,
1,
task,
MyServiceCapabilityContext.getServiceContext());
The following figure includes the interfaces related to the Plug-in Manager.
Figure 2-3 Plug-in manager interfaces
|
Call back interface used to notify that a plug-in has registered or de-registered itself in the Plug-in Manager |
|
|
Implemented by the SCs. Closer descriptions can be found in SC manager. |
This interface is the initial object when accessing the Plug-in Manager.
The base interface that all plug-ins must implement. It is important that all CORBA objects that implement this interface are persistent, that is always use the same IOR. If this is not the case, plug-in routing information, as configured in the Plug-in Manager will not work. This interface is extended by Service Capability-specific parts, so there is one extension per SC type, call control, messaging, user location and so on.
The SCs can implement this interface. This listener interface will be notified when new plug-ins are registered in the Plug-in Manager. This will make it possible for the SC to add itself as a plug-in listener when new plug-ins are activated.
The Resource interface is implemented by the plug-in.
If the plug-in returns false when the isActive method is invoked, it will not be accessible until it is activated.
If a plug-in supports more than one type it should use this registration process for each type.
Figure 2-4 Registration and de-registration of a plug-in
The following sequence diagram shows how application-initiated events are handled. An application-initiated event could for example be creation of a new call or sending an SMS.
The Plug-in Manager maintains a list of routing information for the plug-ins. In this list it is specified what address ranges a certain plug-in supports. The list is specified using the Management Tool.
Figure 2-5 General plug-in usage
Description of the sequence diagram:
The SC Manager is similar to the Plug-in Manager in many ways. The difference is that it manages SCs instead of plug-ins. The main responsibility for the SC Manager is to deliver SC references to the plug-ins when dealing with network-triggered events. The SC Manager contains one part that is used by the SCs for registration an unregistration, and one part that is used by the plug-ins to obtain SCs.
Each SC that wants to be accessed by plug-ins needs to implement the SC base interface. The SC Manager supports registration and de-registration of SCs. The SCs are associated with a certain type that is used when locating the SCs. It is possible to create new SC types from the SLEE Manager.
In the case where several SLEEs are running, each instance will have its own SC Manager. In this case it does not matter which SC Manager is used, as they all share the same information.
It is not necessary for the plug-ins to use the SC Manager at all. It is the choice of the plug-in developer. The SC can register all available call back interfaces directly in the plug-in also. This means that the plug-in can handle the load balancing internally. If an SC is overloaded it will throw an overload exception and the plug-in should try another SC. This may be better for external, not executing in the SLEE, plug-ins for performance reasons as no extra CORBA invocations are needed. The use of the SC Manager is better suited for internal plug-ins as they interact with a pure java interface. It may on the other hand be more convenient to use the SC Manager. There is no need to use both these methods as the reference obtained from the SC Manager and the registered listener will be the same.
The SC Manager is retrieved from the SLEEContext. See The SLEEContext is fetched from the ServiceContext, provided by the SLEE via the ServiceAccessible interface.
Listing 2-2 Getting the SC manager
m_scsManager = m_sc.getSLEEContext().getSCSManager();
Here, m_sc is the ServiceContext. The list of ESPA SCs are retrieved. In the example below all registered listeners of MESSAGING_TYPE are requested. Other ESPA SCs are requested using the same methodology, it is only the type that differs.
Listing 2-3 Example of how to get a list of ESPA Messaging SCs
scsArray = m_scsManager.getSLEESCSDiscovery().getSCSCtx(capabilityProperties,
SCS.MESSAGING_TYPE,
m_eventAny,
m_resourceID);
The code fragment also illustrates how a list of suitable SCs are fetched. The first in the list should be used since the SC manager provides load balancing, although any in the list can be used.
The figure below displays the interfaces related to the SC Manager.
Figure 2-6 SC Manager interfaces
|
Interface used to register an SC. This interface will not be closer described in this document. |
|
An object implementing the SCSMgr interface is the initial object in the SC Manager. This interface is used to access other SCSMgr instances and to retrieve the registration and discovery interfaces.
This is interface is used by the ESPA SC to registers into the SC manager.
This is interface is used by the plug-ins to retrieve references to SC instances. SCs retrieved with this interface will ensure that load balancing is applied to network-initiated traffic.
|
Retrieve all SCs that have enabled a criteria matching the supplied parameters. |
|
The following sequence show how a network-triggered event is distributed to an SC using the SC manager.
Figure 2-7 Figure Network-triggered event
The Service capabilities are responsible for implementing the Policy Enforcement Points, storing CDRs and to hold session information that is beyond the scope of the plug-ins.
Examples if this is user interaction sessions and call control sessions, which are of less transient nature than for example sending of SMSs or positioning requests.
The existing Service capabilities are stateful.
The service capabilities registers themselves with a certain type, that is used to bind a plug-in to a Service capability.
The stateful adapters (or SESPA) are used to provide a stateless interfaces towards the service capabilities. SESPA presents a stateless interface to the Web Services implementation.
Per default there is a one to one mapping between Stateless adapters and Service capability modules.
If the standard Network Gatekeeper is extended with a Web Services or pure HTTP interface that fits on top of an existing Service Capability, the extended interface can be implemented on top of this interface.
In the standards product, the Parlay X implementation is using this interface.
The Web Services implementations are deployed in the Tomcat server embedded in the SLEE.
|
|
|
