com.jcabi.http

Interface Request

All Known Implementing Classes:

ApacheRequest, FakeRequest, JdkRequest

@Immutable
public interface Request

RESTful request.

Instance of this class is supposed to be used this way:

 String name = new ApacheRequest("https://www.example.com:8080")
   .uri().path("/users").queryParam("id", 333).back()
   .method(Request.GET)
   .header(HttpHeaders.ACCEPT, MediaType.TEXT_XML)
   .fetch()
   .as(HttpResponse.class)
   .assertStatus(HttpURLConnection.HTTP_OK)
   .as(XmlResponse.class)
   .assertXPath("/page/links/link[@rel='see']")
   .rel("/page/links/link[@rel='see']/@href")
   .header(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON)
   .fetch()
   .as(JsonResponse.class)
   .json().getJsonObject().getString("name");

Since version 0.10 it is recommended to use RetryWire decorator to avoid accidental IOException when connection is weak or unstable, for example:

 String body = new JdkRequest("https://www.google.com")
   .through(RetryWire.class)
   .fetch()
   .body();

Instances of this interface are immutable and thread-safe.

Since:

0.8

Version:

$Id$

Author:

Yegor Bugayenko ([email protected])

See Also:

JdkRequest, ApacheRequest

Field Summary

Fields

Modifier and Type	Field and Description
static String	DELETE DELETE method name.
static String	GET GET method name.
static String	HEAD HEAD method name.
static String	OPTIONS OPTIONS method name.
static String	PATCH PATCH method name.
static String	POST POST method name.
static String	PUT PUT method name.

Method Summary

Methods

Modifier and Type	Method and Description
RequestBody	body() Get request body.
Response	fetch() Execute it with a specified HTTP method.
Response	fetch(InputStream stream) Execute this request using the content provided by the InputStream being passed as the request body.
Request	header(String name, Object value) Set request header.
Request	method(String method) Use this method.
Request	reset(String name) Remove all headers with this name.
<T extends Wire> Request	through(Class<T> type, Object... args) Send it through a decorating Wire.
RequestURI	uri() Get destination URI.

Field Detail

GET

static final String GET

GET method name.

See Also:

Constant Field Values

POST

static final String POST

POST method name.

See Also:

Constant Field Values

PUT

static final String PUT

PUT method name.

See Also:

Constant Field Values

HEAD

static final String HEAD

HEAD method name.

See Also:

Constant Field Values

DELETE

static final String DELETE

DELETE method name.

See Also:

Constant Field Values

OPTIONS

static final String OPTIONS

OPTIONS method name.

See Also:

Constant Field Values

PATCH

static final String PATCH

PATCH method name.

See Also:

Constant Field Values

Method Detail

uri

@NotNull(message="URI is never NULL")
RequestURI uri()

Get destination URI.

Returns:

The destination it is currently pointing to

body

@NotNull(message="request is never NULL")
RequestBody body()

Get request body.

Returns:

New alternated request

header

@NotNull(message="request is never NULL")
Request header(@NotNull(message="header name can\'t be NULL")
                     String name,
                     @NotNull(message="header value can\'t be NULL")
                     Object value)

Set request header.

Parameters:

name - ImmutableHeader name

value - Value of the header to set

Returns:

New alternated request

reset

@NotNull(message="alternated request is never NULL")
Request reset(@NotNull(message="header name can\'t be NULL")
                    String name)

Remove all headers with this name.

Parameters:

name - ImmutableHeader name

Returns:

New alternated request

Since:

0.10

method

@NotNull(message="request is never NULL")
Request method(@NotNull(message="method can\'t be NULL")
                     String method)

Use this method.

Parameters:

method - The method to use

Returns:

New alternated request

fetch

Response fetch()
               throws IOException

Execute it with a specified HTTP method.

Returns:

Response

Throws:

IOException - If fails to fetch HTTP request

fetch

Response fetch(InputStream stream)
               throws IOException

Execute this request using the content provided by the InputStream being passed as the request body. Note that the request MUST have an empty body when this method is being invoked, or it will throw an IllegalStateException.

Parameters:

stream - The input stream to use

Returns:

Response

Throws:

IOException - If fails to fetch HTTP request

Since:

1.8

through

<T extends Wire> Request through(Class<T> type,
                               Object... args)

Send it through a decorating Wire.

Type Parameters:

T - Type to use

Parameters:

type - Type of wire to use

args - Optional arguments for the wire constructor

Returns:

New request with a wire decorated

Since:

0.10