Access Keys:
Skip to content (Access Key - 0)









How do I use SLEE Initial Event Selection?

Print this page

Introduction

The JAIN SLEE Initial Event Selection mechanism allows developers to flexibly control how events trigger services. For example, a developer can specify that a service is only triggered when a certain parameter is present in the event, or only if the event is addressed to a valid user.

There are many choices available, and this can be daunting to beginners. This guide explains how initial event selection works, and illustrates this by showing how several common service triggering scenarios can be realised in JAIN SLEE.

Throughout this guide, section numbers in parentheses, such as (§1.2.3), are referring the reader to sections in the JAIN SLEE 1.0 Specification.

Overview of Initial Event Selection

A SLEE service is triggered when the SLEE receives an event that is an initial event for the service. Initial events are simply those events that the service's root SBB declares as initial in its deployment descriptor (§8.5.1).

When the SLEE determines that an event is a potential initial event for a service, it must then apply its initial event selection logic to determine how the service handles the event. This is described in more detail below.

Developers new to SLEE may initially find the details of initial event selection confusing, but essentially it boils down to the SLEE making these two decisions about the initial event:

  1. Should this service process the event, or ignore it?
  2. If this service will process the event, will it be handled by a new or existing root SBB entity?

Whether an existing or new root SBB entity is used is important, because it affects how the service is designed.

For example, a common design pattern in telco services is to use a single root SBB per call or call leg. With the SLEE's initial event selection mechanism, the developer can guarantee that a new SBB entity is created for each new call, or "activity" in SLEE terms. This simplifies the SBB design, because it need only be concerned with a single call.

Similarly, a developer might want to ensure that an existing SBB entity handles an initial event. For example, a conferencing service can ensure that the same SBB entity will handle multiple calls addressed to the same number.

Initial Event Selection Details

This section describes the initial event selection process in more detail. New users can safely skip ahead to the examples in the next section, and come back to this later.

The initial event selection behaviour for a service is specified in the root SBB's deployment descriptor, sbb-jar.xml. Events that are declared as initial events can contain the two optional elements, initial-event-select and initial-event-selector-method (§8.5.3). The SLEE uses these to calculate the convergence name for the initial event.

Convergence Names

The convergence name is a logical name that can be thought of as a concatenation of several variables related to the initial event. Each variable is either selected or not selected. If a variable is not selected, it will not be part of the convergence name.

When the convergence name is calculated, the SLEE looks for a root SBB that was created with the same convergence name. If none exists, a new root SBB is created to process the initial event. If a root SBB entity already exists with that convergence name, then that SBB entity will process the initial event. In this way the convergence name is like a "primary key" for root SBBs.

It is the convergence name that determines whether new root SBB entities are created or not. So when deciding which variables to use, the basic process is: to have a different root SBB entity handle each initial event, then ensure that the convergence names will be different for each initial event. If the same root SBB entity should be processing several initial events, then ensure that the convergence name will be the same for those events.

Selecting Convergence Name variables

The initial-event-select element is used to select the variables that will be used to calculate the convergence name. Zero or more initial-event-select elements may be present, each selecting a different variable, specified by the variable attribute, as shown below:

sbb-jar.xml
<event event-direction="Receive" initial-event="True">
  <event-name ... />
  <event-type-ref ... />
  <initial-event-select variable="ActivityContext"/>
</event>

There are 5 standard variables. The variables, and the values they add to the convergence name if selected, are:

  • ActivityContext - a unique ID for each activity context.
  • AddressProfile - the ID of an address profile that matched the event's address. If no profile matched then the event is ignored.
  • Address - the value of the event's address.
  • EventType - the event's event type identifier.
  • Event - a unique ID for each event fired.

So if an initial event just has ActivityContext selected, then this will result in a different convergence name for each new activity. Therefore a new root SBB entity will be created for each activity. See more examples below.

Initial Event Selector methods

If more control is needed, the SBB can use an initial event selector method (§8.5.4). The initial-event-selector-method element specifies the name of a method in the root SBB's abstract class. The SLEE will invoke this method before it calculates the convergence name.

