io.vertx.core.streams

## Interface Pipe<T>

-     public interface Pipe<T>

  Pipe data from a `ReadStream` to a `WriteStream` and performs flow control where necessary to prevent the write stream buffer from getting overfull.

  Instances of this class read items from a `ReadStream` and write them to a `WriteStream`. If data can be read faster than it can be written this could result in the write queue of the `WriteStream` growing without bound, eventually causing it to exhaust all available RAM.

  To prevent this, after each write, instances of this class check whether the write queue of the `WriteStream` is full, and if so, the `ReadStream` is paused, and a `drainHandler` is set on the `WriteStream`.

  When the `WriteStream` has processed half of its backlog, the `drainHandler` will be called, which results in the pump resuming the `ReadStream`.

  This class can be used to pipe from any `ReadStream` to any `WriteStream`, e.g. from an `HttpServerRequest` to an `AsyncFile`, or from `NetSocket` to a `WebSocket`.

  Please see the documentation for more information.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close the pipe.
    `Pipe<T>` | `endOnComplete(boolean end)` Set to `true` to call `WriteStream.end()` when the source `ReadStream` completes, `false` otherwise.
    `Pipe<T>` | `endOnFailure(boolean end)` Set to `true` to call `WriteStream.end()` when the source `ReadStream` fails, `false` otherwise.
    `Pipe<T>` | `endOnSuccess(boolean end)` Set to `true` to call `WriteStream.end()` when the source `ReadStream` succeeds, `false` otherwise.
    `default Future<Void>` | `to(WriteStream<T> dst)` Same as `to(WriteStream, Handler)` but returns a `Future` of the asynchronous result
    `void` | `to(WriteStream<T> dst, Handler<AsyncResult<Void>> completionHandler)` Start to pipe the elements to the destination `WriteStream`.

- - ### Method Detail

    - #### endOnFailure

          Pipe<T> endOnFailure(boolean end)

      Set to `true` to call `WriteStream.end()` when the source `ReadStream` fails, `false` otherwise.
      Parameters:
        `end` - `true` to end the stream on a source `ReadStream` failure
      Returns:
        a reference to this, so the API can be used fluently

    - #### endOnSuccess

          Pipe<T> endOnSuccess(boolean end)

      Set to `true` to call `WriteStream.end()` when the source `ReadStream` succeeds, `false` otherwise.
      Parameters:
        `end` - `true` to end the stream on a source `ReadStream` success
      Returns:
        a reference to this, so the API can be used fluently

    - #### endOnComplete

          Pipe<T> endOnComplete(boolean end)

      Set to `true` to call `WriteStream.end()` when the source `ReadStream` completes, `false` otherwise.

      Calling this overwrites `endOnFailure(boolean)` and `endOnSuccess(boolean)`.

      Parameters:
        `end` - `true` to end the stream on a source `ReadStream` completion
      Returns:
        a reference to this, so the API can be used fluently

    - #### to

          default Future<Void> to(WriteStream<T> dst)

      Same as `to(WriteStream, Handler)` but returns a `Future` of the asynchronous result

    - #### to

          void to(WriteStream<T> dst,
                  Handler<AsyncResult<Void>> completionHandler)

      Start to pipe the elements to the destination `WriteStream`.

      When the operation fails with a write error, the source stream is resumed.

      Parameters:
        `dst` - the destination write stream
        `completionHandler` - the handler called when the pipe operation completes

    - #### close

          void close()

      Close the pipe.

      The streams handlers will be unset and the read stream resumed unless it is already ended.

Copyright © 2023 Eclipse. All rights reserved.