System Administrator’s Guide

Managing and Configuring the Plug-in Manager

The following section describes configuration and maintenance attributes and operations for the Plug-in manager. It also provides a workflow for the configuration:

Introduction

Network protocol plug-ins consist of two parts: the plug-in service and the plug-in instance.The plug-in service is the deployable and updatable unit. It does not itself process any traffic. Plug-in instances are instantiated from a plug-in service. One plug-in service can be the base for many plug-in instances.

A plug-in service:

Has a unique ID.
Has a version.
Is packaged in an EAR, together with other plug-ins of that share the same set of application-facing interfaces.

A plug-in instance:

Is instantiated from a plug-in service
Has a unique ID
Is versioned based on the plug-in service it is instantiated from.
Belongs to a type.
Exposes a set of traffic interfaces to the service communication layer. This set is a Java representation of the Web Services interfaces exposed by the service access layer.
Interfaces with network nodes using one or more protocols.
Supports a set of address schemes.
Is configured and managed independently of other instances.
Can be assigned a node ID to be used when setting up node SLAs.

Plug-in instances are created using the Plug-in Manager MBean.

The plug-in manager introspects the plug-in north interfaces, methods, and names of any arguments. This is useful when creating up service provider group and application group SLAs.

Execution and evaluation flow

Application-initiated requests

When an application’s request is processed, it is routed to the network protocol plug-in instance via the plug-in manager. The plug-in manager triggers a chain of service interceptors, where the request is evaluated and a given plug-in instance is selected based on:

Data in the request originating from the application.
Status of the plug-in (only plug-ins in status active are considered)
Properties of the registered plug-ins, including:

Plug-in type.
Plug-in ID.
Address plan, that is the kind of network to which they are connected: for example E.164 or SIP.

Usage policies based on SLA settings and policy rules.
Load balancing
Data from external sources: any custom data-lookups implemented as service interceptors.
Routing logic

Once the decision has been made, the request is forwarded to the selected plug-in.

Routing logic is expressed in XML, and is evaluated by means of service interceptors.

Refer to the section in this guide for each communication service for the plug-in service ID and plug-in type under which individual plug-ins are registered.

The following interceptors use data configured using the plug-in manager:

CreatePluginList
RemoveInvalidRoute

Network triggered Requests

When a request is triggered from the network, the plug-in manager is also part of the request flow, and is responsible for invoking the chain of service interceptors.

Plug-in Routing Logic

The plug-in routing logic matches data in a request, and data associated with a request, with routing logic and results in the selection of a plug-in instance. The request is handed off to the selected plug-in instance for further processing.

The routing logic offers a fine grained way to select a network protocol plug-in instance and makes it possible to select a plug-in instance, and thereby a network node, to be targeted for individual requests, based on all data available in the request.

In combination with the plug-in instance feature make it possible to single out a certain network node based on the above operands and thereby:

offer different QoS levels. Example: different network nodes offers different QoS, for example latencies for message delivery.
ensure that requests are routed to a node that can actually handle the request. Example: one SMSC is capable of handling binary content in the form of SM logos, while another is not.
maximize utilization of the network nodes. Example: Two network nodes offers exactly the same functionality, but one processes the request more expensively, so the selection is done based on the charging code the application supplied.

In combination with the plug-in instance feature make it possible to single out a network protocol plug-in instance even if the different plug-in instances connect to the same network node and thereby use different configurations for the request towards the network node.

Example: A network protocol plug-in offers the possibility to configure a priority parameter when sending request to the network node, by setting the parameter differently in different plug-in instances, different priorities can be used for different service providers. In the same way credentials can be mapped so the originator of the request is mapped to the request that is made to the network node.

Defining Routing Logic

The routing logic is expressed in XML and provides:

a set of logical operators:

access to a set of operands:

the method name
all parameters in the request
the authentication data, and the data associated with the authentication data, such as service provider ID, application ID, and application instance ID.
the destination address in the request
tunnelled parameters provided by the application as xparams in the SOAP header.

The XML based routing logic is specified per plug-in instance and routes requests to a plug-in based on logical expressions and tests that gets evaluated.

The logical operators are XML elements, as described in Table 19-1.

Table 19-1 Logical operators/elements for Plug-in routing
Operator/Element	Description
and	This element contains 1 or many nested elements that in turn are evaluated. This expression will only be true if all the contained elements are true.
or	Contains 1 or many nested elements that in turn are evaluated. This expression will be true if any of the contained elements are true.
not	This element can contain only one nested element. This expression results in the inverse of the nested element.

