org.jooby

Interface Request

All Superinterfaces:

Registry

All Known Implementing Classes:

Request.Forwarding

public interface Request
extends Registry

Give you access at the current HTTP request in order to read parameters, headers and body.

HTTP parameter and headers

Access to HTTP parameter/header is available via param(String) and header(String) methods. See some examples:

   // str param
   String value = request.param("str").value();

   // optional str
   String value = request.param("str").value("defs");

   // int param
   int value = request.param("some").intValue();

   // optional int param
   Optional <Integer > value = request.param("some").toOptional(Integer.class);

   // list param
   List <String > values = request.param("some").toList(String.class);
 

form post/multi-param request

Due that form post are treated as HTTP params you can collect all them into a Java Object via params(Class) or form(Class) methods:

 {
   get("/search", req -> {
     Query q = req.params(Query.class);
   });

   post("/person", req -> {
     Person person = req.form(Person.class);
   });
 }
 

form file upload

Form post file upload are available via files(String) or file(String) methods:

 {
   post("/upload", req  -> {
     try(Upload upload = req.file("myfile")) {
       File file = upload.file();
       // work with file.
     }
   });
 }
 

Since:

0.1.0

Author:

edgar

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Request.Flash Flash scope.
static class	Request.Forwarding Forwarding request.

Method Summary

Modifier and Type	Method and Description
List<MediaType>	accept()
Optional<MediaType>	accepts(List<MediaType> types) Check if the given types are acceptable, returning the best match when true, or else Optional.empty.
default Optional<MediaType>	accepts(MediaType... types) Check if the given types are acceptable, returning the best match when true, or else Optional.empty.
default Optional<MediaType>	accepts(String... types) Check if the given types are acceptable, returning the best match when true, or else Optional.empty.
Map<String,Object>	attributes() A read only version of the current locals.
Mutant	body() HTTP body.
default <T> T	body(Class<T> type) Short version of body().to(type).
Charset	charset() The charset defined in the request body.
String	contextPath() Application path (a.k.a context path).
Mutant	cookie(String name) Get a cookie with the given name (if present).
List<Cookie>	cookies()
default Upload	file(String name) Get a file Upload with the given name.
List<Upload>	files() Get a list of files Upload that were uploaded in the request.
List<Upload>	files(String name) Get a list of file Upload with the given name.
default Request.Flash	flash() Give you access to flash scope.
default String	flash(String name) Get a flash attribute value or throws BAD_REQUEST error if missing.
default Request	flash(String name, Object value) Set a flash attribute.
default <T> T	form(Class<T> type) Short version of params().to(type).
default <T> T	form(Class<T> type, String... xss) Short version of params(xss).to(type).
default <T> T	get(String name) Get a request local attribute.
default <T> T	get(String name, T def) Get a request local attribute.
Mutant	header(String name) Get a HTTP header.
Mutant	header(String name, String... xss) Get a HTTP header and apply the XSS escapers.
Map<String,Mutant>	headers()
String	hostname() The fully qualified name of the resource being requested, as obtained from the Host HTTP header.
default Optional<Upload>	ifFile(String name) Get a file Upload with the given name or empty.
default Optional<String>	ifFlash(String name) Get an optional for the given flash attribute's name.
<T> Optional<T>	ifGet(String name) Get a request local attribute.
Optional<Session>	ifSession()
String	ip()
default boolean	is(List<MediaType> types) True, if request accept any of the given types.
default boolean	is(MediaType... types) True, if request accept any of the given types.
default boolean	is(String... types) True, if request accept any of the given types.
default boolean	isSet(String name)
long	length()
default Locale	locale() Get a locale that best matches the current request or the default locale as specified in application.lang.
Locale	locale(BiFunction<List<Locale.LanguageRange>,List<Locale>,Locale> filter) Get a locale that best matches the current request.
default List<Locale>	locales() Get a list of locale that best matches the current request as per Locale.filter(java.util.List<java.util.Locale.LanguageRange>, java.util.Collection<java.util.Locale>, java.util.Locale.FilteringMode).
List<Locale>	locales(BiFunction<List<Locale.LanguageRange>,List<Locale>,List<Locale>> filter) Get a list of locale that best matches the current request.
boolean	matches(String pattern) Test if the given request path matches the pattern.
default String	method()
Mutant	param(String name) Get a HTTP request parameter under the given name.
Mutant	param(String name, String... xss) Get a HTTP request parameter under the given name.
Mutant	params() Get all the available parameters.
default <T> T	params(Class<T> type) Short version of params().to(type).
default <T> T	params(Class<T> type, String... xss) Short version of params(xss).to(type).
Mutant	params(String... xss) Get all the available parameters.
default String	path() Given:
default String	path(boolean escape) Escape the path using UrlEscapers.urlFragmentEscaper().
int	port()
String	protocol()
default Request	push(String path) Send a push promise frame to the client and push the resource identified by the given path.
Request	push(String path, Map<String,Object> headers) Send a push promise frame to the client and push the resource identified by the given path.
Optional<String>	queryString() The query string, without the leading ?.
String	rawPath() Raw path, like path() but without decoding.
Route	route()
boolean	secure()
Session	session()
default Request	set(Class<?> type, Object value) Seed a RequestScoped object.
Request	set(com.google.inject.Key<?> key, Object value) Seed a RequestScoped object.
Request	set(String name, Object value) Set local attribute.
default Request	set(com.google.inject.TypeLiteral<?> type, Object value) Seed a RequestScoped object.
long	timestamp() Request timestamp.
MediaType	type()
<T> Optional<T>	unset(String name) Remove a request local attribute.
default boolean	xhr()

