Correlation RA Overview

What is the Correlation RA?

The Correlation RA provides a mechanism to correlate two otherwise independent sessions. The correlation data is replicated across the Rhino cluster. All nodes in the cluster have access to read/write correlation data.

The Correlation RA allocates a correlation ID with the first session, that can then be used to process a second session. The SLEE Service may associate a blob of data with an allocated correlation ID.

Topics

Deploying the Correlation RA

refer to the Getting Started guide how to download and deploy the package

Configuring a Correlation RA entity

the section includes configuration properties and examples how the Correlation RA can be setup

Monitoring Correlation RA entity statistics

the Correlation RA provides statistics that may be monitored via the Rhino statistics client.

Correlation RA entity Alarms

the Correlation RA can raise the following alarms if it encounters any issues.

Using the Correlation RA

install and run the example service included with the Correlation RA

Configuring a Correlation RA entity

A Correlation RA entity configuration consists of:

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.

The example Correlation RA entity has the following configuration:

[admin@localhost (#0)] listraentityconfigproperties correlation-ra
Configuration properties for resource adaptor entity correlation-ra:
 ConfigProfile (java.lang.String): CorrelationConfigProfile
 ConfigProfileTable (java.lang.String): CorrelationConfigTable
 CorrelationIdPoolTable (java.lang.String): CorrelationIdPoolTable
 slee-vendor:com.opencloud.rhino_max_activities (java.lang.Integer): 0
 slee-vendor:com.opencloud.rhino_replicate_activities (java.lang.String): none

Correlation RA entity configuration profile

The Correlation RA configuration profile has the following attributes:

Name

Type

Description

CorrelationIDExpiryTimerPeriod

Int

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

Default: 30000

NumberOfThreadPool

Int

How many threads the Correlation RA entity should use.

Default: 5

StateDistributionTimeout

Int

The maximum time (measured in ms) that the Correlation RA entity will allow for distributing correlation state to the cluster during a RA configuration update. Correlation requests are suspended while state distribution is in progress.

Default: 3000

For example, the correlation-ra RA entity that is deployed with the example service has the following configuration:

[admin@localhost (#3)] listprofileattributes CorrelationConfigTable CorrelationConfigProfile
CorrelationIDExpiryTimerPeriod=10000
NumberOfThreadPool=20
StateDistributionTimeout=3000

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 the longest prefix 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. Click here for more information on alarms

Name

Type

Description

AddressPrefixes

Array

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

NodeIds

Array

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

Default: [101]

IsPreconfiguredCorrelationIdSetUsed

Boolean

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

Default: true

PreconfiguredCorrelationIdSet

Array

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

Default: [34610000001:34610000002:34610000003]

MinCorrelationIDInCluster

Int

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

Default: 0

MaxCorrelationIDInCluster

Int

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

Default: 999

CorrelationIDNumberOfDigits

Int

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

Default: 10

CorrelationIDRangePerNode

Array

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

Default: [1000]

Tip When updating configuration properties set them using the same setprofileattributes command i.e.
[admin@localhost (#3)] setprofileattributes CorrelationIdPoolTable _DEFAULT_ maxCorrelationIDInCluster 40000 isPreconfiguredCorrelationIdSetUsed false  PreconfiguredCorrelationIdSet [] correlationIDRangePerNode [10000,10000,10000] NodeIds [101,102,103]

There are two possible configuration options for correlation ID pools.

  • prescribed set of IDs for each node

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

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.

Correlation RA Alarms

The Correlation RA can raise the following alarms if it encounters any issues.

Category Level Alarm Type Message Description

CorrelationRA

CRITICAL

correlationra.config

Dependent on exception

A general configuration error occurred. The alarm is raised while initialising the resource adaptor and cleared when the resource adaptor is deactivated.

CorrelationRA

WARNING

correlation.pool.noids

The correlation pool ([Pool Name]) has run out of IDs.

The correlation pool has run out of IDs and requests for new IDs are being rejected. The alarm is raised when the correlation pool runs out of available IDs.

CorrelationRA

CRITICAL

correlationra.config.profile

Pools profile table '[Table Name]' not found

The pools profile table specified in the RA configuration could not be read. The alarm is cleared when the resource adaptor is deactivated.

CorrelationRA

CRITICAL

correlationra.config.profile

Could not read the RA configuration profile table '[Table Name]'

The profile table specified in the RA configuration could not be read. The alarm is cleared when the resource adaptor is deactivated.

CorrelationRA

CRITICAL

correlationra.config.profile

"Could not read the RA configuration profile '[Profile Name]'"

The profile specified in the RA configuration could not be read. The alarm is cleared when the resource adaptor is deactivated.

Deploying the Correlation RA

Refer to Correlation RA Getting Started Guide for details.

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.

localDelivery

Count of correlation queries which is triggered through asynchronous or force synchronous request, but the data is in local RA instance.

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 Service uses the Correlation RA by invoking methods on the provider interface.

  • To store data for correlation, a service calls either allocateCorrelationID(byte[] correlationData), allocateCorrelationID(String associatedAddress, byte[] correlationData), or allocateCorrelationIDFromNamedPool(String poolName, byte[] correlationData) methods on the CorrelationProvider. These methods will store the correlation data locally, and return a operation result object (the AllocationResult) which contains the correlationID and the maxAllocationDuration. 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 service calls either getCorrelationData(String correlationId) method or getCorrelationDataSynchronously(String correlationId) 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. Alternatively there are methods peekCorrelationData(String correlationId) and peekCorrelationDataSynchronously(String correlationId) which behave identically to their get counterparts except that they do not remove the stored data.

  • If the data is available locally then it can be immediately accessed via the [synchronous] 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 [asynchronous] result delivery.

Warning Take care when using the peek*() API methods. Since they do not remove the stored data the only way a correlation ID will get released back to the pool is by explicitly calling the releaseCorrelationID() method on the node where it is stored, or by waiting for it to expire. Alternatively the last lookup of a specific correlation ID could use one of the get*() methods instead of peek*().

For information on the CorrelationProvider, AllocationResult, CorrelationResult, and CorrelationActivity interfaces refer to Correlation Resource Adaptor Correlation RA Type API

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;
    AllocationResult allocationResult;
    try {
        allocationResult = corrProvider.allocateCorrelationID(correlationData);
        correlationId = allocationResult.getCorrelationID();
    } 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) or peekCorrelationData(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 ...
}