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:
-
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.
-
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.
Below are procedures for Configuring a Correlation RA entity, Monitoring Correlation RA entity statistics, and Using the Correlation RA.
Configuring a Correlation RA entity
A Correlation RA entity configuration consists of:
The following diagram shows the Reorigination Correlation RA entity.
![correlation ra](../../images/correlation-ra.png)
![]() |
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 |
|
String |
The SLEE profile table with an RA configuration profile for this RA entity. |
|
String |
The SLEE profile in the ConfigProfileTable with configuration for this RA entity. |
|
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 |
|
Int |
The maximum time (measured in ms) the Correlation RA will spend trying to allocate a correlation ID. |
|
Int |
The maximum time (measured in ms) that an active correlation ID is considered to be still valid. |
|
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.
![]() |
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. |
|
An array of address prefixes that corresponds to this pool. The default pool has an empty addressPrefixes array. |
|
An array of node IDs for which this pool has correlation IDs. |
|
If true, configure this ID pool with a pre-configured set of correlation IDs, else derive the correlation IDs. |
|
The preconfigured set of correlation IDs per node (delimited with ‘:’). |
|
The minimum correlation ID value used in the cluster. 0 to maxCorrelationIDInCluster |
|
The maximum correlation ID value used in the cluster. 0 to (10^18-1) |
|
The number of digits the correlation ID should have. Minimum of number of digits in maxCorrelationIDInCluster to 18 maximum. |
|
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 forNodeIds[0]
-
NodeIds[1]
—PreconfiguredCorrelationIdSet[1]
which is a ‘:’ separated string containing all the correlation IDs forNodeIds[1]
-
etc.
![]() |
‘:’ 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 ofCorrelationIDRangePerNode[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 |
---|---|
|
Count of correlation IDs which have been requested via |
|
Count of correlation queries which returned immediately (synchronous delivery) as the local RA had the data available. |
|
Count of correlation queries which did not return immediately (asynchronous delivery) as the local RA did not have the data available. |
|
Count of correlation queries which required delivering data to another correlation RA instance. |
|
Count of correlation queries which could not be remotely delivered as the destination RA for a correlation ID was unknown. |
![]() |
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 thegetNewCorrelationID(String associatedAddress, byte[] correlationData)
method on theCorrelationProvider
. 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 theCorrelationProvider
. This returns aCorrelationResult
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, andCorrelationResult.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.