Methods inherited from interface org.jooby.Registry

require, require, require, require, require

Method Detail

path

@Nonnull
default String path()

Given:

  http://domain.com/some/path.html  -> /some/path.html
  http://domain.com/a.html          -> /a.html
 

Returns:

The request URL pathname.

rawPath

@Nonnull
String rawPath()

Raw path, like path() but without decoding.

Returns:

Raw path, like path() but without decoding.

queryString

@Nonnull
Optional<String> queryString()

The query string, without the leading ?.

Returns:

The query string, without the leading ?.

path

@Nonnull
default String path(boolean escape)

Escape the path using UrlEscapers.urlFragmentEscaper(). Given:

  http://domain.com/404<h1>X</h1> {@literal ->} /404%3Ch1%3EX%3C/h1%3E
 

Parameters:

escape - True if we want to escape this path.

Returns:

The request URL pathname.

contextPath

@Nonnull
String contextPath()

Application path (a.k.a context path). It is the value defined by: application.path. Default is: / This method returns empty string for /. Otherwise, it is identical the value of application.path.

Returns:

Application context path..

method

@Nonnull
default String method()

Returns:

HTTP method.

type

@Nonnull
MediaType type()

Returns:

The Content-Type header. Default is: /.

accept

@Nonnull
List<MediaType> accept()

Returns:

The value of the Accept header. Default is: /.

accepts

@Nonnull
default Optional<MediaType> accepts(String... types)

Check if the given types are acceptable, returning the best match when true, or else Optional.empty.

 // Accept: text/html
 req.accepts("text/html");
 //  => "text/html"

 // Accept: text/*, application/json
 req.accepts("text/html");
 //  => "text/html"
 req.accepts("text/html");
 //  => "text/html"
 req.accepts("application/json" "text/plain");
 //  => "application/json"
 req.accepts("application/json");
 //  => "application/json"

 // Accept: text/*, application/json
 req.accepts("image/png");
 //  => Optional.empty

 // Accept: text/*;q=.5, application/json
 req.accepts("text/html", "application/json");
 //  => "application/json"
 

Parameters:

types - Types to test.

Returns:

The best acceptable type.

matches

boolean matches(String pattern)

Test if the given request path matches the pattern.

Parameters:

pattern - A pattern to test for.

Returns:

True, if the request path matches the pattern.

is

default boolean is(String... types)

True, if request accept any of the given types.

Parameters:

types - Types to test

Returns:

True if any of the given type is accepted.

is

default boolean is(MediaType... types)

True, if request accept any of the given types.

Parameters:

types - Types to test

Returns:

True if any of the given type is accepted.

is

default boolean is(List<MediaType> types)

True, if request accept any of the given types.

Parameters:

types - Types to test

Returns:

True if any of the given type is accepted.

accepts

@Nonnull
default Optional<MediaType> accepts(MediaType... types)

