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:
    3.0

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and 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 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
                                          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 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 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 may only be called from the `Processor.saveToSnapshot()` method.

      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 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 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 class javadoc.

Copyright © 2020. All rights reserved.