The initial event selector method can have any name (see restrictions in §8.5.4), but must have the following signature:

SBB Code
import javax.slee.InitialEventSelector;

public InitialEventSelector someMethod(InitialEventSelector ies) { ... }

The method is specified in the root SBB's deployment descriptor as follows:

sbb-jar.xml
<event event-direction="Receive" initial-event="True">
  <event-name ... />
  <event-type-ref ... />
  <initial-event-selector-method-name>someMethod</initial-event-selector-method-name>
</event>

The InitialEventSelector interface provides methods for selecting and de-selecting the standard convergence name variables as above. It also makes available the event and activity objects, and the event's address. The method can also set a custom name in the InitialEventSelector, which will be added to the convergence name. This gives the SBB maximum control over the resulting convergence name. Finally there is the InitialEventSelector.setInitialEvent(boolean) method. If this is set to false, then the event will be ignored and the service will not be triggered at all. So a service could use this to ensure it is only triggered when the initial event matches certain conditions.

Example Applications of Initial Event Selection

This section describes how SLEE initial event selection can be applied in real-world scenarios. It should clarify the concepts discussed in the previous sections.

One SBB per Activity

This is a very common scenario, where the developer wants to ensure that a new root SBB entity is created for each activity (such as a phone call or SIP dialog).

This can be done by simply selecting the standard ActivityContext variable in the initial event definition:

sbb-jar.xml
<event event-direction="Receive" initial-event="True">
  <event-name ... />
  <event-type-ref ... />
  <initial-event-select variable="ActivityContext"/>
</event>

Because the ActivityContext variable is unique per activity, initial events that arrive on different activities will have different convergence names. Therefore the SLEE will create a new root SBB entity for each new activity.

One SBB per Address

A conferencing service might want to ensure that all calls to a particular address are handled by the same root SBB entity. This can simplify the service's design because the same SBB entity can know the state of all the participants in the conference.

This can be implemented by by simply selecting the "Address" variable in the initial event definition:

sbb-jar.xml
<event event-direction="Receive" initial-event="True">
  <event-name ... />
  <event-type-ref ... />
  <initial-event-select variable="Address"/>
</event>

This means that when 2 or more initial events arrive with the same address, the convergence names for the events will be the same. The first initial event to arrive on a particular address will create the root SBB entity, and the next event will go to the same SBB entity (provided it still exists, otherwise a new root SBB entity will be created).

Trigger Service if User Profile is Present

Services often make use of SLEE profile tables to store provisioned user data. But a service may want to ignore events for users that are not provisioned. This filtering can be done in the initial event selection logic.

A service can have an associated address profile table (§10.13.2). If the AddressProfile variable is selected, the SLEE will look up the initial event's address in this profile table. If the address is not found, the event will be ignored. If the address is found, the convergence name variable will be set to the ProfileID of the matching profile.

This provides a simple way to ensure that the service is only triggered when the address (phone number, user name etc.) is known to the service. The initial event definition would have to include the AddressProfile variable:

sbb-jar.xml
<event event-direction="Receive" initial-event="True">
  <event-name ... />
  <event-type-ref ... />
  <initial-event-select variable="AddressProfile"/>
</event>

And the service's deployment descriptor must specify the name of an address profile table:

service.xml
<service-xml>
  <service>
    <service-name ... />
    <service-vendor ... />
    <service-version ... />
    <root-sbb ... />
    <default-priority ... />
    <address-profile-table>MyAddressProfiles</address-profile-table>
  </service>
</service-xml>

Default Address Selection

The two examples above described using the Address and AddressProfile variables in the convergence name. These automatically use the initial event's default address. But what if the default address is undefined, or not applicable to a service?

The default address of an event is set by the entity that fired the event, such as a Resource Adaptor or SBB. The RA or SBB that fired the event should define how it selects the address - it could be the the source or destination phone number in a phone call, or it may not be defined at all.

