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 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.

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 ...
}
Previous page