Skip to content

Clarify how to terminate an http response in the javadoc #5737

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 3, 2025
Merged

Clarify how to terminate an http response in the javadoc #5737

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 53 additions & 2 deletions vertx-core/src/main/java/io/vertx/core/http/HttpServerResponse.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,11 @@
* <p>
* It implements {@link io.vertx.core.streams.WriteStream} so it can be used with
* {@link io.vertx.core.streams.Pipe} to pipe data with flow control.
* <p>
* Any response should end with a terminal action, which are {@link #end()} or {@link #sendFile(String)} for successful
* completion of the request, or {@link #reset()} for erroneous completion of the request, so you can only call one of
* the three methods as the last step in dealing with your response, but you must call one of the three methods.
* </p>
*
* @author <a href="http://tfox.org">Tim Fox</a>
*/
Expand Down Expand Up @@ -281,6 +286,11 @@ public interface HttpServerResponse extends WriteStream<Buffer> {
* the actual response won't get written until this method gets called.
* <p>
* Once the response has ended, it cannot be used any more.
* </p>
* <p>
* This is a terminal action, like {@link #sendFile(String)} and {@link #reset()}, so you can only call one of the
* three methods as the last step in dealing with your response.
* </p>
*
* @return a future completed with the body result
*/
Expand Down Expand Up @@ -335,7 +345,11 @@ default Future<Void> send(ReadStream<Buffer> body) {
*
* <p> If the {@link HttpHeaders#CONTENT_LENGTH} is set then the request assumes this is the
* length of the {stream}, otherwise the request will set a chunked {@link HttpHeaders#CONTENT_ENCODING}.
*
* </p>
* <p>
* This is a terminal action, like {@link #end()} and {@link #reset()}, so you can only call one of the
* three methods as the last step in dealing with your response.
* </p>
* @return a future notified when the response has been written
*/
default Future<Void> sendFile(String filename) {
Expand All @@ -345,6 +359,10 @@ default Future<Void> sendFile(String filename) {
/**
* Same as {@link #sendFile(String, long, long)} using length @code{Long.MAX_VALUE} which means until the end of the
* file.
* <p>
* This is a terminal action, like {@link #end()} and {@link #reset()}, so you can only call one of the
* three methods as the last step in dealing with your response.
* </p>
*
* @param filename path to the file to serve
* @param offset offset to start serving from
Expand All @@ -360,6 +378,10 @@ default Future<Void> sendFile(String filename, long offset) {
* (where supported by the underlying operating system.
* This is a very efficient way to serve files.<p>
* The actual serve is asynchronous and may not complete until some time after this method has returned.
* <p>
* This is a terminal action, like {@link #end()} and {@link #reset()}, so you can only call one of the
* three methods as the last step in dealing with your response.
* </p>
*
* @param filename path to the file to serve
* @param offset offset to start serving from
Expand All @@ -371,6 +393,10 @@ default Future<Void> sendFile(String filename, long offset) {
/**
* Same as {@link #sendFile(FileChannel, long)} using length @code{Long.MAX_VALUE} which means until the end of the
* file.
* <p>
* This is a terminal action, like {@link #end()} and {@link #reset()}, so you can only call one of the
* three methods as the last step in dealing with your response.
* </p>
*
* @param channel the file channel to the file to serve
* @return a future completed with the body result
Expand All @@ -384,6 +410,10 @@ default Future<Void> sendFile(FileChannel channel) {
/**
* Same as {@link #sendFile(FileChannel, long, long)} using length @code{Long.MAX_VALUE} which means until the end of the
* file.
* <p>
* This is a terminal action, like {@link #end()} and {@link #reset()}, so you can only call one of the
* three methods as the last step in dealing with your response.
* </p>
*
* @param channel the file channel to the file to serve
* @param offset offset to start serving from
Expand All @@ -404,6 +434,10 @@ default Future<Void> sendFile(FileChannel channel, long offset) {
* The actual serve is asynchronous and may not complete until some time after this method has returned.
* The developer is responsible to set the adequate Content-Type with {@link #putHeader(String, String)}. If not
* application/octet-stream will be set as default Content-Type.
* <p>
* This is a terminal action, like {@link #end()} and {@link #reset()}, so you can only call one of the
* three methods as the last step in dealing with your response.
* </p>
*
* @param channel the file channel to the file to serve
* @param offset offset to start serving from
Expand All @@ -416,6 +450,10 @@ default Future<Void> sendFile(FileChannel channel, long offset) {

/**
* Same as {@link #sendFile(FileChannel)} with {@link RandomAccessFile}
* <p>
* This is a terminal action, like {@link #end()} and {@link #reset()}, so you can only call one of the
* three methods as the last step in dealing with your response.
* </p>
*
* @param file the file to serve
* @return a future completed with the body result
Expand All @@ -429,6 +467,10 @@ default Future<Void> sendFile(RandomAccessFile file) {
/**
*
* Same as {@link #sendFile(FileChannel, long)} with {@link RandomAccessFile}
* <p>
* This is a terminal action, like {@link #end()} and {@link #reset()}, so you can only call one of the
* three methods as the last step in dealing with your response.
* </p>
*
* @param file the file to serve
* @param offset offset to start serving from
Expand All @@ -442,6 +484,10 @@ default Future<Void> sendFile(RandomAccessFile file, long offset) {

/**
* Same as {@link #sendFile(FileChannel, long, long)} with {@link RandomAccessFile}
* <p>
* This is a terminal action, like {@link #end()} and {@link #reset()}, so you can only call one of the
* three methods as the last step in dealing with your response.
* </p>
*
* @param file the file to serve
* @param offset offset to start serving from
Expand Down Expand Up @@ -540,7 +586,8 @@ default Future<HttpServerResponse> push(HttpMethod method, String path) {
Future<HttpServerResponse> push(HttpMethod method, HostAndPort authority, String path, MultiMap headers);

/**
* Reset this HTTP/2 stream with the error code {@code 0}.
* Equivalent to calling {@link #reset(long)} with {@code 0}.
* @see #reset(long)
*/
default Future<Void> reset() {
return reset(0L);
Expand All @@ -555,6 +602,10 @@ default Future<Void> reset() {
* </ul>
* <p/>
* When the response has already been sent nothing happens and {@code false} is returned as indicator.
* <p>
* This is a terminal action, like {@link #end()} and {@link #sendFile(String)}, so you can only call one of the three
* methods as the last step in dealing with your response.
* </p>
*
* @param code the error code
* @return {@code true} when reset has been performed
Expand Down
Loading