Correlation RA Overview

What is the Correlation RA?

There are situations where Sentinel must correlate two independent sessions. The Correlation RA allocates a correlation ID with the first session, that can then be used to process a second session. The Sentinel service may associate a blob of data with an allocated correlation ID.

The Correlation RA is used for two cases in Sentinel:

  1. Playing an announcement using ETC/ARI. In this case, the Correlation RA is used to allocate the correlation ID that is included in the ETC message, which is then present in the ARI message sent on a second dialog.

  2. Roaming Re-origination Feature. In this case, the Correlation RA is used to allocate a special routing address that is used in the Connect message on the initial dialog. A second re-originated dialog will be received by Sentinel for this special address. Sentinel uses the Correlation RA on the re-originated dialog to retrieve data that was associated with the special address via the first dialog. The associated data includes relevant details from the InitialDP of the initial dialog.

Configuring a Correlation RA entity

A Correlation RA entity configuration consists of:

The following diagram shows the Reorigination Correlation RA entity.

correlation ra
Tip The Correlation resource adaptor supports live re-configuration, so the administrator may update the configuration properties of a Correlation resource adaptor entity that has already been created.

Correlation RA configuration properties

The Correlation RA configuration properties are:

Name

Type

Description

ConfigProfileTable

String

The SLEE profile table with an RA configuration profile for this RA entity.

ConfigProfile

String

The SLEE profile in the ConfigProfileTable with configuration for this RA entity.

CorrelationIdPoolProfileTable

String

The SLEE profile table with correlation ID pool definitions for this Correlation RA entity.

For example, the Reorigination Correlation RA entity has the following configuration:

