Correlation Resource Adaptor

public interface CorrelationProvider {

    /**
     * Creates an activity used for async requests.
     *
     * @return a new CorrelationActivity
     * @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 the Correlation ID
     * @return the CorrelationResult, which will contain the correlation data associated to the correlation ID
     * @throws CorrelationRequestException
     */
    public CorrelationResult getCorrelationDataSynchronously(String correlationId) throws CorrelationRequestException;

    /**
     * Requests a new Correlation ID from the default pool and save the specified data against it.
     *
     * @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.
     *
     * @deprecated replaced by {@link #allocateCorrelationID(byte[])}
     */
    @Deprecated
    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.
     *
     * @deprecated replaced by {@link #allocateCorrelationID(String, byte[])}
     */
    @Deprecated
    public String getNewCorrelationID(String associatedAddress, byte[] correlationData) throws NoAvailableEntriesException;

    /**
     * Requests a new Correlation ID from the default pool and save the specified data against it.
     *
     * @param correlationData data to be correlated.
     * @return 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 NoAvailableEntries if there is any problem accessing data.
     */
    public AllocationResult allocateCorrelationID(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 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 NoAvailableEntries if there is any problem accessing data.
     */
    public AllocationResult allocateCorrelationID(String associatedAddress, byte[] correlationData) throws NoAvailableEntriesException;

    /**
     * Release a correlation ID that was allocated locally.
     *
     * @param correlationID the correlation ID to release
     * @return true if the correlation id was released; false if the correlation id was unknown, or is associated with a remote node.
     */
    public boolean releaseCorrelationID(String correlationID);

    /**
     * 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);
}

/**
 * The result of requesting a Correlation ID.
 */
public interface AllocationResult {

    /**
     * @return A new Correlation ID with a correlation name that is not being used in any other session.
     */
    String getCorrelationID();

    /**
     * @return The maximum duration before the correlation ID is considered expired and is returned to the correlation ID pool.
     */
    long getMaxAllocationDuration();
}

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();
}

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);

}