The operands are XML elements, as described in Table 19-2.

Table 19-2 Operands/elements for Plug-in routing
Operand/Element	Description
spId	The service provider ID associated with the request is compared with the value given in this element. The result is true only if there is an exact match.
appId	The application ID associated with the request is compared with the value given in this element. The result is true only if there is an exact match.
appInstanceId	The application instance ID associated with the request is compared with the value given in this element. The result is true only if there is an exact match.
destAddress	The destination address provided in the request is compared with the value given in this element. Which parameter that is considered the destination address is plug-in specific. The format of the value is a regular expression specified as a string. The result is true only if the regular expression matches. See How address ranges are specified when setting up routes for examples of regular expressions. The element has the optional attribute `defaultResult`. It is a Boolean attribute that affects the end result if the request does not contain any destination address. If the attribute is set to false the evaluation results in false. If set to true, the evaluation results in true. Default value is false.
method	The name of the method that the application invoked is compared with the value given in this element. The result is true only if there is an exact match. Examples: `<method>sendSms</method>` `<method>makeACall</method>`
param	A named parameter in the request is compared with the value given in this element. There are three attributes to this element: `name`, the parameter name. The format of the atttribute is the same as used when referring to parameters in the SLAs. Mandatory attribute.Use Operation: getServiceInfo for a list of parameter names. `value,` the value of the parameter. If the parameter is not of type String, the Java toString() method is used to convert it to a String. Mandatory attribute. `defaultResult`, a Boolean attribute that affects the end result if the request does not contain the specified `name` attribute. If set to false the evaluation results in false if the `name` attribute is not present in the request. If set to true, the evaluation results in true if the if the `name` attribute is not present in the request. Default value is false. Optional attribute. The result is true only if there is a match or if `defaultResult` is set to true and the `name` attribute is not present at all in the request. The result is true only if there is a match. The value can be expressed as a regular expression. Example: `<param name="arg0.senderName" value="tel:123456"/>` <param name="arg0.senderName" value="tel:123.*"/>
xparam	A parameter supplied in the request as a tunnelled parameter (xparam) in the request is compared with the value given in this element. There are three attributes to this element: `name`, corresponds to the contents of the `key` attribute in the `param` element in the request. Mandatory attribute. `value`, corresponds to the contents of the `value` attribute in the `param` element in the request.Mandatory attribute. `defaultResult`, a Boolean attribute that affects the end result if the request does not contain the specified `name` attribute. If set to false the evaluation results in false if the `name` attribute is not present in the request. If set to true, the evaluation results in true if the if the `name` attribute is not present in the request. Default value is false. Optional attribute. The result is true only if there is a match or if `defaultResult` is set to true and the `name` attribute is not present at all in the request. The result is true only if there is a match. The value can be expressed as a regular expression. Example: The tunneled parameter is defined as: `<xparams>` `<param key="aParameterName" value="aParameterValue" />` `</xparams>` A match occurs if the `xparam` element in the routing configuration is `<xparam name="aParameterName" value="aParameterValue"/>`

The plug-in routing configuration XML document is validated when it is provisioned. The XML is validated according to the XSD, see Plug-in Routing XSD.

For a set of examples, see Plug-in Routing Configuration Examples.

Plug-in Routing Configuration Examples

The example in Listing 19-1 matches requests sent to an address starting with tel:123. If the request does not contain an address this route does not match.

Listing 19-1 Plug-in Routing Configuration Example 1

<?xml version="1.0" encoding="UTF-8"?>

<route xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="route.xsd">

  <destAddress>tel:123.*</destAddress>

</route>

The example in Listing 19-2 matches any address and also matches any request that does not contain an address.

Listing 19-2 Plug-in Routing Configuration Example 2

<?xml version="1.0" encoding="UTF-8"?>

<route xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="route.xsd">

  <destAddress defaultResult="true">.*</destAddress>

</route>

The example in Listing 19-3 matches requests sent from the service provider with the ID sp1, and the application with the ID app1.

Listing 19-3 Plug-in Routing Configuration Example 3

<?xml version="1.0" encoding="UTF-8"?>

<route xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="route.xsd">

  <and>

    <spId>sp1</appId>

    <appId>app1</appId>

  </and>

</route>

The example in Listing 19-4 matches all requests except the ones where the operation is sendSmsRingtone and either sent from and application using application instance ID appInst1 or the operation is sendSms withe the value of the parameter senderName is tel:123456.

Listing 19-4 Plug-in Routing Configuration Example 4

<?xml version="1.0" encoding="UTF-8"?>

