Package io.vertx.core.streams

## Interface ReadStream<T>

- All Superinterfaces:
    `StreamBase`
  All Known Subinterfaces:
    `AmqpReceiver`, `AsyncFile`, `CassandraRowStream`, `ClientWebSocket`, `GrpcClientResponse<Req,​Resp>`, `GrpcReadStream<T>`, `GrpcServerRequest<Req,​Resp>`, `HttpClientResponse`, `HttpServerFileUpload`, `HttpServerRequest`, `JsonParser`, `KafkaConsumer<K,​V>`, `KafkaReadStream<K,​V>`, `MessageConsumer<T>`, `NetSocket`, `PgChannel`, `RabbitMQConsumer`, `ReactiveReadStream<T>`, `RecordParser`, `RedisConnection`, `RowStream<T>`, `ServerWebSocket`, `SockJSSocket`, `TestSuiteReport`, `WebServerRequest`, `WebSocket`, `WebSocketBase`

      public interface ReadStream<T>
      extends StreamBase

  Represents a stream of items that can be read from.

  Any class that implements this interface can be used by a `Pipe` to pipe data from it to a `WriteStream`.

  ### Streaming mode

  The stream is either in flowing or fetch mode.
  Initially the stream is in flowing mode.
  - When the stream is in flowing mode, elements are delivered to the `handler`.
  - When the stream is in fetch mode, only the number of requested elements will be delivered to the `handler`.
  The mode can be changed with the `pause()`, `resume()` and `fetch(long)` methods:
  - Calling `resume()` sets the flowing mode
  - Calling `pause()` sets the fetch mode and resets the demand to `0`
  - Calling `fetch(long)` requests a specific amount of elements and adds it to the actual demand
  Author:
    Tim Fox

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `default Stream<T>` | `blockingStream()` | Adapt this `ReadStream` to a blocking sequential `Stream`, the return stream usage is restricted to non vertx threads or vertx virtual threads.
    `default <R,​A> Future<R>` | `collect​(Collector<T,​A,​R> collector)` | Apply a `collector` to this stream, the obtained result is returned as a future.
    `ReadStream<T>` | `endHandler​(Handler<Void> endHandler)` | Set an end handler.
    `ReadStream<T>` | `exceptionHandler​(Handler<Throwable> handler)` | Set an exception handler on the read stream.
    `ReadStream<T>` | `fetch​(long amount)` | Fetch the specified `amount` of elements.
    `ReadStream<T>` | `handler​(Handler<T> handler)` | Set a data handler.
    `ReadStream<T>` | `pause()` | Pause the `ReadStream`, it sets the buffer in `fetch` mode and clears the actual demand.
    `default Pipe<T>` | `pipe()` | Pause this stream and return a `Pipe` to transfer the elements of this stream to a destination `WriteStream`.
    `default Future<Void>` | `pipeTo​(WriteStream<T> dst)` | Pipe this `ReadStream` to the `WriteStream`.
    `ReadStream<T>` | `resume()` | Resume reading, and sets the buffer in `flowing` mode.

- - ### Method Detail

    - #### exceptionHandler

          ReadStream<T> exceptionHandler​(Handler<Throwable> handler)

      Set an exception handler on the read stream.
      Specified by:
        `exceptionHandler` in interface `StreamBase`
      Parameters:
        `handler` - the exception handler
      Returns:
        a reference to this, so the API can be used fluently

    - #### handler

          ReadStream<T> handler​(Handler<T> handler)

      Set a data handler. As data is read, the handler will be called with the data.
      Returns:
        a reference to this, so the API can be used fluently

    - #### pause

          ReadStream<T> pause()

      Pause the `ReadStream`, it sets the buffer in `fetch` mode and clears the actual demand.

      While it's paused, no data will be sent to the data `handler`.

      Returns:
        a reference to this, so the API can be used fluently

    - #### resume

          ReadStream<T> resume()

      Resume reading, and sets the buffer in `flowing` mode.

      If the `ReadStream` has been paused, reading will recommence on it.
      Returns:
        a reference to this, so the API can be used fluently

    - #### fetch

          ReadStream<T> fetch​(long amount)

      Fetch the specified `amount` of elements. If the `ReadStream` has been paused, reading will recommence with the specified `amount` of items, otherwise the specified `amount` will be added to the current stream demand.
      Returns:
        a reference to this, so the API can be used fluently

    - #### endHandler

          ReadStream<T> endHandler​(Handler<Void> endHandler)

      Set an end handler. Once the stream has ended, and there is no more data to be read, this handler will be called.
      Returns:
        a reference to this, so the API can be used fluently

    - #### pipe

          default Pipe<T> pipe()

      Pause this stream and return a `Pipe` to transfer the elements of this stream to a destination `WriteStream`.

      The stream will be resumed when the pipe will be wired to a `WriteStream`.
      Returns:
        a pipe

    - #### collect

          default <R,​A> Future<R> collect​(Collector<T,​A,​R> collector)

      Apply a `collector` to this stream, the obtained result is returned as a future.

      Handlers of this stream are affected by this operation.
      Returns:
        a future notified with result produced by the `collector` applied to this stream

    - #### blockingStream

          default Stream<T> blockingStream()

      Adapt this `ReadStream` to a blocking sequential `Stream`, the return stream usage is restricted to non vertx threads or vertx virtual threads.
      Returns:
        a blocking stream

    - #### pipeTo

          default Future<Void> pipeTo​(WriteStream<T> dst)

      Pipe this `ReadStream` to the `WriteStream`.

      Elements emitted by this stream will be written to the write stream until this stream ends or fails.

      Parameters:
        `dst` - the destination write stream
      Returns:
        a future notified when the write stream will be ended with the outcome