Check if the given types are acceptable, returning the best match when true, or else Optional.empty.

 // Accept: text/html
 req.accepts("text/html");
 //  => "text/html"

 // Accept: text/*, application/json
 req.accepts("text/html");
 //  => "text/html"
 req.accepts("text/html");
 //  => "text/html"
 req.accepts("application/json" "text/plain");
 //  => "application/json"
 req.accepts("application/json");
 //  => "application/json"

 // Accept: text/*, application/json
 req.accepts("image/png");
 //  => Optional.empty

 // Accept: text/*;q=.5, application/json
 req.accepts("text/html", "application/json");
 //  => "application/json"
 

Parameters:

types - Types to test.

Returns:

The best acceptable type.

accepts

@Nonnull
Optional<MediaType> accepts(List<MediaType> types)

Check if the given types are acceptable, returning the best match when true, or else Optional.empty.

 // Accept: text/html
 req.accepts("text/html");
 //  => "text/html"

 // Accept: text/*, application/json
 req.accepts("text/html");
 //  => "text/html"
 req.accepts("text/html");
 //  => "text/html"
 req.accepts("application/json" "text/plain");
 //  => "application/json"
 req.accepts("application/json");
 //  => "application/json"

 // Accept: text/*, application/json
 req.accepts("image/png");
 //  => Optional.empty

 // Accept: text/*;q=.5, application/json
 req.accepts("text/html", "application/json");
 //  => "application/json"
 

Parameters:

types - Types to test for.

Returns:

The best acceptable type.

params

@Nonnull
Mutant params()

Get all the available parameters. A HTTP parameter can be provided in any of these forms:

• Path parameter, like: /path/:name or /path/{name}
• Query parameter, like: ?name=jooby
• Body parameter when Content-Type is application/x-www-form-urlencoded or multipart/form-data

Returns:

All the parameters.

params

@Nonnull
Mutant params(String... xss)

Get all the available parameters. A HTTP parameter can be provided in any of these forms:

• Path parameter, like: /path/:name or /path/{name}
• Query parameter, like: ?name=jooby
• Body parameter when Content-Type is application/x-www-form-urlencoded or multipart/form-data

Parameters:

xss - Xss filter to apply.

Returns:

All the parameters.

params

@Nonnull
default <T> T params(Class<T> type)

Short version of params().to(type).

Type Parameters:

T - Value type.

Parameters:

type - Object type.

Returns:

Instance of object.

form

@Nonnull
default <T> T form(Class<T> type)

Short version of params().to(type).

Type Parameters:

T - Value type.

Parameters:

type - Object type.

Returns:

Instance of object.

params

@Nonnull
default <T> T params(Class<T> type,
                              String... xss)

Short version of params(xss).to(type).

Type Parameters:

T - Value type.

Parameters:

type - Object type.

xss - Xss filter to apply.

Returns:

Instance of object.

form

@Nonnull
default <T> T form(Class<T> type,
                            String... xss)

Short version of params(xss).to(type).

Type Parameters:

T - Value type.

Parameters:

type - Object type.

xss - Xss filter to apply.

Returns:

Instance of object.

param

@Nonnull
Mutant param(String name)

Get a HTTP request parameter under the given name. A HTTP parameter can be provided in any of these forms:

• Path parameter, like: /path/:name or /path/{name}
• Query parameter, like: ?name=jooby
• Body parameter when Content-Type is application/x-www-form-urlencoded or multipart/form-data

The order of precedence is: path, query and body. For example a pattern like: GET /path/:name for /path/jooby?name=rocks produces:

  assertEquals("jooby", req.param(name).value());

  assertEquals("jooby", req.param(name).toList().get(0));
  assertEquals("rocks", req.param(name).toList().get(1));
 

Uploads can be retrieved too when Content-Type is multipart/form-data see Upload for more information.

Parameters:

name - A parameter's name.

Returns:

A HTTP request parameter.

param

@Nonnull
Mutant param(String name,
                      String... xss)

Get a HTTP request parameter under the given name. A HTTP parameter can be provided in any of these forms:

• Path parameter, like: /path/:name or /path/{name}
• Query parameter, like: ?name=jooby
• Body parameter when Content-Type is application/x-www-form-urlencoded or multipart/form-data

The order of precedence is: path, query and body. For example a pattern like: GET /path/:name for /path/jooby?name=rocks produces:

  assertEquals("jooby", req.param(name).value());

  assertEquals("jooby", req.param(name).toList().get(0));
  assertEquals("rocks", req.param(name).toList().get(1));
 

Uploads can be retrieved too when Content-Type is multipart/form-data see Upload for more information.

Parameters:

name - A parameter's name.

xss - Xss filter to apply.

Returns:

A HTTP request parameter.