<route xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="route.xsd">

  <and>

    <not><method>sendSmsRingtone</method></not>

    <or>

      <appInstanceId>appInst1</appInstanceId>

      <and>

        <method>sendSms</method>

        <param name="arg0.senderName" value="tel:123456"/>

      </and>

    </or>

  </and>

</route>

Plug-in Routing XSD

Below is the XSD to use when creating a plug-in routing configuration XML file.

Listing 19-5 route.xsd

<?xml version="1.0" encoding="utf-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="route">

    <xs:complexType>

      <xs:group ref="ConditionGroup" minOccurs="1" maxOccurs="1"/>

    </xs:complexType>

  </xs:element>

  <xs:group name="ConditionGroup">

    <xs:choice>

      <xs:element name="and" type="AndType"/>

      <xs:element name="or" type="OrType"/>

      <xs:element name="not" type="NotType"/>

      <xs:element name="spId" type="xs:string"/>

      <xs:element name="appId" type="xs:string"/>

      <xs:element name="appInstanceId" type="xs:string"/>

      <xs:element name="destAddress" type="AddressType"/>

      <xs:element name="method" type="xs:string"/>

      <xs:element name="param" type="ParamType"/>

      <xs:element name="xparam" type="ParamType"/>

    </xs:choice>

  </xs:group>

  <xs:complexType name="AndType">

    <xs:group ref="ConditionGroup" minOccurs="1" maxOccurs="unbounded"/>

  </xs:complexType>

  <xs:complexType name="OrType">

    <xs:group ref="ConditionGroup" minOccurs="1" maxOccurs="unbounded"/>

  </xs:complexType>

  <xs:complexType name="NotType">

    <xs:group ref="ConditionGroup" minOccurs="1" maxOccurs="1"/>

  </xs:complexType>

  <xs:complexType name="AddressType">

    <xs:simpleContent>

      <xs:extension base="xs:string">

        <xs:attribute name="defaultResult" type="xs:boolean" default="false"/>

      </xs:extension>

    </xs:simpleContent>

  </xs:complexType>

  <xs:complexType name="ParamType">

    <xs:attribute name="name" type="xs:string" use="required"/>

    <xs:attribute name="value" type="xs:string" use="required"/>

    <xs:attribute name="defaultResult" type="xs:boolean" default="false"/>

  </xs:complexType>

</xs:schema>

How address ranges are specified when setting up routes

Address ranges are specified using UNIX regular expressions. A few examples are given below:

^.* specifies a route that matches all addresses.
^[0-5].* specifies a route that matches all address strings starting with 0, 1, 2, 3, 4, or 5.
^.*[6-9]$ specifies a route that matches all address strings ending with 6, 7, 8, or 9.
^46.* specifies a route that matches all address string starting with 46.
^46.{8}$ specifies a route that matches all address strings starting with 46 that contain exactly 10 total digits.
^.*@.*\.com$ specifies a route matching all mail addresses in the com domain. Note that the dot in .com must be written “\.”.

In the examples:

^ indicates the beginning of the string.
. matches anything except a new-line. That is, “a.b” matches any three-character string which begins with a and ends with b.
* is a suffix which means the preceding regular expression is to be repeated zero or more times. That is, in the expression “^46.*” the “.” is repeated until the whole string is matched.
$ is a indicator of end of line (or end of string).

The address scheme can be included in the expression. If not specified, any scheme will match. Examples

tel:^46.* matches all tel (E.164) numbers starting with 46.
sip:.* matches any SIP address.

Plug-in Routing Logic and Plug-in Routes

Plug-in routing logic is an extension the plug-in routes and Operation: setRouteConfig and Operation: getRouteConfig replaces Operation: addRoute and Operation: removeRoute.

Plug-in routes added using Operation: addRoute, are converted into plug-in routing logic where route is added as a logical OR given that the route that is being modified only contain <or> and <destAddress defaultResult="true"> elements.

Configuration Workflow

Configuring the plug-in manager can be divided into:

Configuration of the general behavior of the plug-in manager, see Configuring the Plug-in Manager.
Administration of routes, which is tightly coupled to the configuration of the individual communication services, see Configuring the Plug-in Manager.

Configuring the Plug-in Manager

Below is an outline for configuring the plug-in manager:

Specify whether or not to use policy based routing in Attribute: PolicyBasedRouting. Policy based routing is necessary in order to enforce node SLAs.
Specify the network protocol plug-in behavior when it is being deployed or re-deployed in Attribute: ForceConnectInResuming

Creating a Plug-in instance

