Extension SDK for BEA WebLogic Network Gatekeeper
|
 |
 |
|
 |
 |
The Extension SDK for WebLogic Network Gatekeeper consists of template source code and build tools that assists the creation of WESPA modules, SESPA modules, ESPA service capabilities, and network plug-ins that execute in WebLogic Network Gatekeeper. It also contains examples of a Policy utility class that can be used from Policy rules.
The template source code illustrates how a request from an application is propagated through the internal layers of the Network Gatekeeper down to the plug-in. It also illustrates how a network initiated request is propagated from the plug-in, through the different layers and up to an application. The network initiated part of the templates also illustrates how the application registers to listen to network initiated events.
The following sections contain descriptions of the Extension SDK templates:
Understanding of the network plug-in, ESPA service capability module, SESPA module, and WESPA module concepts as outlined in WebLogic Network Gatekeeper Product Description.
All template source code is written in Java and some modules use CORBA, so experience with Java and CORBA is essential.
The build environment is based upon the Ant build tool, so experience with Ant and Ant build files is necessary.
Orbacus 4.1.2 or 4.3 must be installed.
Java 2 SDK 1.4.2 must be installed.
It is necessary to have working knowledge of how to handle the WebLogic Network Gatekeeper.
When deploying software modules created with the Extension SDK, the software modules must be deployed to a WebLogic Network Gatekeeper 2.1 with the following patches installed:
The following prerequisites must be fulfilled before starting to install an Extension SDK:
esdk21_wlng21.zip to the file system. The file is extracted to the directory bea\wlng21\esdk. The directory structure described in Directory structure for the templates on page 15-15 is created.Note: A password is required to extract this file. The password was provided when you ordered Extension SDK for Network Gatekeeper and can also be obtained from the BEA eLicense system.
<Orbacus installation path>\bin.ANT_HOME environment variable to the Ant directory provided by the Extension SDK. The ant directory is located in <install path to Extension SDK>\bea\wlng21\esdk\dev_tools\ant<install path to Extension SDK>\bea\wlng21\esdk\dev_tools\ant\bin.
There are some alternatives when extending the WebLogic Network Gatekeeper:
An overview of the WebLogic Network Gatekeeper software architecture supporting the above extension alternatives is shown in Figure 15-1.
Figure 15-1 Software module and interface overview
WebLogic Network Gatekeeper is designed around a layered architecture model. This is reflected in the Extension SDK.
The southern most layer, the plug-in layer, contains logic for communication with underlying network systems. The interface between the ESPA Service Capability and the plug-in, the plug-in interface, is an asynchronous CORBA interface used for communication with the service capability layer, and is defined in my_plugin_if.idl. The south bound interface of a plug-in is undefined and depends on the underlying network system. Each plug-in specifies it's type (for example CALL_CONTROL) and it's supported address plans (for example E164). The type can be customized and could be any string. Based on these criteria, plug-ins are accessed from the service capability layer.
The middle most layer, the service capability layer, enforces traffic restrictions and policies. On the northbound side of the service capability layer is the CORBA based ESPA interface and the south bound is the plug-in interface. ESPA service capability implementations register themselves in the ESPA access framework from which they can be accessed, ensuring that they can only be accessed after client authenticity has been assured by ESPA access. ESPA service capabilities can for each service request get a a plug-in that the request shall be mapped onto based on plug-in type and address plan as described above.
The Extension SDK can be used to create web services based access interfaces. These interface modules are divided in two, one SESPA part which makes a stateless native Java representation of the ESPA CORBA interface, and one web services part (WESPA) executing in Tomcat/Axis.
The south bound interface of the SESPA layer is hence the ESPA interface. The northbound SESPA interface is defined using plain java classes. WESPA will access SESPA from the web services environment executing in Tomcat/Axis, therefore both SESPA and WESPA must be loaded in the same Java class loader. A utility in the SLEE is used for this purpose, the SLEE CommonLoader. The WESPA services' northbound interface is defined in plain java files, from which WSDL files are generated. A client can use the WSDL files to generate it's own stubs in the language it uses.
describe the flow through the template software modules provided in the module_templates directory in the Extension SDK. Use the decription together with the code provided in the templates.
For the application initiated requests, the template exposes two methods to an application in the WESPA service capability, myMethod(...) and myMethodWait(...). The method myMethod(...) returns the result asynchronously via a call to the Web Service method myMethodResult(...), or if an error has occurred via myMethodError(...). The corresponding calls are tied together via an assignment ID given by the application in myMethod(...) and provided as parameters in myMethodResult(...) and MyMethodError(...). The methods myMethodResult(...) and MyMethodError(...) are calling a Web Service that shall be implemented by the application.
The method myMethodWait(...) returns the result synchronously via the return value. The WESPA implementation calls the corresponding methods myMethod(...) and myMethodWait(...) exposed by the SESPA Service Capability module. These calls are pure Java calls.
The application must login to the WESPA Access module prior to calling myMethod(...) or myMethodWait(...).
See Network Gatekeeper Developer's Guide for Extended Web Services and Network Gatekeeper API Description for Extended Web Services for information on how to login to WESPA Access.
If the login was successful, a login ticket representing the session is returned. The login ticket must be provided by the application in every consecutive call to the WESPA module. The ticket is provided in the SOAP header and is retrieved by calling the method getCurrentSessionId() in com.bea.wespa.util.SOAPHeaderHandler. The session ID returned is provided as a parameter to the call to both myMethodWait(...) and myMethodWait(...) exposed by the SESPA service capability.
For the application initiated requests, the template exposes two methods to the WESPA module in the SESPA service capability, myMethod(...) and myMethodWait(...). The method myMethod(...) returns the result asynchronously via a call to the WESPA method myMethodResult(...), or if an error has occurred via myMethodError(...). The corresponding calls are tied together via an assignment ID given by an application in myMethod(...) and provided as parameters in myMethodResult(...) and MyMethodError(...). The method myMethodWait(...) returns the result synchronously via the return value. The SESPA implementation calls the method myMethod(...) exposed by the ESPA Service Capability module.
For the method myMethodWait(...) exposed to the SESPA module, the asynchronous method myMethod(...) exposed by the ESPA module is called. The SESPA module waits for the ESPA module to call either the method myMethodResult(...) or myMethodError(...) on the SESPA modules listener interface until returning. The method could also return if the timer associated with the call to myMethodWait(...) expires. It is important to convert any, from an application point of view, synchronous calls to asynchronous as early as possible, in order to block as few threads as possible in the Network Gatekeeper. This means that these conversions should be done in the SESPA layer.
For each traffic method invocation, the SESPA service capability module retrieves the CORBA client session objects from the login ticket. First, the application session object is retrieved using the database helper utility defined in com.incomit.sespa.util.DbHelper. The object is provided in the constructor of MyServiceCapabilityImpl. By calling getApplicationSession(...) the application session object is returned. This object is provided as a parameter in when the traffic method request is propagated to the ESPA service capability module. The ESPA Manager object is also retrieved using the database helper utility. By calling getEspaManager(...) on the database helper utility the correct ESPA Manager object is returned. The Manager object is found based on the login ticket and the SLEE service name the ESPA Service capability module is registered under. The traffic method request is performed on the ESPA Manager object.
For the application initiated requests, the template exposes one asynchronous method, myMethod(...), to the SESPA module. The result of the method myMethod(...) is reported asynchronously via a call to the SESPA callback method myMethodResult(...), or if an error has occurred via myMethodError(...).
The method myMethod(...) calls an internal method, myMethodInternal(...) which implements a Policy Enforcement Point. If the request is allowed, the class MyServiceCapabilityPluginTask is instantiated and provided in the request to scheduleResourceTask(...) on the plug-in manager. When the plug-in manager has found a suitable plug-in and allocated a task, the SLEE will call doTask(...) on MyServiceCapabilityPluginTask. A reference to the plug-in is provided as an argument to doTask(...). In the doTask(...) method, the ESPA service capability module call the method myMethodReq(...) exposed by the plug-in. The result of the call to the method myMethodReq(...) is reported asynchronously to the call back interface implementation MyPluginListener_impl via the methods myMethodRes(...) or myMethodErr(...).
For each traffic method invocation, the SESPA service capability module checks if the ESPA service capability module is suspended and if it is overloaded. If not, it checks if the application session is valid. This is done by calling checkSessionValidity(...) on the ESPA utility class com.incomit.espa.util.ApplicationSessionValidityHelper.session. The Application session object is provided as a parameter in each traffic method invocation.
For the application initiated requests, the template exposes one asynchronous method, myMethodReq(...), to the ESPA module. The method myMethodReq(...) schedules a new task using scheduleSLEETask(...) on the SLEE Task Manager. As an argument to scheduleSLEETask(...) is an instance of MyMethodReqTask which is the class that will perform the actual protocol-specific communication with the underlying network node. In MyMethodReqTask the method doTask(...) will be invoked when the SLEE Task manager has assigned a new task. In the implementation of doTask(...), the interface to the Web Services part of the plug-in is fetched from the SLEE Common Loader via a call to SleeCommonLoader.getInstance().getObject(OBJ_NETWORK_INTERFACE). The Web Services part of the plug-in is called via myNetworkMethod(...) and a call to the call-back is performed via a call to myMethodRes(...) on the listener object.
In the Web services part of the network plug-in, the communication with the underlying network node takes place.
The SLEE services part of the network plug-in called the method myNetworkMethod(...) in the class NetworkInterfaceImpl. This method class the underlying node via a Web Services call and returns the result to the SLEE services part of the network plug-in.
The network triggered part of the template is divided into two parts, a registration part where an application registers for network initiated events the traffic flow part where a request reaches the network plug-in and is propagated through the template traffic path up to an application. The registration part is initiated by the application and described below. The traffic path is described in Traffic flow for network triggered requests.
For the registration for network triggered notifications, the template exposes two methods to an application in the WESPA service capability, enableNetworkTriggeredEvents(...) and disableNetworkTriggeredEvents(...). The method enableNetworkTriggeredEvents(...) returns a ticket identifying the notification. The method disableNetworkTriggeredEvents(...) removes the registration for network initiated notifications. The WESPA implementation calls the corresponding methods enableNetworkTriggeredEvents(...) and disableNetworkTriggeredEvents(...) exposed by the SESPA Service Capability module. These calls are pure Java calls.
The application must login to the WESPA Access module prior to calling enableNetworkTriggeredEvents(...) or disableNetworkTriggeredEvents(...). See the Network Gatekeeper development documentation for information on how to login to WESPA Access. If the login was successful, a login ticket representing the session is returned. The login ticket must be provided by the application in every consecutive call to the WESPA module. The ticket is provided in the SOAP header and is retrieved by calling the method getCurrentSessionId() in com.bea.wespa.util.SOAPHeaderHandler. The session ID returned is provided as a parameter to the call to both enableNetworkTriggeredEvents(...) and disableNetworkTriggeredEvents(...) exposed by the SESPA service capability.
For the registration part for network triggered notifications, the template exposes two methods to the WESPA module in the SESPA service capability, enableNetworkTriggeredEvents(...) and disableNetworkTriggeredEvents(...). When the method enableNetworkTriggeredEvents(...) is invoked, an object representing the notification, NotificationInfoId, is created and a check is performed that there are not other applications that have registered for notifications with the same criteria using getIdenticalNotifications(...) on the helper class MyServiceCapabilityPersistentStorage. If there are identical notification criteria, and the notification is created by the same application, the notification is fetched from the database by calling getNotification(...) on the helper class MyServiceCapabilityPersistentStorage. The listener object is created using the method internalAddNetworkListener(...) and the listener is stored in the database using storeNotification(...) on the helper class MyServiceCapabilityPersistentStorage. An event is broadcasted to other instances of the SESPA module via a call to generateEnableNotificationEvent(...) on the event helper class MyServiceCapabilityEventHelper. The method internalAddNetworkListener(...) creates a listener object from the class MyESPAServiceCapabilityNetworkListener_impl.
When the ESPA Service capability module becomes activated, it registers the callback interface for the communication between the plug-in and the ESPA Service Capability module. The listener object is registered in the SC manger. The plug-in will query the SC manager for a suitable ESPA Service capability when a network triggered event occurs.
For the registration part for network triggered notifications, the template exposes two methods to the SESPA module in the ESPA service capability, addNetworkTriggeredEventListener(...) and removeNetworkTriggeredEventListener(...). When the method addNetworkTriggeredEventListener(...) is invoked a check that the application session is valid is performed. After this check, the method addNetworkTriggeredEventListenerInternal(...) is invoked. This method implements the Policy Evaluation Point and enables the notification via the NotificationHandler class. This class handles distribution of events between the different instances of the ESPA Service Capability module. The events are distributed when one of the following occurs:
NotificationHandler holds a hashtable, represented by the variable m_notifications, containing registered notifications and callback interfaces. The NotificationHandler class distributes the details about the notification, such as which application that has requested the notification and stores the information in the database using the NotificationHelper class and distributes the notification information to all other instances of the ESPA service capability module via the SLEE Event Handler. The event is created using generateEvent on the SLEE event channel.
The processEvent(...) method in the class NotificationHandler listens to the events and updates the instance of the ESPA Service Capability module according to the events.
The SLEE service part of the network protocol plug-in is not involved when registering for network triggered notifications. A listener, MyWPluginNetworkTriggeredEventListenerImpl, is instantiated and registered in the SLEE Common loader when the SLEE service is instantiated. The plug-in also registers in the Plug-in manager when it becomes activated.
The Web Services part of the plug-in registers the implementation of the network triggered interface NetworkInterfaceImpl and MyWPluginNetworkTriggeredEventResultListenerImpl in the SLEE Common Loader, when MyWPluginServlet.init(...) is called at startup of the servlet.
The network triggered part of the template is divided into two parts, a registration part where an application registers for network initiated events and the traffic flow part where a request reaches the network plug-in and is propagated through the template traffic path up to an application. The traffic flow is described below and the registration part is described in Registration flow for network triggered requests.
The network node performs the Web Services call myDeliverNetworkTriggeredEventMethod on the Web Service implemented in the Web Services part of the plug-in. The Web Service is bound to the class NetworkTriggeredEventListenerSoapBindingImpl.
The method myDeliverNetworkTriggeredEventMethod(...) is invoked on the class NetworkTriggeredEventListenerSoapBindingImpl. Via the method NetworkTriggeredEventListenerSoapBindingImpl.nameLookUp() the object in the SLEE service part of the plug-in is retrieved from the SLEE Common Loader via the name, OBJ_NETWORK_TRIGGERED_EVENT_LISTENER
The object in the SLEE Service part of the plug-in, implemented in MyWPluginNetworkTriggeredEventListenerImpl was registered in the SLEE Common loader when it was activated.
The Web Services part of the plug-in has performed a call to MyWPluginNetworkTriggeredEventListenerImpl.myDeliverNetworkTriggeredEventMethod(...).
MyWPluginNetworkTriggeredEventListenerImpl, which implements the listener for network triggered events, was instantiated and registered in the SLEE Common Loader when the SLEE service part of the plug-in was activated, that is when doActivated() is invoked by the SLEE on the class MyPluginSleeService.
The class DeliverNetworkTriggeredEventTask is instantiated and provided as a scheduled task to the SLEE Task Manager via a call to scheduleSLEETask(...).
In DeliverNetworkTriggeredEventTask the method doTask(...) is invoked when the SLEE Task manager has assigned a new task.
In DeliverNetworkTriggeredEventTask.doTask() the class MyPluginNetworkTriggeredEventResultListenerImpl is instantiated. This class is used by the ESPA SC to send back responses to the plug-in describing the outcome of the request.
DeliverNetworkTriggeredEventTask.getListener().myDeliverNetworkTriggeredEventMethod(...) is invoked, where DeliverNetworkTriggeredEventTask.getListener() asks the SC manager for an object in the ESPA SC that listens for network initiated request and returns the listener. This object is instantiated from the class DeliverNetworkTriggeredEventTask in ESPA.
The class MyPluginNetworkTriggeredEventListener_impl implements the listener object the SLEE service part of the plug-in calls when new network initiated events arrives. The class was instantiated and registered in the SC manager when it was activated.
The SLEE service part of the plug-in calls MyPluginNetworkTriggeredEventListener_impl.myDeliverNetworkTriggeredEventMethod(...) where the class DeliverNetworkTriggeredEventTask is instantiated and provided as a scheduled task to the SLEE Task Manager via a call to scheduleSLEETask(...).
In DeliverNetworkTriggeredEventTask the method doTask(...) is invoked when the SLEE Task manager has assigned a new task.
First, DeliverNetworkTriggeredEventTask.doTask() calls internalNotificationArrived(...) on the singleton class NotificationHandler.
The method NotificationHandler.internalNotificationArrived(...) checks if any application has registered for notifications for the events via the method NotificationHandler.findEnabledNotification(...). The method findEnabledNotification(...) returns a list of notifications enabled by the applications.
NotificationHandler.findEnabledNotification(...) checks in the Hashtable m_notifications for notifications registered by the applications. The method returns an object of type MyServiceCapabilityNotification which holds information on which application has registered for notifications and an array of IORs to the SESPA listeners that represents the listeners registered by the applications.
A Policy Evaluation Point is implemented where it is verified if the application is permitted to receive notifications. If the policy rules denies the request, a CDR is generated that the notifications could not be delivered because of a policy violation. If the policy rules permits the request, the method NotificationHandler.executeNotificationArrived(...) is invoked.
In NotificationHandler.executeNotificationArrived(...) the class MyServiceCapabilityNetworkTriggeredEventResultListenerImpl is instantiated. This object is used by the SESPA SC to report successful or failed deliveries of notifications to the ESPA SC. The method MyServiceCapabilityNotification.getCallback() is invoked. This method returns a SESPA object representing a callback that SESPA has registered for an application. MyServiceCapabilityNotification.getCallback() returns the IOR to the SESPA listeners that corresponds to a listener registered by an application.
If no such object is returned, MyServiceCapabilityNetworkTriggeredEventResultListenerImpl.myDeliverNetworkTriggeredEventMethodError(...) is called.
If a callback object is found, the method MyServiceCapabilityNetworkTriggeredEventListener.myDeliverNetworkTriggeredEventMethod(...) is called to the SESPA SC.
The class MyESPAServiceCapabilityNetworkTriggeredEventListener_impl implements the listener object in the SESPA module. The class was instantiated and provided to ESPA when the application enabled the network triggered event listener.
ESPA calls myDeliverNetworkTriggeredEventMethod(...) on the object instantiated from the class MyESPAServiceCapabilityNetworkTriggeredEventListener_impl where the class DeliverNetworkTriggeredEventTask is instantiated and provided as a scheduled task to the SLEE Task Manager via a call to scheduleSLEETask(...).
In DeliverNetworkTriggeredEventTask the method doTask(...) is invoked when the SLEE Task manager has assigned a new task.
First, DeliverNetworkTriggeredEventTask.doTask() calls MyESPAServiceCapabilityNetworkTriggeredEventListener_impl.getNextCallback() which returns an object instantiated from the class MyServiceCapabilityCallbackInfo. The method gets the object from the AbstractList m_callbackList which holds a list of object instantiated from the class MyServiceCapabilityCallbackInfo. The class MyServiceCapabilityCallbackInfo holds information about the notification ticket and the endpoint of the Web Service implemented by the application that enabled network triggered notifications.
Then the object in the WESPA SC that performs the Web Services call to the application is fetched from the SLEE Common loader. The object returned is instantiated from the class MyServiceCapabilityNetworkTriggeredEventListener. The method myDeliverNetworkTriggeredEventMethod(...) is invoked on the class MyServiceCapabilityNetworkTriggeredEventListenerImpl in the WESPA SC.
After the calls has been returned from the WESPA SC, and the application, the method myDeliverNetworkTriggeredEventMethodResult(...) is called on the object provided as result listener. This object is instantiated from the class MyServiceCapabilityNetworkTriggeredEventResultListenerImpl. The method passes the result to the plug-in.
The class MyServiceCapabilityNetworkTriggeredEventListenerImpl implements the method myDeliverNetworkTriggeredEventMethod(...). This method is called from the SESPA SC module.
myDeliverNetworkTriggeredEventMethod(...) calls getMyScNetworkListener(...) which returns an object instantiated from MyServiceCapabilityNetworkTriggeredEventListener.
getMyScNetworkListener uses the Axis generated class MyServiceCapabilityNetworkTriggeredEventListenerServiceLocator to create a proxy object for the application Web Service.
Finally the call to the Web Service implementation in the application is performed using a call to MyServiceCapabilityNetworkTriggeredEventListener.myDeliverNetworkTriggeredEventMethod(...). When the application has returned the call, the execution proceeds in the ESPA SC module.
The following directory structure is used for the Extension SDK.
dev_tools\
doc\
eclipse\
idl\
espa_if\
plugin_if\
lib\
module_templates\
build\
client_impl\
espa_sc_if\
espa_sc_impl\
network_if\
network_simulator_impl\
plugin_if\
plugin_impl\
policy\
rules\
sla\
policy_util_impl\
sespa_sc_if\
sespa_sc_impl\
wespa_sc_if\
wespa_sc_impl\
wplugin_if\
wplugin_impl\
thirdparty\
wsdl\
The actual templates for the services are found under module_templates.
For each module there is an ant build file in build.xml directly under each module.
Source code is found under src and IDL interface files are found under idl. Any stubs generated from IDL files will be put under a directory generated, while compiled class files and packaged jar files will be stored under lib.
Below is a description of the individual directories
Directly under module_templates\build there are two files:
.build.xmlThis is a main build file for the entire Extension SDK. This build file prepares the environment by extracting necessary jar files under lib, and builds all targets under module_templates. Note that each module may be built by itself under module_templates\<module_name>\build, but this file must be built once initially to do the preparations.
build.propertiesmodule_templates\client_implContains templates for the an application using the interfaces exposed by the Web Services interfaces.
module_templates\espa_sc_if module_templates\espa_sc_impl module_templates\network_ifContains example WSDL interface descriptions for the communication between the Web Services part of the plug-in to an example network node (the example network simulator application).
module_templates\network_simulator_implmodule_templates\plugin module_templates\plugin_ifmodule_templates\policymodule_templates\policy_util_implmodule_templates\sespa_sc_ifmodule_templates\sespa_sc_implmodule_templates\wespa_sc_ifmodule_templates\wespa_sc_impl module_templates\wespa_sc_impl module_templates\wplugin_if Contains templates for the interface part of the plug-in that executes in Tomcat (Web Services part).
module_templates\wplugin_impl Contains templates for the implementation part of the plug-in that executes in Tomcat (Web Services part).
libthirdpartywsdl
A network plug-in collaborates with a set of actors:
The plug-in is built-up by a set of classes and IDL-files.
The SLEE Service part of the plug-in uses a set of utility classes that implements the Basic SLEE services interfaces ServiceDeployable and ServiceAccessible, and extends these classes as described in Help classes for network plug-ins.
This template file defines the interfaces between the network plug-in and the ESPA service capability module.
The module definitions in this file are used by both the ESPA service capability module implementation and the plug-in implementation. The template holds these interfaces:
MyPluginListener, MyPlugin, and MyPluginNetworkListener
MyPlugin is used by the ESPA service capability module to invoke methods on the plug-in. The method definition myMethodReq serves as a template for an asynchronous method request. It uses the parameter assignmentID to keep track of corresponding requests and responses. The parameter MyPluginListener is the callback interface as defined in the interface MyPluginListener.
MyPluginListener is used by the plug-in to invoke callback methods implemented by the ESPA service capability module. It holds two template methods:
myMethodRes is invoked upon successful completion of a method invocation and myMethodErr is invoked upon a failed completion of a method invocation.
It is the responsibility of the plug-in to invoke these methods, while it is the responsibility of the ESPA service capability module to implement them.
MyPluginNetworkListener is used by the plug-in to invoke methods implemented by the ESPA service capability module when network triggered events arrives to the plug-in. It holds the method:
myDeliverNetworkTriggeredEventMethod which is invoked when the plug-in receives a network initiated event. It is the responsibility of the plug-in to invoke this method, while it is the responsibility of the ESPA service capability module to implement it.
The purpose of this file is to define the interface between the plug-in and the OAM functionality of the SLEE. Methods defined in this interface will be accessible via the Network Gatekeeper OAM interface and the Management Tool.
The module definition in this file reflects the module definition in the plug-in interface.
Location: plugin_impl\src\com\acompany\plugin\myplugintype
Implements the class MyPluginContext. The purpose of this class is to define the service context for the plug-in and to hold data that is global for the plug-in. This class extends the wrapper class PluginContext. The following static variables are defined:
PLUGIN_TYPE defines the plug-in type that the plug-in specifies when registering in the plug-in manager. Service capability implementations will use this type identifier when retrieving plug-ins for handling service requests. The type must match one of the allowed types in the plug-in manager service. Custom types are allowed, but must be registered in the plug-in manager.ADDRESS_PLANS is an array holding information on the address plans supported by the plug-in. Example: Possible values are defined in the JavaDoc for the plug-in interfaces.
The package name reflects the module definition in the plug-in interface.
Location: plugin_impl\src\com\acompany\plugin\myplugintype
Implements the class MyPluginSleeService. The purpose of this class is to implement the state control of the plug-in as a SLEE service and to instantiate and provide a reference to the class that implements the traffic interface, the class MyPlugin_impl.
When the service gets activated and started, when the doActivated() and doStarted() methods are invoked, it creates the object that listens for network initiated traffic from the class MyPluginNetworkTriggeredInterfaceImpl, and it registers it in the SLEE Common Loader so it will be accessible by the Web Services part of the plug-in. See Plug-ins that executes as a SLEE service and a web application for more information about interaction between the web application part of a plug-in and the SLEE service part of a plug-in.
Location: plugin_impl\src\com\acompany\plugin\myplugintype
Implements the class MyPlugin_impl. The purpose of this class is to implement the traffic interface of the plug-in as a SLEE service and to implement the plug-in interface used by the ESPA service capability. The template implements the plug-in interface, used by the ESPA service capability module. The actual logic is performed in a separate class, MyMethodReqTask. This task class is scheduled as a SLEE task. The SLEE will put it in it's transaction queue and assign a thread to it and let it execute in due time.
public void myMethodReq(....) {
...
MyMethodReqTask task = new MyMethodReqTask(Context.getServiceContext(), listener, address, data, assignmentID);
Context.getServiceContext().getSLEEContext().getTaskManager().scheduleSLEETask(task);
...
}
The class MyMethodReqTask performs the actual processing. See MyMethodReqTask.java.
Since the implementation of the interface used by the ESPA service capability module resides in this class, the class must extend the generated POA implementation of the IDL interface:
public class MyPlugin_impl extends MyPluginPOA
The POA name MyPluginPOA reflects the name of the plug-in interface. In this case MyPlugin. See the description of my_plugin_if.idl.
The methods defined in the plug-in interface are implemented here. The method myMethodReq serves as a template for all methods to be used in the plug-in interface. All methods defined in the plug-in interface must be implemented here. Also the corresponding callback interface must be used. For example, the method myMethodReq and the callback interface myPluginListener is defined in the plug-in interface, and myMethodReq method signature is:
myMethodReq(.,., int assignmentID, MyPluginListener, listener)
The assignmentID is used to keep corresponding requests and responses together.
Location: plugin_impl\src\com\acompany\plugin\myplugintype
Implements the class MyMethodReqTask. This class performs the operations towards the Web Service part of the plug-in. It is implemented in a separate class in order to use the SLEE task processing functions for asynchronous operations. It fetches the object that defines the interface to the Web Services part of the plug-in from the SLEE Common Loader and calls the method myNetworkMethod implemented in the Web Services part of the plug-in.
The package name reflects the module definition in the plug-in interface.
Location: plugin_impl\src\com\acompany\plugin\myplugintype
Implements the class DeliverNetworkTriggeredEventTask. The purpose of this class is to deliver an network triggered event to the ESPA SC via the SC manager.
Location: plugin_impl\src\com\acompany\plugin\myplugintype
Implements the class MyPluginNetworkTriggeredEventResultListenerImpl. The purpose of this class is to receive the result from a previously delivered network triggered event from the ESPA SC. The results are processed in the methods myDeliverNetworkTriggeredEventMethodResult(...) and myDeliverNetworkTriggeredEventMethodError(...). Both these methods schedules SLEE Tasks that performs the actual processing, in the classes MyDeliverNetworkTriggeredEventMethodResultTask and MyDeliverNetworkTriggeredEventMethodErrorTask.
Location: plugin_impl\src\com\acompany\plugin\myplugintype
Implements the class MyWPluginNetworkTriggeredEventListenerImpl. The purpose of this class is to receive notifications on network triggered events from the Web Services part of the plug-in and to schedule a SLEE Task on the class DeliverNetworkTriggeredEventTask when a notification arrives.
Location: plugin_impl\src\com\acompany\plugin\myplugintype
Implements the class MyPluginOAM_impl. The purpose of this class is to implement the OAM methods that are offered towards the plug-in.
The package name reflects the module definition in the plug-in interface.
Location: wplugin_impl\src\com\acompany\wplugin\myplugintype
The purpose of this file is to propagate the result a previously delivered network initiated requests to the network node.
Location: wplugin_impl\src\com\acompany\wplugin\myplugintype
The purpose of this file is to add the object implementing the interface the SLEE service part of the plug-in uses to propagate the request to the Web Services part of the plug-in. The object is added to the SLEE Common loader in the init(...) method of the servlet.
Location: wplugin_impl\src\com\acompany\wplugin\myplugintype
The purpose of this file is implement the interface to the network node.
Location: wplugin_impl\src\com\acompany\wplugin\myplugintype
This class implements the Web Service called by an underlying network node when network initiated requests arrives. It implements the Web Service method myDeliverNetworkTriggeredEventMethod(...) and calls the corresponding method implemented in the SLEE Service part of the plug-in.
An ESPA service capability module collaborates with the following set of actors:
The ESPA service capability module is built-up by a set of classes and IDL-files.
Location: espa_sc_module_if/idl
This template file defines the interfaces between the ESPA service capability module and a SESPA module.
The module definitions in this file are used by both the ESPA service capability module implementation and the SESPA module.
In contrary to the plug-in interface, which is asynchronous only, the ESPA interface offers both synchronous and asynchronous request methods to it's clients (SESPA in this case). A client that uses the synchronous request method (see below) does not have to implement or use the callback interface.
The template holds two interfaces for southbound requests:
The MyServiceCapabilityManager interface is used by a SESPA module to invoke methods on the ESPA service capability module. It contains the methods:
myMethod, a template for an asynchronous method request. It returns an assignmentID to keep track of corresponding requests and responses.addNetworkTriggeredEventListener, for enabling listeners for network triggered events.removeNetworkTriggeredEventListener, for removing listeners for network triggered events.The MyServiceCapabilityListener interface is used by the ESPA service capability module to provide the result of an asynchronous method invocation made by a SESPA module. It contains two methods:
myMethodResult and myMethodError.
myMethodResult is invoked upon successful completion of an asynchronous method invocation and myMethodError is invoked upon a failed completion of an asynchronous method invocation.
For network initiated traffic three are two interfaces:
MyServiceCapabilityNetworkTriggeredEventListener, for forwarding network initiated requests to the SESPA SC.MyServiceCapabilityNetworkTriggeredEventResultListener, for delivering the result of previously delivered network triggered notifications.
The purpose of this file is to define the interface between the ESPA service capability module and the OAM functionality of the SLEE.
Location: espa_sc_impl\src\com\acompany\espa\mysctype
Performs charging, that is generate Charging Data Records (CDRs).
Location: espa_sc_impl\src\com\acompany\espa\mysctype
Delivers notifications on network triggered events to the SESPA SC.
Location: espa_sc_impl\src\com\acompany\espa\mysctype
Listens for network triggered notifications from the plug-in and orders to the SLEE Task Manager to execute doTask in DeliverNetworkTriggeredEventTask.
Location: espa_sc_impl\src\com\acompany\espa\mysctype
Listens for results of previously delivered network triggered notifications.
Location: espa_sc_impl\src\com\acompany\espa\mysctype
This file holds a class that implements the plug-in callback interface (MyPluginListener_impl). It also handles a supervision timer on request invocations towards the plug-in to avoid session hangs if the plug-in fails to deliver a result or error callback.
It delivers the result to the ESPA listener in SESPA. For result deliverance to the ESPA clients, it uses an the inner helper class MyMethodResultTask and MyMethodErrorTask.
Location: espa_sc_impl\src\com\acompany\espa\mysctype
This class implements the OAM interface of the ESPA service capability. It utilizes the MyServiceCapabilityPersistentStorage class to store data of persistent nature in the database.
Location: espa_sc_impl\src\com\acompany\espa\mysctype
This file holds a helper class used for storing and retrieving configuration data in the database.
Location: espa_sc_impl\src\com\acompany\espa\mysctype
This file holds the class serving as the service deployable interface. It handles notifications about SLEE service state change and also implements the ESPA Service interface defined in ESPA Access. This interface must be supported by any service that should be accessible via the ESPA Access framework.
Location: espa_sc_impl\src\com\acompany\espa\mysctype
This file contains a class with methods for distributing events to other ESPA SCs. It broadcasts and listens to events originating from an application adding or removing listeners for network triggered events. It uses incoming network triggered notifications from the network plug-in and connects them with listeners that has been registered by the SESPA SC.
Location: espa_sc_impl\src\com\acompany\espa\mysctype
This file implements the server part of the MyServiceCapabilityManager interface. It implements the Policy Enforcement Point (PEP) and utilizes an inner helper class MyServiceCapabilityPluginTask for performing the actual invocations towards the plug-in.
The following line schedules the helper class as a SLEE resource task, which causes the SLEE to obtain a plug-in according to the type defined in PLUGIN_TYPE and executes the task from a separate thread:
getResourceManager().scheduleResourceTask(new TrProperty[0],
MyServiceCapabilityContext.PLUGIN_TYPE,
TrAddress,
resourceContext,
0, // prio
MyServiceCapabilityContext.POLICY_SERVICE_GROUP,
1, // sendlist size
task,
MyServiceCapabilityContext.getServiceContext());
Location: espa_sc_impl\src\com\acompany\espa\mysctype
The purpose of this file is to define the service context for the ESPA service capability module and to hold global data for the ESPA service capability. The following static variables are defined:
POLICY_SERVICE_NAME defines the service name, visible in the Policy service Rule files for this service are loaded with this name.POLICY_SERVICE_GROUP defines the Policy service group of this service.PLUGIN_TYPE defines the plug-in type string that the service uses when obtaining plug-in references from the plug-in manager. This must be the same name as the plug-in uses when it registers itself in the plug-in manager.SERVICE_TYPE to define the ESPA service capability type the ESPA service capability module belongs to. Possible values are defined in the JavaDoc for the ESPA service capability and plug-in interfaces.Other service types than specified in the JavaDoc are also allowed. These are registered through the Management tool at installation.
A Policy Enforcement Point (PEP) forwards data about a certain method invocation to a Policy Decision Point (PDP), where the data is evaluated, and possible manipulated, by a policy rule. The data, which may be modified, is returned to the PEP and the execution continues if the request was allowed according to the PDP. If the request was not allowed, an exception is thrown.
The implementation of a PEP resides in the method definition of the method that will implement a PEP. In the templates, the file MyServiceCapabilityManager_impl.java in the directory espa_sc_impl\src\com\acompany\espa\mysctype holds an example on how a PEP may be implemented.
Below is a description of how to implement a PEP, based on the example in the Extension SDK.
The example PEP resides in the method myMethodInternal(...). The basic implementation steps of building a PEP is creating an instance of the class PolicyRequest_impl and populating it with service context specific data, and then passing it to the policy service for evaluation. Policy evaluation may result in approval or denial of the service request. Denial is communicated to the PEP implementor through exceptions. If a PEP is accepted, the PolicyRequest is returned by the policy service, containing the same data as the original PolicyRequest except for that some data may have been modified by the policy rule.
The template example code in myMethodInternal() shows how the PolicyRequest is instantiated and populated with mandatory parameters. Any properties specific to the particular context where the PEP is enforced may be passed to policy rules as optional additional parameters in the PolicyRequest. In the example, the data and address parameters are passed as optional.
Location: policy_util_impl\src\com\acompany\policy\util
The purpose of this class is to expose a public method, subscriberExists, that checks in a database if a user exists. The class is a singleton class in order to be called from a Policy Rule. It uses the Subscriber profile plug-in interface to fetch subscriber data. The plug-in is found in lib\b_db_sp_resource.jar. See Creating an example Policy Utility for information on how to deploy the plug-in and to provision users in the database.
The Policy Utility called from the example rule DenySubscriberNotExists, found in ESPA_myservicecapability.ilr in policy\rules\sp\. The rule is triggered from PEP in the template ESPA Service Capability, see Policy implementation concept.
Location: policy_util_impl\src\com\acompany\policy\util
Implements the OAM interface for the Policy Utility. In the template, there are no OAM methods.
Location: policy_util_impl\src\com\acompany\policy\util
Defines an exception for the Policy Utility class.
A SESPA module collaborates with the following set of actors:
The SESPA module is built-up by a set of classes and IDL-files.
Location: sespa_sc_if\src\com\acompany\sespa\mysctype
These template files define the interfaces between the SESPA module and a WESPA module.
The name of these files reflect the name of the SESPA module.
The templates define two interfaces:
The MySESPAServiceCapability interface is used by a WESPA module to invoke methods on the SESPA module. It contains these methods:
myMethod, a template for an asynchronous method request. It returns an assignmentID to keep track of corresponding requests and responses.myMethodWait, a template for a synchronous method request. It returns the result of the request.enableNetworkTriggeredEvents, a template for enabling listeners for network triggered requests.disableNetworkTriggeredEvents, a template for disabling of previously registered listeners for network triggered requests.The MyServiceCapabilityListener interface is a callback interface used by the SESPA module to provide the result of an asynchronous method invocation made by a WESPA module. It contains two methods, myMethodResult and myMethodError.
myMethodResult is invoked upon successful completion of an asynchronous method invocation and myMethodError is invoked upon a failed completion of an asynchronous method invocation.
Location: sespa_sc_if\src\com\acompany\sespa\mysctype
This template file define the interface between the SESPA module and a WESPA module for network triggered notifications.
The MyServiceCapabilityNetworkTriggeredEventListener interface is used by a SESPA module to invoke methods on the WESPA module. It contains the method:
The purpose of this file is to define the interface between the SESPA service capability module and the OAM functionality of the SLEE.
The purpose of this file is to deliver notifications on network triggered events from the SESPA SC module to the WESPA SC module.
The purpose of this file is to define the interface between the SESPA service capability module and the OAM functionality of the SLEE.
Location: sespa_sc_impl\src\com\acompany\sespa\mysctype
This is the asynchronous ESPA callback interface implementation. It forwards results received from ESPA to the WESPA module.
Location: sespa_sc_impl\src\com\acompany\sespa\mysctype
The purpose of this class is to implement the listener the ESPA SC module calls when the ESPA SC receives notifications on network triggered notifications. It also maps ESPA login information and notification IDs to login tickets and notification IDs used in the WESPA SC.
Location: sespa_sc_impl\src\com\acompany\sespa\mysctype
The purpose of this class is to keep the different instances of the SESPA SC in sync. It generates events when an application has registered for notifications on network triggered events and it also handles reception of these events. It is also responsible for acting on events related to the login ticket expirations and refresh.
Location: sespa_sc_impl\src\com\acompany\sespa\mysctype
The purpose of this class is to implement the service deployable interface. It instantiates help classes when the SESPA module's state is changed from installed to started and performs class loader registration at activation. At deactivation the classes are unregistered from the class loader. Clean up procedures are performed both when the module is deactivated and stopped.
The reason for the class loader registrations is that the interface between SESPA and WESPA is a normal Java interface. Class definitions and objects must therefore be loaded into a class loader that is common for both SESPA and WESPA. The interface class files, MySESPAServiceCapability.class and MySESPAServiceCapabilityListener.class, must only be included in the SESPA jar file and not in the WESPA war file since the services must share a common definition. The SLEECommonLoader class loader is used by both services for registering and retrieving classes and objects. This is a parent class loader of both services, the WESPA service executes in Tomcat, and Tomcat has SLEECommonLoader as parent class loader.
Location: sespa_sc_impl\src\com\acompany\sespa\mysctype
The purpose of this class is to implement the service manageable object and the OAM methods defined in the MyServiceCapabilityOAM.idl file. In addition, it sets the service context and creates a child POA for the ESPA service capability listeners.
Location: sespa_sc_impl\src\com\acompany\sespa\mysctype
The purpose of this class is to handle operations towards the database.
Location: sespa_sc_impl\src\com\acompany\sespa\mysctype
This file is a helper class that keeps track of the ESPA service capability listeners and other service context related data.
Location: sespa_sc_impl\src\com\acompany\sespa\mysctype
This is the SESPA interface implementation. It performs the mapping between the SESPA and ESPA interfaces. In addition, it validates the login ticket received from WESPA.
Location: sespa_sc_impl\src\com\acompany\sespa\mysctype
Holds data about notifications for network triggered events.
An WESPA module collaborates with the following set of actors:
The WESPA module is built-up by a set of classes.
Location: wespa_sc_if\src\com\acompany\wespa\mysctype
These template files define the interfaces between the WESPA module and an application.
The name of these files reflect the name of the WESPA module.
The templates hold these interfaces for application initiated requests:
The MyServiceCapability interface is used by a client to invoke methods on the SESPA module. It contains these methods:
myMethod, a template for an asynchronous method request. It returns an assignmentID to keep track of corresponding requests and responses.myMethodWait, a template for a synchronous method request. It returns the result of the request.enableNetworkTriggeredEvents, for enabling listeners for network triggered events.disableNetworkTriggeredEvents, for disabling previously registered listeners for network triggered events.The MyServiceCapabilityListener interface is a callback interface used by the WESPA module to provide the result of an asynchronous method invocation made by a client. It contains two methods, myMethodResult and myMethodError.
myMethodResult is invoked upon successful completion of an asynchronous method invocation and myMethodError is invoked upon a failed completion of an asynchronous method invocation.
Location: wespa_sc_if\src\com\acompany\wespa\mysctype
The file is a class that implements exception handling.
Location: wespa_sc_if\src\com\acompany\wespa\mysctype
This file defines the interface for delivering notifications on network triggered events.
Location: wespa_sc_impl\src\com\acompany\wespa\mysctype
This is the asynchronous SESPA callback interface implementation. It forwards results received from SESPA to the application.
Location: wespa_sc_impl\src\com\acompany\wespa\mysctype
This is the implementation of the interface used for delivering network triggered notifications to an application.
Location: wespa_sc_impl\src\com\acompany\wespa\mysctype
This class implements the server part of the WESPA MyServiceCapability interface. It is deployed in the Axis web services engine.
The test application uses the Web Service implemented by the WESPA Service capability module and implements the Web Service called by the WESPA Service Capability module.
Location: client_impl\src\com\acompany\test
Handles login towards WESPA Access and holds the login information.
Location: client_impl\src\com\acompany\test
Performs the calls towards the Web Service exposed by the WESPA Service Capability.
Location: client_impl\src\com\acompany\test
Implements the Web Service the WESPA Service Capability module uses to reports results of asynchronous application triggered requests.
Location: client_impl\src\com\acompany\test
Main program for the test client that implements a menu and call the different parts of the test client according to the menu choices and information given.
Location: client_impl\src\com\acompany\test
Helper class and interface to perform trace.
Location: client_impl\src\com\acompany\test
Helper class that creates Web Services calls and creates security headers.
The network simulator application uses a Web Service implemented by the Web Services part of the network plug-in and implements the Web Service called by the Web Services part of the network plug-in. For application initiated requests it receives the request and prints the request data to System.out. For network initiated requests it performs a Web Services call to the Web Services part of the network plug-in.
Location: network_simulator_impl\src\com\acompany\test
Performs network initiated requests to the Web Services part of the network plug-in. Uses a Web Service.
Location: network_simulator_impl\src\com\acompany\test
Receives application triggered requests from the plug-in. Implements a Web Service.
Location: network_simulator_impl\src\com\acompany\test
Main program for the test client that implements a menu and call the different parts of the test client according to the menu choices and information given.
Location: network_simulator_impl\src\com\acompany\test
Helper class and interface to perform trace.
In order to create a new set of modules, copy the relevant modules from bea\wlng21\esdk\module_templates to a new directory where the development will take place. This directory will be referred to as exampleproj.
In the file exampleproj\build.properties, change the properties described below.
Note: All slashes that separates directories, should be regular slashes, not back slashes (\) on Windows systems also.
C:/wlng21install.install.C:/bea/wlng21/esdkexampleproj.Depending on which modules to be developed, the build files for these module needs to be adapted to reflect the new modules. All module-specific build files are named build.xml, and are located directly under the directory for the module.
For a completely new traffic path, there is a main build file, exampleproj\build\build.xml, that calls a a set of build files specific for the individual modules. If the new project does not include all modules this build file should be adapted to include only the relevant modules.
The following properties can be changed in the module-specific build files to reflect any changes in interface names, module name etc:
The version information will be added to the deployment descriptor for the module.
All software modules executing as SLEE services are packed in a jar file. This is automatically performed by the build files.
In the root of the jar file there is a deployment descriptor. This is an XML file describing how the software module is deployed. The name of the XML file is always srv_depl.xml, and the build files automatically creates this file in the ant target "jar". Below is a description of the tags in the XML file.
<SLEE_SERVICE> Defines the service deployment descriptor. It has the following attributes:
name: the name of the SLEE Service, fetched from the property local.deployName.version: the version of the service, fetched from the property local.fullVersion.max_alarms:-maximum number of CRITICAL alarms the service is allowed to generate before the service is set is state ERROR by the SLEE.company: unused.trace: ON or OFF. Defines if trace shall be activated for the service when it is started for the first time.db_share: unused."Slee_common_loader". If it is a SESPA service, set this attribute to "SESPA_access". SESPA_Access has the Slee_common_loader as a parent class loader, so the SESPA services have access to the classes in the SLEE Common loader. See Plug-ins that executes as a SLEE service and a web application on page 7-1 and Stateless adapter framework on page 5-4 for more information on SLEE Common Loader.<SERVICE_DEPLOYABLE> Defines the class that implements the ServiceDeployable interface.
<SERVICE_ACCESSIBLE> Defines the class that implements the ServiceAccessible interface. Contains the following tag:
<NAMESERVICE_VISIBILITY> ON or OFF. Defines if the CORBA objects that implements the ServiceAccessible interface shall be registered in the CORBA nameservice, and be reachable from outside the SLEE.<SERVICE_MANAGEABLE> Defines the class that implements the ServiceManageable interface. Contains the following tag:
The templates and the build environment supports Eclipse 3.1.1.
Below is a suggestion on how to setup an Eclipse workspace for the templates.
bea\wlng21\esdk\eclipse\module_templates_eclipse.zip to bea\wlng21\esdk\module_templates.bea\wlng21\esdk\module_templates to the working directory for your project. This directory will be referred to as exampleproj.bea\wlng21\esdk\dev_tools\ant.The indicators on the project symbol, white crosses on a red background, should disappear when refreshing the project.
|
|
|