Interface UmaDbStream

public interface UmaDbStream
A handle on an active server stream, used to control demand and to cancel the stream.

An instance is handed to UmaDbStreamObserver.onStart(UmaDbStream) before any event is delivered, and is also returned from the call that opened the stream.

Flow control

By default a stream runs in push mode: the client requests one batch at a time and automatically asks for the next one once UmaDbStreamObserver.onNext(Object) returns. Nothing is buffered, so a slow consumer naturally slows the server down.

Calling request(long) from within UmaDbStreamObserver.onStart(UmaDbStream) switches the stream to pull mode: no batch is delivered unless it has been requested, and the consumer becomes responsible for asking for more. This is useful when a consumer wants to control exactly how much data is in flight.

Memory

The events held in memory at any moment are roughly outstanding demand × batch size, where the batch size is the one configured on the ReadRequest or SubscribeRequest. Requesting very large amounts on a subscription, which never ends, is how you run out of memory.

Thread safety

Both methods are safe to call from any thread.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    cancel()
    Cancels the stream.
    boolean
    isActive()
    Returns whether the stream is still running, i.e.
    void
    request(long count)
    Requests count further batches.

  • Method Details

    • request

      void request(long count)
      Requests count further batches.

      Demand is additive. Calling this for the first time from UmaDbStreamObserver.onStart(UmaDbStream) switches the stream to pull mode.

      Parameters:
      count - the number of additional batches to deliver; must be > 0
      Throws:
      IllegalArgumentException - if count is not positive

    • cancel

      void cancel()
      Cancels the stream.

      Idempotent, and safe to call from any thread, including from inside a callback. After cancellation at most one further terminal signal is delivered to the observer.

    • isActive

      boolean isActive()
      Returns whether the stream is still running, i.e. it has neither completed, nor failed, nor been cancelled.
      Returns:
      true while the stream is live