Package com.opencloud.slee.resources.correlation

Interface CorrelationProvider

  • @ResourceAdaptorType(id=@ComponentId(name="Correlation RA Type",vendor="OpenCloud",version="1.1"),vendorExtensionID="correlation",description="Correlation Resource Adaptor Type",eventTypeRefs={@EventTypeReference(eventType=@ComponentId(name="com.opencloud.slee.resources.correlation.CorrelationFailure",vendor="OpenCloud",version="1.1")),@EventTypeReference(eventType=@ComponentId(name="com.opencloud.slee.resources.correlation.CorrelationResult",vendor="OpenCloud",version="1.1"))},raTypeClasses=@ResourceAdaptorTypeClasses(activityTypes=@ActivityType(activityTypeName="com.opencloud.slee.resources.correlation.CorrelationActivity"),acInterfaceFactoryInterface=@ActivityContextInterfaceFactoryInterface(aciFactoryInterfaceName="com.opencloud.slee.resources.correlation.CorrelationActivityContextInterfaceFactory"),resourceAdaptorInterface=@ResourceAdaptorInterface(resourceAdaptorInterfaceName="com.opencloud.slee.resources.correlation.CorrelationProvider")))
public interface CorrelationProvider
    Defines the provider interface used by services to obtain an unused Correlation ID.

    The Correlation RA may be configured with zero or more correlation id pools and a default correlation id pool. Each pool is identified by one or more prefixes for addresses that should be associated with the pool. The correlation resource adapter will do a longest prefix max on the associated address to choose the correlation id pool to use. If the address does not correspond to a pool, then the default correlation id pool is used.

    Alternatively it is possible to refer to a pool directly by name.

    Synchronous requests

    The procedure to make synchronous requests is:

    1. request a new Correlation ID by calling the CorrelationProvider.allocateCorrelationID(byte []) method
    2. a new Correlation ID is returned
    3. at a later point when required request the data associated with the Correlation ID
    Example Synchronous Request 
         private void syncRequest(byte [] correlationData) {
         AllocationResult allocationResult;
         try {
             allocationResult = corrProvider.allocateCorrelationID(correlationData);
         } catch (NoAvailableEntriesException e) {
             // ... handle exception ...
             return;
         }

         final String correlationId = allocationResult.getCorrelationID();

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

         try {
             byte [] corrData = getCorrelationData(correlationId);
         } catch (UnknownCorrelationIdException e) {
             // ... handle exception ...
             return;
         } catch (NoDataFoundException e) {
             // ... handle exception ...
             return;
         } catch (CorrelationIDExpiredException e) {
             // ... handle exception ...
             return;
         }
     }

    • Method Detail

      • getCorrelationDataSynchronously

        CorrelationResult getCorrelationDataSynchronously​(String correlationId)
                                           throws CorrelationRequestException
        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.
        Parameters:
        correlationId - the Correlation ID
        Returns:
        the CorrelationResult, which will contain the correlation data associated to the correlation ID
        Throws:
        CorrelationRequestException - if there was a problem looking up the correlation data

      • peekCorrelationDataSynchronously

        CorrelationResult peekCorrelationDataSynchronously​(String correlationId)
                                            throws CorrelationRequestException
        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.
        Unlike getCorrelationDataSynchronously(String) this will not remove the stored data. This means that the correlation ID will only be released if
        • The get*() API is used with the same correlation ID,
        • the releaseCorrelationID(String) method is called on the node storing the data, or
        • the correlation ID expires.
        Parameters:
        correlationId - the Correlation ID
        Returns:
        the CorrelationResult, which will contain the correlation data associated to the correlation ID
        Throws:
        CorrelationRequestException - if there was a problem looking up the correlation data

      • allocateCorrelationID

        AllocationResult allocateCorrelationID​(byte[] correlationData)
                                throws NoAvailableEntriesException
        Requests a new Correlation ID from the default pool and save the specified data against it.
        Parameters:
        correlationData - data to be correlated.
        Returns:
        a new AllocationResult with a Correlation ID String with a correlation name that is not being used in any other session and the maximum duration the ID has been allocated.
        Throws:
        NoAvailableEntriesException - if there is any problem accessing data.

      • allocateCorrelationID

        AllocationResult allocateCorrelationID​(String associatedAddress,
                                       byte[] correlationData)
                                throws NoAvailableEntriesException
        Request a new Correlation ID String from a correlation id pool associated with an address.
        Parameters:
        associatedAddress - an address that the correlation RA will use to select a pool from which to return a correlation id.
        correlationData - data to be correlated.
        Returns:
        a new AllocationResult with a Correlation ID String with a correlation name that is not being used in any other session and the maximum duration the ID has been allocated.
        Throws:
        NoAvailableEntriesException - if there is any problem accessing data.

      • allocateCorrelationIDFromNamedPool

        AllocationResult allocateCorrelationIDFromNamedPool​(String poolName,
                                                    byte[] correlationData)
                                             throws NoAvailableEntriesException
        Request a new Correlation ID String from a correlation id pool associated with a name.
        Parameters:
        poolName - the name of the pool from which to return a correlation id.
        correlationData - data to be correlated.
        Returns:
        a new AllocationResult with a Correlation ID String with a correlation name that is not being used in any other session and the maximum duration the ID has been allocated.
        Throws:
        NoAvailableEntriesException - if there is any problem accessing data.

      • releaseCorrelationID

        boolean releaseCorrelationID​(String correlationID)
        Release a correlation ID that was allocated locally.
        Parameters:
        correlationID - the correlation ID to release
        Returns:
        true if the correlation id was released; false if the correlation id was unknown, or is associated with a remote node.

      • isValidCorrelationId

        boolean isValidCorrelationId​(String possibleCorrelationId)
        Determine if an id is a correlation id we know about.
        Parameters:
        possibleCorrelationId - an id we wish to check to see if it is a correlation id.
        Returns:
        true iff this id is a correlation id we know about.