Below is an outline for creating an instance of a plug-in service:

Find the plug-in service ID for the service you wish to use to create the plug-in instance. The plug-in service IDs are listed under the heading “Properties” in the sections describing the management of each plug-in. To get a list of plug-in service IDs, use Operation: listPluginServices.
Use Operation: createPluginInstance to create the instance. The Plug-in Instance ID supplied as a parameter will be used to identify the instance for all routing and administration.
To destroy an instance use Operation: destroyPluginInstance

Administration of Plug-in Routing Logic and Node IDs

The administration of routes uses the following operations:

To add new routing logic: Operation: setRouteConfig
To change or remove routing logic: Operation: getRouteConfig and Operation: setRouteConfig
To list all existing routes: Operation: listRoutes
To get information about a specific plug-in instance, Operation: getPluginServiceInfo.
To get a list of all registered plug-in instances: Operation: listPluginInstances
To get a list of all registered plug-in services: Operation: listPluginServices
To define the node ID: Operation: setPluginNodeId.

A node ID is assigned to one or more plug-in instance IDs to enforce node SLAs,. The node ID is then referred to in the node SLAs.

Reference: Attributes and Operations for PluginManager

Managed object: Container ServicesPluginManager

MBean: com.bea.wlcp.wlng.plugin.PluginManagerMBean

Below is a list of attributes and operations for configuration and maintenance:

Attribute: ForceConnectInResuming

Scope: Cluster

Unit: n/a

Format: Boolean

Specifies if a network protocol plug-in service is allowed to transition to state ACTIVE if it fails to establish a connection with the underlying network node during deployment or re-deployment. This assures that a new version of the network protocol plug-in service is activated only when it is certain that it can accept traffic.

If enabled, all plug-ins services packaged in the EAR that is being updated must become active before any traffic is routed to the plug-in instances derived from the new version. If any plug-in instance fails to connect to the underlying network, the new version does not become active.

Use:

true to check if a connection can be established before accepting traffic.
false to not perform this check.

Attribute: PolicyBasedRouting

Scope: Cluster

Unit: n/a

Format: Boolean

Specifies whether policy based routing should be used.

Use:

true to enable policy based routing
false to disable policy based routing

Note:

Policy based routing must be enabled in order to enforce node SLAs.

Operation: addRoute

Scope: Cluster

Deprecated. Use Operation: setRouteConfig.

Adds a new plug-in route. A route is identified by the plug-in instance ID and a match pattern.

Signature:

addRoute(PluginInstanceId: String, AddressExpression: String)

Table 19-3 addRoute
addRoute
Parameter	Description
PluginInstanceId	ID of the plug-in instance that is the target of the route. A list of plug-in instance IDs is displayed using the Operation: listPluginInstances.
AddressExpression	The pattern to be used as a matching criteria. See How address ranges are specified when setting up routes.

Operation: createPluginInstance

Scope: Cluster

Creates a new instance of a specific plug-in service.

Signature:

createPluginInstance(PluginServiceId: String, PluginInstanceId: String)

Table 19-4 createPluginInstance
createPluginInstance
Parameter	Description
PluginServiceId	ID of the plug-in service to instantiate. See Operation: listPluginServices for a list of plug-in service IDs.
PluginInstanceId	ID of the plug-in instance to be created. The ID must be unique among all instances. All existing instances can be displayed using Operation: listPluginInstances.

Operation: destroyPluginInstance

Scope: Cluster

Destroys an instance of a specific plug-in instance. All routes associated with the instance are kept.

Signature:

destroyPluginInstance(PluginServiceId: String, PluginInstanceId: String)

Table 19-5 destroyPluginInstance
destroyPluginInstance
Parameter	Description
PluginServiceId	ID of the plug-in service which has a plug-in instance that is to be destroyed.
PluginInstanceId	ID of the plug-in instance to destroy.

Operation: getPluginInstanceInfo

Scope: Cluster

Gets information about a specific plug-in instance. The information includes:

The node ID, if the plug-in instance is assigned a node ID using Operation: setPluginNodeId.
A list of North interfaces registered with the plug-in manager.
A list of South Interfaces registered with the plug-in manager.
Whether the plug-in instance is connected to the network node (true if connected).
A list of all configured routes

Signature:

getPluginInstanceInfo(PluginInstanceId: String)

Table 19-6 getPluginInstanceInfo
getPluginInstanceInfo
Parameter	Description
PluginInstanceId	ID of the plug-in instance to get information about.

Operation: getPluginNodeId

Scope: Cluster

