Package com.hazelcast.jet.core

Interface Outbox

All Known Implementing Classes:
TestOutbox
public interface Outbox
Data sink for a Processor. The outbox consists of individual output buckets, one per outbound edge of the vertex represented by the associated processor and one for the snapshot state. The processor must deliver its output items separated by destination edge into the outbox by calling offer(int, Object) or offer(Object).

To save its current state to the snapshot, it must call offerToSnapshot(Object, Object) from its implementation of saveToSnapshot().

The outbox has finite capacity and will eventually refuse an item. If one of the offer() methods returns false, the calling processor must return from its callback method and retry delivering the same item when Jet calls its method again.

Thread safety

You must offer to outbox only from the thread that called the processor's methods. For example, you must not offer to outbox from a callback of an asynchronous operation. If you need that, you have to employ a concurrent queue, add to it in the callback and drain it in e.g. Processor.tryProcess().
Since:
Jet 3.0

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    bucketCount()
    Returns the number of buckets in this outbox.
    boolean
    hasUnfinishedItem()
    Returns true if this outbox has an unfinished item and the same item must be offered again.
    boolean
    offer(int[] ordinals, Object item)
    Offers the item to all supplied edge ordinals.
    boolean
    offer(int ordinal, Object item)
    Offers the supplied item to the bucket with the supplied ordinal.
    default boolean
    offer(Object item)
    Offers the item to all edges.
    boolean
    offerToSnapshot(Object key, Object value)
    Offers the given key and value pair to the processor's snapshot storage.

  • Method Details

    • bucketCount

      int bucketCount()
      Returns the number of buckets in this outbox. This is equal to the number of output edges of the vertex and does not include the snapshot bucket.

    • offer

      @CheckReturnValue boolean offer(int ordinal, @Nonnull Object item)
      Offers the supplied item to the bucket with the supplied ordinal.

      Items offered to outbox should not be subsequently mutated because the same instance might be used by a downstream processor in different thread, causing concurrent access.

      Outbox is not thread safe, see Thread safety in its class javadoc.

      Parameters:
      ordinal - output ordinal number or -1 to offer to all ordinals
      Returns:
      true if the outbox accepted the item

    • offer

      @CheckReturnValue boolean offer(@Nonnull int[] ordinals, @Nonnull Object item)
      Offers the item to all supplied edge ordinals. See offer(int, Object) for more details.

      Outbox is not thread safe, see Thread safety in its class javadoc.

      Returns:
      true if the outbox accepted the item

    • offerToSnapshot

      @CheckReturnValue boolean offerToSnapshot(@Nonnull Object key, @Nonnull Object value)
      Offers the given key and value pair to the processor's snapshot storage.

      The type of the offered key determines which processors receive the key and value pair when it is restored. If the key is of type BroadcastKey, the entry will be restored to all processor instances. Otherwise, the key will be distributed according to default partitioning and only a single processor instance will receive the key.

      This method must only be called from the Processor.saveToSnapshot() or Processor.snapshotCommitPrepare() methods.

      Keys and values offered to snapshot are serialized and can be further mutated as soon as this method returns.

      Outbox is not thread safe, see Thread safety in its class javadoc.

      Returns:
      true if the outbox accepted the item

    • offer

      @CheckReturnValue default boolean offer(@Nonnull Object item)
      Offers the item to all edges. See offer(int, Object) for more details.

      Outbox is not thread safe, see Thread safety in its class javadoc.

      Returns:
      true if the outbox accepted the item

    • hasUnfinishedItem

      boolean hasUnfinishedItem()
      Returns true if this outbox has an unfinished item and the same item must be offered again. If it returns false, it is safe to offer a new item.

      Outbox is not thread safe, see Thread safety in its class javadoc.