Class ChannelMap<T>

java.lang.Object
io.superdurable.dex.PersistenceDefinition
io.superdurable.dex.ChannelMap<T>
Type Parameters:
T - the Java message type carried by every Channel instance
public final class ChannelMap<T> extends PersistenceDefinition
Defines a durable map of named, typed Channel instances.

Use a Channel map when the instance key is selected at runtime, such as one Channel per order or tenant. Register the definition once in the Flow's PersistenceSchema, then pass the same instance key when publishing, waiting, and reading condition results. Instance keys must be nonblank and must not contain /. 

private final ChannelMap<String> commands =
        ChannelMap.define("commands", String.class);

return Wait.until(commands.forOne(orderId, "next-command"));

  • Method Details

    • define

      public static <T> ChannelMap<T> define(String name, Class<T> valueType)
      Defines a typed Channel map.
      Type Parameters:
      T - the Java message type
      Parameters:
      name - the stable Channel-map name; must not be blank or contain /
      valueType - the concrete Java class used to serialize messages
      Returns:
      the typed Channel-map definition
      Throws:
      IllegalArgumentException - if name is null, blank, or contains /
      NullPointerException - if valueType is null

    • publish

      public void publish(Context context, String instance, T value)
      Publishes one message to a map instance from the current invocation.
      Parameters:
      context - the Step or RPC invocation context
      instance - the Channel-map instance
      value - the typed message to publish

    • delete

      public void delete(Context context, String instance, String messageId)
      Stages deletion of one pending message from a Channel-map instance.

      Step and timeout-handler deletions are best-effort when the message is already absent.

      Parameters:
      context - the handler invocation context
      instance - the nonblank Channel-map instance
      messageId - the nonblank server-assigned message ID

    • size

      public int size(Context context, String instance)
      Returns the number of messages visible in one map instance.
      Parameters:
      context - the Step or RPC invocation context
      instance - the Channel-map instance
      Returns:
      the visible message count

    • pendingMessages

      public List<ChannelMessage<T>> pendingMessages(Context context, String instance)
      Returns one instance's loaded pending-message snapshot in FIFO order.

      Select the instance in the handler's options. The snapshot does not change after staged publications or deletions in the same handler.

      Parameters:
      context - the handler invocation context
      instance - the logical ChannelMap instance
      Returns:
      immutable pending message IDs and decoded values
      Throws:
      ChannelMessagesNotLoadedException - if the invocation did not load its messages

    • findPendingMessage

      public ChannelMessage<T> findPendingMessage(Context context, String instance, String messageId)
      Finds one instance message in the loaded handler snapshot.
      Parameters:
      context - the handler invocation context
      instance - the logical ChannelMap instance
      messageId - the server-assigned message ID
      Returns:
      the matching message, or null when absent from the snapshot
      Throws:
      ChannelMessagesNotLoadedException - if the invocation did not load its messages

    • getMapSize

      public int getMapSize(Context context)
      Returns the number of non-empty instances visible to the current RPC.
      Parameters:
      context - the RPC invocation context
      Returns:
      the current number of non-empty instances

    • getAllInstanceKeys

      public List<String> getAllInstanceKeys(Context context)
      Returns non-empty instance keys in ascending order for the current RPC.
      Parameters:
      context - the RPC invocation context
      Returns:
      an immutable sorted list of decoded instance keys

    • getConditionResults

      public List<T> getConditionResults(Context context, String instance)
      Returns messages consumed by a satisfied condition for one map instance.
      Parameters:
      context - the Step invocation context
      instance - the Channel-map instance used by the condition
      Returns:
      the typed condition results in server-provided order

    • forOne

      public Condition forOne(String instance)
      Creates a condition requiring exactly one message from an instance.
      Parameters:
      instance - the Channel-map instance
      Returns:
      the Channel condition

    • forOne

      public Condition forOne(String instance, String conditionId)
      Creates a named condition requiring exactly one message from an instance.
      Parameters:
      instance - the Channel-map instance
      conditionId - the condition ID used to identify its result
      Returns:
      the Channel condition

    • forN

      public Condition forN(String instance, int count)
      Creates a condition requiring exactly count messages from an instance.
      Parameters:
      instance - the Channel-map instance
      count - the required message count
      Returns:
      the Channel condition

    • forN

      public Condition forN(String instance, int count, String conditionId)
      Creates a named condition requiring exactly count messages from an instance.
      Parameters:
      instance - the Channel-map instance
      count - the required message count
      conditionId - the condition ID used to identify its results
      Returns:
      the Channel condition

    • atLeast

      public Condition atLeast(String instance, int count)
      Creates a condition requiring at least count messages from an instance.
      Parameters:
      instance - the Channel-map instance
      count - the minimum message count
      Returns:
      the Channel condition

    • atLeast

      public Condition atLeast(String instance, int count, String conditionId)
      Creates a named condition requiring at least count messages from an instance.
      Parameters:
      instance - the Channel-map instance
      count - the minimum message count
      conditionId - the condition ID used to identify its results
      Returns:
      the Channel condition

    • atMost

      public Condition atMost(String instance, int count)
      Creates a non-blocking condition consuming up to count queued messages from an instance. When its surrounding Wait completes, it consumes messages queued then. An empty queue yields none.
      Parameters:
      instance - the Channel-map instance
      count - the maximum message count
      Returns:
      the Channel condition

    • atMost

      public Condition atMost(String instance, int count, String conditionId)
      Creates a named, non-blocking condition consuming up to count queued messages from an instance. When its surrounding Wait completes, it consumes messages queued then. An empty queue yields none.
      Parameters:
      instance - the Channel-map instance
      count - the maximum message count
      conditionId - the condition ID used to identify its results
      Returns:
      the Channel condition

    • range

      public Condition range(String instance, Integer atLeast, Integer atMost)
      Creates a condition with optional message-count bounds for one instance. Dex waits only for the minimum, then consumes currently queued messages up to the maximum. A null minimum makes the condition complete immediately.
      Parameters:
      instance - the Channel-map instance
      atLeast - the minimum count, or null for no minimum
      atMost - the maximum count, or null for no maximum
      Returns:
      the Channel condition
      Throws:
      IllegalArgumentException - if both bounds are null

    • range

      public Condition range(String instance, Integer atLeast, Integer atMost, String conditionId)
      Creates a named condition with optional message-count bounds for one instance. Dex waits only for the minimum, then consumes currently queued messages up to the maximum. A null minimum makes the condition complete immediately.
      Parameters:
      instance - the Channel-map instance
      atLeast - the minimum count, or null for no minimum
      atMost - the maximum count, or null for no maximum
      conditionId - the condition ID used to identify its results
      Returns:
      the Channel condition
      Throws:
      IllegalArgumentException - if both bounds are null