file

@Nonnull
default Upload file(String name)
                      throws IOException

Get a file Upload with the given name. The request must be a POST with multipart/form-data content-type.

Parameters:

name - File's name.

Returns:

An Upload.

Throws:

IOException

ifFile

@Nonnull
default Optional<Upload> ifFile(String name)
                                  throws IOException

Get a file Upload with the given name or empty. The request must be a POST with multipart/form-data content-type.

Parameters:

name - File's name.

Returns:

An Upload.

Throws:

IOException

files

@Nonnull
List<Upload> files(String name)
                     throws IOException

Get a list of file Upload with the given name. The request must be a POST with multipart/form-data content-type.

Parameters:

name - File's name.

Returns:

A list of Upload.

Throws:

IOException

files

@Nonnull
List<Upload> files()
                     throws IOException

Get a list of files Upload that were uploaded in the request. The request must be a POST with multipart/form-data content-type.

Returns:

A list of Upload.

Throws:

IOException

header

@Nonnull
Mutant header(String name)

Get a HTTP header.

Parameters:

name - A header's name.

Returns:

A HTTP request header.

header

@Nonnull
Mutant header(String name,
                       String... xss)

Get a HTTP header and apply the XSS escapers.

Parameters:

name - A header's name.

xss - Xss escapers.

Returns:

A HTTP request header.

headers

@Nonnull
Map<String,Mutant> headers()

Returns:

All the headers.

cookie

@Nonnull
Mutant cookie(String name)

Get a cookie with the given name (if present).

Parameters:

name - Cookie's name.

Returns:

A cookie or an empty optional.

cookies

@Nonnull
List<Cookie> cookies()

Returns:

All the cookies.

body

@Nonnull
Mutant body()
              throws Exception

HTTP body. Please don't use this method for form submits. This method is used for getting raw data or a data like json, xml, etc...

Returns:

The HTTP body.

Throws:

Exception - If body can't be converted or there is no HTTP body.

body

@Nonnull
default <T> T body(Class<T> type)
                     throws Exception

Short version of body().to(type). HTTP body. Please don't use this method for form submits. This method is used for getting raw or a parsed data like json, xml, etc...

Type Parameters:

T - Value type.

Parameters:

type - Object type.

Returns:

Instance of object.

Throws:

Exception - If body can't be converted or there is no HTTP body.

charset

@Nonnull
Charset charset()

The charset defined in the request body. If the request doesn't specify a character encoding, this method return the global charset: application.charset.

Returns:

A current charset.

locales

@Nonnull
default List<Locale> locales()

Get a list of locale that best matches the current request as per Locale.filter(java.util.List<java.util.Locale.LanguageRange>, java.util.Collection<java.util.Locale>, java.util.Locale.FilteringMode).

Returns:

A list of matching locales or empty list.

locales

@Nonnull
List<Locale> locales(BiFunction<List<Locale.LanguageRange>,List<Locale>,List<Locale>> filter)

Get a list of locale that best matches the current request. The first filter argument is the value of Accept-Language as Locale.LanguageRange and filter while the second argument is a list of supported locales defined by the application.lang property. The next example returns a list of matching Locale instances using the filtering mechanism defined in RFC 4647:

 req.locales(Locale::filter)
 

Parameters:

filter - A locale filter.

Returns:

A list of matching locales.

locale

@Nonnull
Locale locale(BiFunction<List<Locale.LanguageRange>,List<Locale>,Locale> filter)

Get a locale that best matches the current request. The first filter argument is the value of Accept-Language as Locale.LanguageRange and filter while the second argument is a list of supported locales defined by the application.lang property. The next example returns a Locale instance for the best-matching language tag using the lookup mechanism defined in RFC 4647.

 req.locale(Locale::lookup)
 

Parameters:

filter - A locale filter.

Returns:

A matching locale.

locale

@Nonnull
default Locale locale()

Get a locale that best matches the current request or the default locale as specified in application.lang.

Returns:

A matching locale.

length

long length()

Returns:

The length, in bytes, of the request body and made available by the input stream, or -1 if the length is not known.

ip

@Nonnull
String ip()

Returns:

The IP address of the client or last proxy that sent the request.

port

int port()

Returns:

Server port, from host header or the server port where the client connection was accepted on.

route

@Nonnull
Route route()

Returns:

The currently matched Route.

hostname

@Nonnull
String hostname()

The fully qualified name of the resource being requested, as obtained from the Host HTTP header.

