org.apache.ode.bpel.dao

## Interface CorrelatorDAO

- All Known Implementing Classes:
    CorrelatorDAOImpl

      public interface CorrelatorDAO

  Data access object representing a correlator. A correlator does not have a simple explanation: it acts as match-maker connecting messages with message consumers (i.e. BPEL pick and receive operations) across time. For each partnerLink "myRole" and operation there is one correlator.

  The correlator functions as a two-sided queue: when a message is received the correlator is used to dequeue a consumer based on the keys from the message. If no consumer matches the keys in the message, the message itself is enqueued along with its keys. Conversely, when a BPEL pick/receive operation is performed, the correlator is used to dequeue a message matching a given correlation key. If no message is found, the consumer (i.e. the pick/receive operation) is enqueued along with the target key.

  The end result is matching of messages to pick/receive operations, irrespective of whether the operation or the message arrives first. Make sense?

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addRoute(java.lang.String routeGroupId, ProcessInstanceDAO target, int index, CorrelationKeySet correlationKeySet, java.lang.String routePolicy)` Add a route from the given correlation key to the given process instance.
    `boolean` | `checkRoute(CorrelationKeySet correlationKeySet)` Check if corresponding key set is free to register (see ODE-804)
    `MessageExchangeDAO` | `dequeueMessage(CorrelationKeySet correlationKeySet)` Dequeue a message exchange matching a correlationKey constraint.
    `void` | `enqueueMessage(MessageExchangeDAO mex, CorrelationKeySet correlationKeySet)` Enqueue a message exchange to the queue with a set of correlation keys.
    `java.util.List<MessageRouteDAO>` | `findRoute(CorrelationKeySet correlationKeySet)` Deprecated. Find a route matching the given correlation key.
    `java.util.List<MessageRouteDAO>` | `findRoute(CorrelationKeySet correlationKeySet, boolean isCorrleationKeySetPreInitialized)` Find a route matching the given correlation key set.
    `java.util.Collection<CorrelatorMessageDAO>` | `getAllMessages()`
    `java.util.Collection<MessageRouteDAO>` | `getAllRoutes()`
    `java.lang.String` | `getCorrelatorId()` Get the correlator identifier.
    `void` | `removeRoutes(java.lang.String routeGroupId, ProcessInstanceDAO target)` Remove all routes with the given route-group identifier.
    `void` | `setCorrelatorId(java.lang.String newId)`

- - ### Method Detail

    - #### getCorrelatorId

          java.lang.String getCorrelatorId()

      Get the correlator identifier.
      Returns:
        correlator identifier

    - #### setCorrelatorId

          void setCorrelatorId(java.lang.String newId)

    - #### enqueueMessage

          void enqueueMessage(MessageExchangeDAO mex,
                            CorrelationKeySet correlationKeySet)

      Enqueue a message exchange to the queue with a set of correlation keys.
      Parameters:
        `mex` - message exchange
        `correlationKeys` - pre-computed set of correlation keys for this message

    - #### dequeueMessage

          MessageExchangeDAO dequeueMessage(CorrelationKeySet correlationKeySet)

      Dequeue a message exchange matching a correlationKey constraint.
      Parameters:
        `correlationKey` - correlation correlationKey constraint
      Returns:
        opaque message-related data previously enqueued with the given correlation correlationKey

    - #### getAllMessages

          java.util.Collection<CorrelatorMessageDAO> getAllMessages()

      Returns:
        all messages waiting on this correlator, use with care as it can potentially return a lot of values

    - #### findRoute

          java.util.List<MessageRouteDAO> findRoute(CorrelationKeySet correlationKeySet)

      Deprecated. Find a route matching the given correlation key.
      Parameters:
        `correlationKey` - correlation key
      Returns:
        route matching the given correlation key
      See Also:
        `findRoute(CorrelationKeySet correlationKeySet,boolean isCorrleationKeySetPreInitialized)`

    - #### checkRoute

          boolean checkRoute(CorrelationKeySet correlationKeySet)

      Check if corresponding key set is free to register (see ODE-804)
      Parameters:
        `correlationKeySet` -
      Returns:
        true - available, false - not available

    - #### addRoute

          void addRoute(java.lang.String routeGroupId,
                      ProcessInstanceDAO target,
                      int index,
                      CorrelationKeySet correlationKeySet,
                      java.lang.String routePolicy)

      Add a route from the given correlation key to the given process instance.
      Parameters:
        `routeGroupId` - identifier of the group of routes to which this route belongs
        `target` - target process instance
        `index` - relative order in which the route should be considered
        `correlationKey` - correlation key to match

    - #### removeRoutes

          void removeRoutes(java.lang.String routeGroupId,
                          ProcessInstanceDAO target)

      Remove all routes with the given route-group identifier.
      Parameters:
        `routeGroupId` -

    - #### getAllRoutes

          java.util.Collection<MessageRouteDAO> getAllRoutes()

      Returns:
        all routes registered on this correlator, use with care as it can potentially return a lot of values

    - #### findRoute

          java.util.List<MessageRouteDAO> findRoute(CorrelationKeySet correlationKeySet,
                                                  boolean isCorrleationKeySetPreInitialized)

      Find a route matching the given correlation key set. If the correlationKeySet is known to be pre initialized then isCorrleationKeySetPreInitialized can be set to true or false otherwise. Depending on the value of isCorrleationKeySetPreInitialized, true - canonical value of the correlationKeySet might be used to find the route. false - canonical value of each of the subset of correlationKeySet might be used to find the route.
      Parameters:
        `correlationKeySet` - correlation key
        `isCorrleationKeySetPreInitialized` -
      Returns:
        route matching the given correlation key