Skip to content

Commit

Permalink
Raw body data support in the HTTP response. Added JavaDocs to the API.
Browse files Browse the repository at this point in the history
  • Loading branch information
@nmihajlovski
nmihajlovski committed Dec 25, 2015
1 parent 8e2d63b commit bcbf676
Show file tree
Hide file tree
Showing 4 changed files with 250 additions and 56 deletions.
191 changes: 148 additions & 43 deletions rapidoid-commons/src/main/java/org/rapidoid/http/Req.java
View file
Expand Up @@ -27,149 +27,254 @@
import org.rapidoid.annotation.Authors;
import org.rapidoid.annotation.Since;

/**
* HTTP Request API.
*/
@Authors("Nikolche Mihajlovski")
@Since("5.0.2")
public interface Req {

/* REQUEST METHODS: */
/* HTTP REQUEST DATA */

/** Gets the <b>verb</b> of the HTTP request. */
String verb();

/** Sets the <b>verb</b> of the HTTP request. */
Req verb(String verb);

/** Gets the <b>uri</b> of the HTTP request. */
String uri();

/** Sets the <b>uri</b> of the HTTP request. */
Req uri(String uri);

/** Gets the <b>path</b> of the HTTP request. */
String path();

/** Sets the <b>path</b> of the HTTP request. */
Req path(String path);

/** Gets the <b>query</b> of the HTTP request. */
String query();

/** Sets the <b>query</b> of the HTTP request. */
Req query(String query);

/** Gets the <b>raw body data</b> of the HTTP request. */
byte[] body();

/** Sets the <b>raw body data</b> of the HTTP request. */
Req body(byte[] body);

/* IP ADDRESS : */

String clientIpAddress();

/* HEADERS: */

/** Gets the value of the <b>Host header</b> of the HTTP request. */
String host();

String forwardedForAddress();
/** Sets the value of the <b>Host header</b> of the HTTP request. */
Req host(String host);

/* UNIQUE CONNECTION ID: */
/** Gets the <b>IP address</b> of the HTTP client sending the request. */
String clientIpAddress();

/** Gets the <b>HTTP connection ID</b>, which is unique per HTTP server instance. */
long connectionId();

/* UNIQUE REQUEST ID: */

/** Gets the <b>HTTP request ID</b>, which is unique per HTTP server instance. */
long requestId();

/* URL PARAMETERS: */

/** Gets the <b>URL parameters</b> of the HTTP request. */
Map<String, String> params();

/**
* Returns the value of the specified <b>mandatory URL parameter</b> from the HTTP request, or throws a runtime
* exception if it is not found.
*/
String param(String name);

/**
* Returns the value of the specified <b>optional URL parameter</b> from the HTTP request, or the specified default
* value, if not found.
*/
String param(String name, String defaultValue);

/* REQUEST HEADERS: */

Map<String, String> headers();

String header(String name);

String header(String name, String defaultValue);

/* REQUEST COOKIES: */

Map<String, String> cookies();

String cookie(String name);

String cookie(String name, String defaultValue);

/* POSTED PARAMS IN REQUEST BODY: */
/* POSTED PARAMETERS IN THE REQUEST BODY: */

/** Gets the <b>posted parameters</b> of the HTTP request body. */
Map<String, Object> posted();

/**
* Returns the value of the specified <b>posted parameter</b> from the HTTP request body, or throws a runtime
* exception if it is not found.
*/
<T extends Serializable> T posted(String name);

/**
* Returns the value of the specified <b>posted parameter</b> from the HTTP request body, or the specified default
* value, if it is not found.
*/
<T extends Serializable> T posted(String name, T defaultValue);

/* POSTED FILES IN REQUEST BODY: */
/* POSTED FILES IN THE REQUEST BODY: */

/** Gets the <b>posted files</b> from the HTTP request body. */
Map<String, byte[]> files();

/**
* Returns the content of the <b>posted file</b> from the HTTP request body, or throws a runtime exception if it is
* not found.
*/
byte[] file(String name);

/**
* Returns the content of the <b>posted file</b> from the HTTP request body, or the specified default value, if it
* is not found.
*/
byte[] file(String name, byte[] defaultValue);

/* REQUEST DATA (URL PARAMS + POSTED DATA): */
/* REQUEST DATA PARAMETERS (URL PARAMETERS + POSTED PARAMETERS + POSTED FILES): */

/**
* Data includes params + posted.
*/
/** Gets the <b>data parameters (URL parameters + posted parameters + posted files)</b> of the HTTP request. */
Map<String, Object> data();

/**
* Data includes params + posted.
* Returns the value of the specified <b>data parameter</b> from the HTTP request, or throws a runtime exception if
* it is not found.
*/
<T> T data(String name);

/**
* Data includes params + posted.
* Returns the value of the specified <b>data parameter</b> from the HTTP request, or the specified default value,
* if it is not found.
*/
<T> T data(String name, T defaultValue);

/* CUSTOM REQUEST ATTRIBUTES: */
/* EXTRA ATTRIBUTES ATTACHED TO THE REQUEST: */

/** Gets the <b>extra attributes</b> of the HTTP request. */
Map<String, Object> attrs();

/**
* Returns the value of an <b>extra attribute</b> from the HTTP request, or throws a runtime exception if it is not
* found.
*/
<T> T attr(String name);

/**
* Returns the value of the specified <b>extra attribute</b> from the HTTP request, or the specified default value,
* if it is not found.
*/
<T> T attr(String name, T defaultValue);

/* SESSION: */

boolean hasSession();
/* SERVER-SIDE SESSION: */

/**
* Returns the ID of the session (the value of the <b>"JSESSIONID" cookie</b>). If a session doesn't exist, a new
* session is created.
*/
String sessionId();

/** Does the HTTP request have a server-side session attached? */
boolean hasSession();

/** Gets the <b>server-side session attributes</b> of the HTTP request. */
Map<String, Serializable> session();

/**
* Returns the value of the specified <b>server-side session attribute</b> from the HTTP request, or throws a
* runtime exception if it is not found.
*/
<T extends Serializable> T session(String name);

/**
* Returns the value of the specified <b>server-side session attribute</b> from the HTTP request, or the specified
* default value, if it is not found.
*/
<T extends Serializable> T session(String name, T defaultValue);

/* COOKIEPACK: */
/* COOKIE-PERSISTED SESSION: */

/** Does the HTTP request have a cookie-persisted session attached? */
boolean hasCookiepack();

/** Gets the <b>cookie-persisted session attributes</b> of the HTTP request. */
Map<String, Serializable> cookiepack();

/**
* Returns the value of the specified <b>cookie-persisted session attribute</b> from the HTTP request, or throws a
* runtime exception if it is not found.
*/
<T extends Serializable> T cookiepack(String name);

/**
* Returns the value of the specified <b>cookie-persisted session attribute</b> from the HTTP request, or the
* specified default value, if it is not found.
*/
<T extends Serializable> T cookiepack(String name, T defaultValue);

/* REQUEST HEADERS: */

/** Gets the <b>headers</b> of the HTTP request. */
Map<String, String> headers();

/**
* Returns the value of the specified <b>header</b> from the HTTP request, or throws a runtime exception if it is
* not found.
*/
String header(String name);

/**
* Returns the value of the specified <b>header</b> from the HTTP request, or the specified default value, if it is
* not found.
*/
String header(String name, String defaultValue);

/* REQUEST COOKIES: */

/** Gets the <b>cookies</b> of the HTTP request. */
Map<String, String> cookies();

/**
* Returns the value of the specified <b>cookie</b> from the HTTP request, or throws a runtime exception if it is
* not found.
*/
String cookie(String name);

/**
* Returns the value of the specified <b>cookie</b> from the HTTP request, or the specified default value, if it is
* not found.
*/
String cookie(String name, String defaultValue);

/* RESPONSE: */

/** Gets the reference to the <b>response object</b>. */
Resp response();

/**
* Renders the response headers based on the response() object, and then returns an <i>OutputStream</i> representing
* the <b>response body</b>. The response body will be constructed by rendering to the <i>OutputStream</i>.
*/
OutputStream out();

Req done();

boolean isDone();
/* ASYNCHRONOUS REQUEST HANDLING: */

/**
* Informs the HTTP server that the request will be handled asynchronously (typically on another thread). When the
* response is complete, <b>the <code>Req#done()</code> or <code>Resp#done()</code> method must be called</b>, to
* inform the server.
*/
Req async();

/** Is/was the request being handled in asynchronous mode? */
boolean isAsync();

/**
* Informs the HTTP server that the asynchronous handling has finished and the response is complete.
*/
Req done();

/** Has the request handling and response construction finished? */
boolean isDone();

}

0 comments on commit bcbf676

Please sign in to comment.