Returns:

The fully qualified name of the server.

session

@Nonnull
Session session()

Returns:

The current session associated with this request or if the request does not have a session, creates one.

ifSession

@Nonnull
Optional<Session> ifSession()

Returns:

The current session associated with this request if there is one.

xhr

default boolean xhr()

Returns:

True if the X-Requested-With header is set to XMLHttpRequest.

protocol

@Nonnull
String protocol()

Returns:

The name and version of the protocol the request uses in the form protocol/majorVersion.minorVersion, for example, HTTP/1.1

secure

boolean secure()

Returns:

True if this request was made using a secure channel, such as HTTPS.

set

@Nonnull
Request set(String name,
                     Object value)

Set local attribute.

Parameters:

name - Attribute's name.

value - Attribute's local. NOT null.

Returns:

This request.

flash

@Nonnull
default Request.Flash flash()
                              throws Err

Give you access to flash scope. Usage:

 {
   use(new FlashScope());

   get("/", req -> {
     Map<String, String> flash = req.flash();
     return flash;
   });
 }
 

As you can see in the example above, the FlashScope needs to be install it by calling Jooby.use(org.jooby.Jooby.Module) otherwise a call to this method ends in BAD_REQUEST.

Returns:

A mutable map with attributes from FlashScope.

Throws:

Err - Bad request error if the FlashScope was not installed it.

flash

@Nonnull
default Request flash(String name,
                               @Nullable
                               Object value)

Set a flash attribute. Flash scope attributes are accessible from template engines, by prefixing attributes with flash.. For example a call to flash("success", "OK") is accessible from template engines using flash.success

Parameters:

name - Attribute's name.

value - Attribute's value.

Returns:

This request.

ifFlash

@Nonnull
default Optional<String> ifFlash(String name)

Get an optional for the given flash attribute's name.

Parameters:

name - Attribute's name.

Returns:

Optional flash attribute.

flash

@Nonnull
default String flash(String name)
                       throws Err

Get a flash attribute value or throws BAD_REQUEST error if missing.

Parameters:

name - Attribute's name.

Returns:

Flash attribute.

Throws:

Err - Bad request error if flash attribute is missing.

isSet

default boolean isSet(String name)

Parameters:

name - Attribute's name.

Returns:

True if the local attribute is set.

ifGet

@Nonnull
<T> Optional<T> ifGet(String name)

Get a request local attribute.

Type Parameters:

T - Target type.

Parameters:

name - Attribute's name.

Returns:

A local attribute.

get

@Nonnull
default <T> T get(String name,
                           T def)

Get a request local attribute.

Type Parameters:

T - Target type.

Parameters:

name - Attribute's name.

def - A default value.

Returns:

A local attribute.

get

@Nonnull
default <T> T get(String name)

Get a request local attribute.

Type Parameters:

T - Target type.

Parameters:

name - Attribute's name.

Returns:

A local attribute.

Throws:

Err - with Status.BAD_REQUEST.

unset

@Nonnull
<T> Optional<T> unset(String name)

Remove a request local attribute.

Type Parameters:

T - Target type.

Parameters:

name - Attribute's name.

Returns:

A local attribute.

attributes

@Nonnull
Map<String,Object> attributes()

A read only version of the current locals.

Returns:

Attributes locals.

set

@Nonnull
default Request set(Class<?> type,
                             Object value)

Seed a RequestScoped object.

Parameters:

type - Object type.

value - Actual object to bind.

Returns:

Current request.

set

@Nonnull
default Request set(com.google.inject.TypeLiteral<?> type,
                             Object value)

Seed a RequestScoped object.

Parameters:

type - Seed type.

value - Actual object to bind.

Returns:

Current request.

set

@Nonnull
Request set(com.google.inject.Key<?> key,
                     Object value)

Seed a RequestScoped object.

Parameters:

key - Seed key.

value - Actual object to bind.

Returns:

Current request.

push

@Nonnull
default Request push(String path)

Send a push promise frame to the client and push the resource identified by the given path.

Parameters:

path - Path of the resource to push.

Returns:

This request.

push

@Nonnull
Request push(String path,
                      Map<String,Object> headers)

Send a push promise frame to the client and push the resource identified by the given path.

Parameters:

path - Path of the resource to push.

headers - Headers to send.

Returns:

This request.

timestamp

long timestamp()

Request timestamp.

Returns:

The time that the request was received.