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

Author: FroMage

vertx-core/src/main/java/io/vertx/core/http/HttpServerResponse.java

@@ -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>
  */
@@ -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
    */
@@ -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) {
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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);
@@ -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