If the default address provided is not applicable to a service, a service is able to override it by using an initial event selector method. The method can call InitialEventSelector.setAddress(javax.slee.Address) to replace the event's default address. Then this new address will be used in the convergence name instead, if the Address or AddressProfile variables are selected.

sbb-jar.xml
<event event-direction="Receive" initial-event="True">
  <event-name ... />
  <event-type-ref ... />
  <initial-event-selector-method-name>changeAddress</initial-event-selector-method-name>
</event>


SBB Code
import javax.slee.Address;
import javax.slee.AddressPlan;
import javax.slee.IntialEventSelector;

public InitialEventSelector changeAddress(InitialEventSelector ies) {
    ies.setAddress(new Address(AddressPlan.E164, "18005551212"));
    return ies;
}

Filter Based on Event Parameters

It is often necessary to filter initial events based on some other criteria, such as whether a certain parameter is present. For example, in telephony applications it is usually a requirement to have different behaviour for the "originating" and "terminating" legs of the call. A developer may want to have different services handling the originating and terminating legs, so the events must be filtered to ensure the correct service is triggered.

This type of filtering can be done in an initial event selector method. The method can examine the initial event and activity objects, and use this and any other information to decide whether the event should be processed by the service, or ignored. The initial event selector method can call InitialEventSelector.setInitialEvent(false) to ensure that this service will not process the event. Otherwise, the initial event selection logic will continue normally and calculate the convergence name from the variables selected.

In this example, the service wants to be triggered only on initial events for the originating side of the call. It also wants a single root SBB per call. This can be realised by using an initial event selector method in conjunction with the ActivityContext variable.

sbb-jar.xml
<event event-direction="Receive" initial-event="True">
  <event-name ... />
  <event-type-ref ... />
  <initial-event-select variable="ActivityContext"/>
  <initial-event-selector-method-name>checkOriginating</initial-event-selector-method-name>
</event>


SBB Code
import javax.slee.IntialEventSelector;

public InitialEventSelector checkOriginating(InitialEventSelector ies) {
    if (isOriginating(ies.getEvent()) {
        ies.setInitialEvent(true);
    }
    else { // not originating, not for this service
        ies.setInitialEvent(false);
    }
    return ies;
}

Custom Name

In some cases, the standard convergence name variables like ActivityContext and Address may not be sufficient. A service might want to ensure that the same root SBB entity processes several initial events, based on a completely custom set of criteria.

This can be achieved using a custom name, an arbitrary string that can be set in an initial event selector method. This string will be used in the convergence name, in conjunction with any other variables selected.

For example, a SIP service could elect to have all initial SIP requests with the same Call-ID field be processed by the same root SBB entity. This would be done by extracting the SIP Call-ID from the request, and using the string value of the Call-ID as the custom name. This is shown below, using JAIN SIP.

sbb-jar.xml
<event event-direction="Receive" initial-event="True">
  <event-name ... />
  <event-type-ref ... />
  <initial-event-selector-method-name>selectCallID</initial-event-selector-method-name>
</event>


SBB Code
import javax.slee.IntialEventSelector;
import javax.sip.RequestEvent;
import javax.sip.message.Request;
import javax.sip.header.CallIdHeader;

public InitialEventSelector selectCallID(InitialEventSelector ies) {
    Object event = ies.getEvent();
    if (event instanceof RequestEvent) {
        Request request = ((RequestEvent)event).getRequest();
        String callID = ((CallIdHeader)request.getHeader(CallIdHeader.NAME)).getCallId();
        ies.setCustomName(callID);
    }
    else {
        ies.setInitialEvent(false);
    }
    return ies;
}

In this example, each unique Call-ID will generate a different convergence name. Therefore requests that arrive with the same Call-ID will generate the same convergence name, and go to the same root SBB entity.

Summary

This guide has explained how SLEE initial event selection works, and applied it to several scenarios. Readers are encouraged to refer to the JAIN SLEE specification, section 8.5, for more detailed information about the topics covered here.

Adaptavist Theme Builder Powered by Atlassian Confluence