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

      All Methods Instance Methods Abstract Methods Default Methods 
      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, java.lang.Object item)
      Offers the item to all supplied edge ordinals.
      boolean offer​(int ordinal, java.lang.Object item)
      Offers the supplied item to the bucket with the supplied ordinal.
      default boolean offer​(java.lang.Object item)
      Offers the item to all edges.
      boolean offerToSnapshot​(java.lang.Object key, java.lang.Object value)
      Offers the given key and value pair to the processor's snapshot storage.

    • Method Detail

      • 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
              java.lang.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
              java.lang.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
                        java.lang.Object key,
                        @Nonnull
                        java.lang.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
                      java.lang.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.