Displays which plug-in node ID a plug-in instance is associated with, if any.

Signature:

getPluginNodeId(PluginInstanceId: String)

Table 19-7 getPluginNodeId
getPluginNodeId
Parameter	Description
PluginInstanceId	ID of the plug-in.

Operation: getPluginServiceInfo

Scope: Cluster

Displays information about a plug-in service. The information includes:

The service type
A list of address schemes the plug-in service supports
The protocol it uses towards the network node.
A list of plug-in instances crated based on the plug-in service.

Signature:

getPluginServiceInfo(PluginServiceId: String)

Table 19-8 getPluginServiceInfo
getPluginServiceInfo
Parameter	Description
PluginServiceId	ID of the plug-in service.

Operation: getRouteConfig

Scope: Cluster

Gets the plug-in routing logic XML for a given plug-in instance.

Signature:

getRouteConfig(PluginInstanceId :String)

Table 19-9 getRouteConfig
getRouteConfig
Parameter	Description
PluginInstanceId	The plug-in instance ID to get the routing configuration for.

Operation: getServiceInfo

Scope: Cluster

Displays information about a service type. The information includes:

A list of interface names for the service type
A list of method names for each interface
A list of argument names for each method.
The name of the return type for each method.

This list is useful when setting up SLAs.

Signature:

getServiceInfo(Type: String)

Table 19-10 getServiceInfo
getServiceInfo
Parameter	Description
Type	ID of the service type. See Operation: listServiceTypes.

Operation: listPluginInstances

Scope: Cluster

Displays a list of plug-in instances IDs.

The list is rendered as:

<Plug-in instance ID>#<JEE application name>#<version of JEE application>

The plug-in instance ID is the part of each entry up to the first #.

Signature:

listPluginInstances()

Table 19-11 listPluginInstances
listPluginInstances
Parameter	Description
-	-

Operation: listPluginServices

Scope: Cluster

Displays a list of plug-in service IDs. A plug-in service ID uniquely identifies a plug-in service.

Signature:

listPluginServices()

Table 19-12 listPluginInstances
listPluginInstances
Parameter	Description
-	-

Operation: listRoutes

Scope: Cluster

Displays a list of all registered routes, including the routing logic expressed an XML.

Signature:

listRoutes()

Table 19-13 listRoutes
listRoutes
Parameter	Description
-	-

Operation: listServiceTypes

Scope: Cluster

Displays a list of service types. The service types defines a collection of plug-in services exposing a specific functionality in the network.

For example: SMS or MMS.

Signature:

listServiceTypes()

Table 19-14 listServiceTypes
listServiceTypes
Parameter	Description
-	-

Operation: removeRoute

Scope: Cluster

Deprecated. Use Operation: setRouteConfig.

Removes a route. The route is identified by the ID of the plug-in instance and the matching pattern.

Signature:

removeRoute(PluginInstanceId: String, AddressExpression: String)

Table 19-15 removeRoute
removeRoute
Parameter	Description
PluginInstanceId	ID of the plug-in.
AddressExpression	The pattern used as a matching criteria. See How address ranges are specified when setting up routes.

Operation: setRouteConfig

Scope: Cluster

Loads plug-in routing logic XML for a plug-in instance. Existing routing logic is overwritten, use Operation: getRouteConfig to get the existing routing logic.

Replaces Operation: addRoute.

Signature:

setRouteConfig(PluginInstanceId :String, xmlConfig: String)

Table 19-16 setRouteConfig
setRouteConfig
Parameter	Description
PluginInstanceId	The plug-in instance ID to load the routing configuration for.
xmlConfig	The plug-in routing logic. Expressed as XML, see Plug-in Routing Logic.

Operation: setPluginNodeId

Scope: Cluster

Assigns a node ID to a plug-in instance.

Signature:

setPluginNodeId(PluginInstanceId :String, nodeId: String)

Table 19-17 setPluginNodeId
setPluginNodeId
Parameter	Description
PluginInstanceId	The plug-in instance ID.
nodeId	ID to be used as a node ID. This ID is used when enforcing node SLAs.

Operation: setRouteConfig

Scope: Cluster

Loads plug-in routing logic XML for a plug-in instance.

Replaces Operation: addRoute.

Signature:

setRouteConfig(PluginInstanceId :String, xmlConfig: String)

Table 19-18 setRouteConfig
setRouteConfig
Parameter	Description
PluginInstanceId	The plug-in instance ID to load the routing configuration for.
xmlConfig	The plug-in routing logic. Expressed as XML, see Plug-in Routing Logic.