io.muserver.MuResponse Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of mu-server Show documentation
A simple but powerful web server framework
The newest version!
package io.muserver;

import java.io.OutputStream;
import java.io.PrintWriter;
import java.net.URI;

/**
 * A response sent to a client.
 * The {@link #status(int)} and {@link #headers()} methods are used to set the response code and response headers.
 * The {@link #addCookie(Cookie)} method can be used to add a cookie to the response.
 * There are several ways to send data back to the client:
 * 
 *     {@link #write(String)} to send a text response without chunking.
 *     {@link #sendChunk(String)} to send a chunk of text (unlike write it can be called multiple times)
 *     {@link #outputStream()} to send bytes
 *     {@link #writer()} to send text as an output stream.
 * 
 * Note: only one of the above methods can be used per response, and aside from sendChunk
 * it is not allowed to call the same method more than once..
 */
public interface MuResponse {

    /**
     * @return The HTTP status of this request.
     */
    int status();

    /**
     * Sets the response code for this request. Defaults to 200
     * @param value The response code to send to the client.
     */
    void status(int value);

    /**
     * Writes the given text as the response body for this request. This can only be called once.
     * If you want to send multiple chunks of text, see {@link #sendChunk(String)}
     * @param text The full response body to send to the client.
     * @throws IllegalStateException Thrown if this is called twice, or this is called after any other body-writing methods.
     */
    void write(String text);

    /**
     * Immediately sends the given text to the client as a chunk.
     * @param text Text to send to the client as an HTTP chunk.
     * @throws IllegalStateException Thrown if {@link #write(String)} or {@link #outputStream()} or {@link #writer()} was
     * already called.
     */
    void sendChunk(String text);

    /**
     * Redirects to the given URL. If relative, it will be converted to an absolute URL.
     * The response code will be 302 unless the status is already set to 300, 301, or 303.
     * @param url The full or relative URL to redirect to.
     */
    void redirect(String url);

    /**
     * Redirects to the given URL. If relative, it will be converted to an absolute URL.
     * The response code will be 302 unless the status is already set to 300, 301, or 303.
     * @param uri The full or relative URI to redirect to.
     */
    void redirect(URI uri);

    /**
     * Gets the response headers map which can be used to specify response headers. Example:
     * response.headers().set("access-control-allow-origin", "*");
     * @return The response headers map that can be used to set headers.
     */
    Headers headers();

    /**
     * Sets the Content-Type response header.
     * @see ContentTypes
     * @param contentType The content type of the response, for example application/json
     */
    void contentType(CharSequence contentType);

    /**
     * Sends a cookie to the client.
     * Example: response.addCookie(new Cookie("user", user));
     * If using HTTPS, it's recommended to use response.addCookie(Cookie.secureCookie("user", user));
     * @param cookie A cookie to store on the client.
     */
    void addCookie(io.muserver.Cookie cookie);

    /**
     * Gets a buffered output stream that can send data to the client.
     * To set the size of the buffer, use @{link {@link #outputStream(int)}} instead.
     * If you are writing text, you may prefer the {@link #writer()} or {@link #sendChunk(String)} methods.
     * @return An output stream to send data to the client.
     */
    OutputStream outputStream();

    /**
     * Gets a buffered output stream that can send data to the client.
     * If you are writing text, you may prefer the {@link #writer()} or {@link #sendChunk(String)} methods.
     * @param bufferSize The size of the output buffer, e.g. 8192, or 0 if you do not want to buffer the response bytes.
     * @return An output stream to send data to the client.
     */
    OutputStream outputStream(int bufferSize);

    /**
     * A print writer that can be used to send text to the client. It is a convenience method, wrapping {@link #outputStream()}
     * in a PrintWriter.
     * You may prefer using {@link #sendChunk(String)} or {@link #write(String)} to send text.
     * @return A print writer that can be used to send text to the client.
     */
    PrintWriter writer();

    /**
     * Specifies whether or not any response data has already been sent to the client. Note that once any data is sent to
     * the client then {@link #status(int)} and {@link #headers()} can no longer be changed.
     * @return Returns true if any data has been sent to the client; otherwise false.
     */
    boolean hasStartedSendingData();

    /**
     * @return The current state of this response
     */
    ResponseState responseState();
}