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
refer to the Getting Started guide how to download and deploy the package |
|
the section includes configuration properties and examples how the Correlation RA can be setup |
|
the Correlation RA provides statistics that may be monitored via the Rhino statistics client. |
|
the Correlation RA can raise the following alarms if it encounters any issues. |
|
install and run the example service included with the Correlation RA |
Configuring a Correlation RA entity
A Correlation RA entity configuration consists of:
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. |
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 |
|
Int |
The maximum time (measured in ms) that an active correlation ID is considered to be still valid. Default: 30000 |
|
Int |
How many threads the Correlation RA entity should use. Default: 5 |
|
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.
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 |
|
Array |
An array of address prefixes that corresponds to this pool. The default pool has an empty addressPrefixes array. |
|
Array |
An array of node IDs for which this pool has correlation IDs. Default: [101] |
|
Boolean |
If true, configure this ID pool with a pre-configured set of correlation IDs, else derive the correlation IDs. Default: true |
|
Array |
The preconfigured set of correlation IDs per node (delimited with ‘:’). Default: [34610000001:34610000002:34610000003] |
|
Int |
The minimum correlation ID value used in the cluster. 0 to maxCorrelationIDInCluster Default: 0 |
|
Int |
The maximum correlation ID value used in the cluster. 0 to (10^18-1) Default: 999 |
|
Int |
The number of digits the correlation ID should have. Minimum of number of digits in maxCorrelationIDInCluster to 18 maximum. Default: 10 |
|
Array |
The number of correlation IDs that can be used for each node in the cluster. Default: [1000] |
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 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.
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 |
---|---|
|
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 is triggered through asynchronous or force synchronous request, but the data is in local RA instance. |
|
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 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)
, orallocateCorrelationIDFromNamedPool(String poolName, byte[] correlationData)
methods on theCorrelationProvider
. These methods will store the correlation data locally, and return a operation result object (theAllocationResult
) which contains thecorrelationID
and themaxAllocationDuration
. 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 orgetCorrelationDataSynchronously(String correlationId)
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. Alternatively there are methodspeekCorrelationData(String correlationId)
andpeekCorrelationDataSynchronously(String correlationId)
which behave identically to theirget
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, andCorrelationResult.getCorrelationData()
will return null. See the following section for how to handle [asynchronous] result delivery.
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)
orpeekCorrelationData(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 ... }