com.arangodb.shaded.vertx.core.streams.Pipe Maven / Gradle / Ivy
/*
* Copyright (c) 2011-2019 Contributors to the Eclipse Foundation
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
* which is available at https://www.apache.org/licenses/LICENSE-2.0.
*
* SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
*/
package com.arangodb.shaded.vertx.core.streams;
import com.arangodb.shaded.vertx.codegen.annotations.Fluent;
import com.arangodb.shaded.vertx.codegen.annotations.VertxGen;
import com.arangodb.shaded.vertx.core.AsyncResult;
import com.arangodb.shaded.vertx.core.Future;
import com.arangodb.shaded.vertx.core.Handler;
import com.arangodb.shaded.vertx.core.Promise;
/**
* Pipe data from a {@link ReadStream} to a {@link WriteStream} and performs flow control where necessary to
* prevent the write stream buffer from getting overfull.
*
* Instances of this class read items from a {@link ReadStream} and write them to a {@link WriteStream}. If data
* can be read faster than it can be written this could result in the write queue of the {@link 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 {@link
* WriteStream} is full, and if so, the {@link ReadStream} is paused, and a {@code drainHandler} is set on the
* {@link WriteStream}.
*
* When the {@link WriteStream} has processed half of its backlog, the {@code drainHandler} will be
* called, which results in the pump resuming the {@link ReadStream}.
*
* This class can be used to pipe from any {@link ReadStream} to any {@link WriteStream},
* e.g. from an {@link com.arangodb.shaded.vertx.core.http.HttpServerRequest} to an {@link com.arangodb.shaded.vertx.core.file.AsyncFile},
* or from {@link com.arangodb.shaded.vertx.core.net.NetSocket} to a {@link com.arangodb.shaded.vertx.core.http.WebSocket}.
*
* Please see the documentation for more information.
*/
@VertxGen
public interface Pipe {
/**
* Set to {@code true} to call {@link WriteStream#end()} when the source {@code ReadStream} fails, {@code false} otherwise.
*
* @param end {@code true} to end the stream on a source {@code ReadStream} failure
* @return a reference to this, so the API can be used fluently
*/
@Fluent
Pipe endOnFailure(boolean end);
/**
* Set to {@code true} to call {@link WriteStream#end()} when the source {@code ReadStream} succeeds, {@code false} otherwise.
*
* @param end {@code true} to end the stream on a source {@code ReadStream} success
* @return a reference to this, so the API can be used fluently
*/
@Fluent
Pipe endOnSuccess(boolean end);
/**
* Set to {@code true} to call {@link WriteStream#end()} when the source {@code ReadStream} completes, {@code false} otherwise.
*
* Calling this overwrites {@link #endOnFailure} and {@link #endOnSuccess}.
*
* @param end {@code true} to end the stream on a source {@code ReadStream} completion
* @return a reference to this, so the API can be used fluently
*/
@Fluent
Pipe endOnComplete(boolean end);
/**
* Same as {@link #to(WriteStream, Handler)} but returns a {@code Future} of the asynchronous result
*/
default Future to(WriteStream dst) {
Promise promise = Promise.promise();
to(dst, promise);
return promise.future();
}
/**
* Start to pipe the elements to the destination {@code WriteStream}.
*
* When the operation fails with a write error, the source stream is resumed.
*
* @param dst the destination write stream
* @param completionHandler the handler called when the pipe operation completes
*/
void to(WriteStream dst, Handler> completionHandler);
/**
* Close the pipe.
*
* The streams handlers will be unset and the read stream resumed unless it is already ended.
*/
void close();
}