[Rhino@localhost (#9)] listraentityconfigproperties reorigination-correlation-ra
Configuration properties for resource adaptor entity reorigination-correlation-ra:
 ConfigProfile (java.lang.String): ReoriginationCorrelationConfigProfile
 ConfigProfileTable (java.lang.String): CorrelationConfigTable
 CorrelationIdPoolTable (java.lang.String): ReoriginationCorrelationIdPools

Correlation RA entity configuration profile

The Correlation RA configuration profile has the following attributes:

Name

Type

Description

RequestTimeout

Int

The maximum time (measured in ms) the Correlation RA will spend trying to allocate a correlation ID.

CorrelationIDExpiryTimerPeriod

Int

The maximum time (measured in ms) that an active correlation ID is considered to be still valid.

NumberOfThreadPool

Int

How many threads the Correlation RA entity should use.

For example, the Reorigination Correlation RA entity has the following configuration:

[Rhino@localhost (#8)] listprofileattributes CorrelationConfigTable ReoriginationCorrelationConfigProfile
CorrelationIDExpiryTimerPeriod=55000
NumberOfThreadPool=5
RequestTimeout=5000

Correlation RA entity ID pools configuration

Each Correlation RA entity has one or more correlation ID pools.

  • a default ID pool (optional)

  • a set of named ID pools. Each named ID pool is identified by a set of prefixes for choosing/selecting the ID pool. From the Correlation RA standpoint, the prefixes can be any address string. The client to the RA provides an address that the RA uses via a longestPrefix match address list search to select the pool to use.

Each correlation ID pool is defined in a SLEE profile in an ID pools profile table. There is one correlation ID pools table per Correlation RA entity.

Tip The correlation resource adaptor entity will raise an alarm if there are no correlation ID pools configured, or if there are configuration errors with the correlation ID pools.

addressPrefixes

An array of address prefixes that corresponds to this pool. The default pool has an empty addressPrefixes array.

nodeIds

An array of node IDs for which this pool has correlation IDs.

isPreconfiguredCorrelationIdSetUsed

If true, configure this ID pool with a pre-configured set of correlation IDs, else derive the correlation IDs.

preconfiguredCorrelationIdSet

The preconfigured set of correlation IDs per node (delimited with ‘:’).

minCorrelationIDInCluster

The minimum correlation ID value used in the cluster. 0 to maxCorrelationIDInCluster

maxCorrelationIDInCluster

The maximum correlation ID value used in the cluster. 0 to (10^18-1)

correlationIDNumberOfDigits

The number of digits the correlation ID should have. Minimum of number of digits in maxCorrelationIDInCluster to 18 maximum.

correlationIDRangePerNode

The number of correlation IDs that can be used for each node in the cluster.

There are two possible configuration options for correlation ID pools.

A prescribed set of IDs for each node

Defines the prescribed correlation IDs for each node in the following way:

  • NodeIds[0] — PreconfiguredCorrelationIdSet[0] which is a ‘:’ separated string containing all the correlation IDs for NodeIds[0]

  • NodeIds[1] — PreconfiguredCorrelationIdSet[1] which is a ‘:’ separated string containing all the correlation IDs for NodeIds[1]

  • etc.

Tip ‘:’ is used as a separator and not to specify a range. For example, to specify IDs 123, 124, 125 and 126 use a value of 123:124:125:126.

A range of correlation IDs (min, max) for each node

Defines the range of values used in each node in conjunction with the NodeIds attribute in the following way:

  • The node whose identifier is NodeIds[i] has a range of values of CorrelationIDRangePerNode[i]

  • Each cluster has a range of CorrelationIDs defined by: [MinCorrelationIDInCluster, MaxCorrelationIDInCluster]

These values are allocated to the different cluster nodes in the following way:

  • NodeIds[0] — [MinCorrelationIDInCluster …​ MinCorrelationIDInCluster + CorrelationIDRangePerNode[0]]

  • NodeIds[1] — [MinCorrelationIDInCluster + CorrelationIDRangePerNode[0] + 1 …​ MinCorrelationIDInCluster + +CorrelationIDRangePerNode[0] + 1 + CorrelationIDRangePerNode[1]]

  • etc.

The maximum number of correlation IDs defined in the range is 1,000,000.

Provisioning Interfaces

The Correlation RA configuration and ID pools are provisioned using the Sentinel REST API or web interface.

Monitoring Correlation RA entity statistics

Each Correlation RA entity collects the following statistics that may be monitored via the Rhino statistics client.

Counters

Name Description

correlationGets

Count of correlation IDs which have been requested via findCorrelationEntry()

localGets

Count of correlation queries which returned immediately (synchronous delivery) as the local RA had the data available.

remoteGets

Count of correlation queries which did not return immediately (asynchronous delivery) as the local RA did not have the data available.

remoteDelivery

Count of correlation queries which required delivering data to another correlation RA instance.

unknown

Count of correlation queries which could not be remotely delivered as the destination RA for a correlation ID was unknown.

Caution The count correlationGets should equal the sum of localGets + remoteGets.

These statistics can use used to create threshold-based alarms.

Using the Correlation RA

A feature uses the Correlation RA by invoking methods on the provider interface.

  • To store data for correlation, a feature calls either the getNewCorrelationID(byte[] correlationData) or the getNewCorrelationID(String associatedAddress, byte[] correlationData) method on the CorrelationProvider. These methods will store the correlation data locally, and return an identifier String (the correlation ID) which can later be used to access the data from elsewhere. This operation will flag the returned ID as ‘in use’ until it is freed (on query) or expires (on timeout).

  • To query the correlation data (for example, from another session) a feature calls the getCorrelationData(String correlationId) method on the CorrelationProvider. This returns a CorrelationResult which will either contain the requested data (if it is available locally), or a flag indicating that the data is not available locally.

  • If the data is available locally then it can be immediately access via the Handling synchronous results API call CorrelationResult.getCorrelationData()

  • If the data is only available for asynchronous delivery, CorrelationResult.isAvailableAsynchronously() will be true, and CorrelationResult.getCorrelationData() will return null. See the following section for how to handle Handling asynchronous results result delivery.

CorrelationProvider interface:

public interface CorrelationProvider {

    /**
     * Creates an activity used for async requests.
     *
     * @return
     * @throws StartActivityException
     */
    public CorrelationActivity createActivity() throws StartActivityException;

    /**
     * This returns immediately and will return a CorrelationResult. This will either contain the correlation data if this is available on
     * this node or else will contain a flag that says this is only available on another node. In the later case you should then call an
     * async request to get the data.
     *
     * @param correlationId the Correlation ID
     * @return the CorrelationResult
     * @throws UnknownCorrelationIdException if the correlation id is not known in this pool
     * @throws NoDataFoundException if there is no data found for the correlation id specified
     * @throws CorrelationIDExpiredException if the correlation id has expired
     */
    public CorrelationResult getCorrelationData(String correlationId) throws UnknownCorrelationIdException, NoDataFoundException, CorrelationIDExpiredException;

    /**
     * This will return the CorrelationResult. This method will block and only return when the CorrelationResult is available. If the data is only
     * available on a remote node this may take some time to return. This should only be used if synchronous behavior is required.
     *
     * @param correlationId
     * @return
     * @throws CorrelationRequestException
     */
    public CorrelationResult getCorrelationDataSynchronously(String correlationId) throws CorrelationRequestException;

    /**
     * Request a new Correlation ID from the default pool
     *
     * @param correlationData data to be correlated
     * @return a new Correlation ID with a correlation name that is not being used in any other session
     * @throws NoAvailableEntries if there is any problem accessing data
     */
    public String getNewCorrelationID(byte[] correlationData) throws NoAvailableEntriesException;

    /**
     * Request a new Correlation ID String from a correlation id pool associated with an address.
     *
     * @param associatedAddress an address that the correlation RA will use to select a pool from which to return a correlation id
     * @param correlationData data to be correlated
     * @return a new Correlation ID String with a correlation name that is not being used in any other session
     * @throws NoAvailableEntries if there is any problem accessing data
     */
    public String getNewCorrelationID(String associatedAddress, byte[] correlationData) throws NoAvailableEntriesException;

    /**
     * Determine if an id is a correlation id we know about
     * @param possibleCorrelationId an id we wish to check to see if it is a correlation id
     * @return true iff this id is a correlation id we know about
     */
    public boolean isValidCorrelationId(String possibleCorrelationId);
}

CorrelationResult interface:

public interface CorrelationResult {
    /**
     * Contains correlation data associated with the requested correlation ID or null if the
     * data is only available asynchronously.
     *
     * @return
     */
    public byte[] getCorrelationData();

    /**
     * String containing requested correlation ID.
     *
     * @return the String containing the Correlation ID
     */
    public String getCorrelationId();

    /**
     * If the correlation data is not available locally but is available via an asynchronous call.
     *
     * An asynchronous call can be made by creating a CorrelationActivity with the provider and then making
     * the asynchronous call on the CorrelationActivity.
     *
     * @return
     */
    public boolean isAvailableAsynchronously();
}

CorrelationActivity interface:

public interface CorrelationActivity {

    /**
     * Request the correlation data associated with the specified Correlation ID.
     *
     * The result will be fired as a {@link CorrelationResultEvent}
     * event on this activity.  Failed queries will be fired as a {@link CorrelationFailureEvent}.
     *
     * @param correlationId The Correlation ID
     */
    public void requestCorrelationData(String correlationId);

}

Handling synchronous results

Synchronous queries occur when the RA which is queried is also storing the queried information. In these circumstances, the data is included in the returned CorrelationResult from a query. The following example demonstrates how to handle synchronous return results:

private void syncRequest(byte [] correlationData) {
    //
    // Store some data against a new correlation ID.
    //
    String correlationId;
    try {
        correlationId = corrProvider.getNewCorrelationID(correlationData);
    } catch (NoAvailableEntriesException e) {
        // ... handle exception ...
        return;
    }

    // ... do work until correlation data is required again.

    // In practice, the following will usually be done in another transaction which only knows the correlation ID.
    // It is done inline here for the sake of simplicity.

    //
    // Query the saved correlation data.
    //
    try {
        CorrelationResult result = corrProvider.getCorrelationData(correlationId);
        byte [] corrData = result.getCorrelationData();
        if (corrData != null) {
           // Do something with data
        } else {
           if (result.isAvailableAsynchronously()) {
             // ... Here we could optionally proceed with an asynchronous correlation data query. See following example.
           }
        }
    } catch (UnknownCorrelationIdException e) {
        // ... handle exception ...
        return;
    } catch (NoDataFoundException e) {
        // ... handle exception ...
        return;
    } catch (CorrelationIDExpiredException e) {
        // ... handle exception ...
        return;
    }
}

Handling asynchronous results

Asynchronous result handling is required when the correlated data for the requested ID is only available from a non-local Correlation RA (that is, on a different Rhino node). After the correlation data is requested, the result is returned in a CorrelationEvent which is delivered to the service. This CorrelationEvents must be explicitly handled with a SLEE event handler.

Requesting correlation data asynchronously is done as follows:

  • Create a new correlation activity using CorrelationProvider.createActivity()

  • Get an ActivityContextInterface object for the activity.

  • Attach the SBB local object to the ACI.

  • Send the request using the requestCorrelationData(String) method on the activity.

  • Handle the result in an event handler for the com.opencloud.slee.resources.correlation.CorrelationResultEvent event.

  • Handle failures in an event handler for the com.opencloud.slee.resources.correlation.CorrelationFailureEvent event.

The follow example demonstrates the handling an asynchronous correlation query:

private void asyncRequest(String correlationId) {
    try {
        CorrelationActivity corrActivity = corrProvider.createActivity();
        ActivityContextInterface corrAci = corrACIFactory.getActivityContextInterface(corrActivity);
        corrAci.attach(getSbbLocalObject());
        corrActivity.requestCorrelationData(correlationId);
    }
    catch (StartActivityException e) {
        // ... handle exception ...
    }
}

public void onCorrelationResult(CorrelationResultEvent result, ActivityContextInterface aci) {
    aci.detach(getSbbLocalObject());
    byte [] corrData = result.getCorrelationData()
    // ... do something with the data ...
}

public void onCorrelationFailure(CorrelationFailureEvent failure, ActivityContextInterface aci) {
    aci.detach(getSbbLocalObject());
    // ... handle failure ...
}

Javadoc API

Javadoc for the Correlation RA is available here: Sentinel Correlation RA API 1.0.

Previous page Next page
Sentinel Express Version 3.1.0