Request (DavidWebb 1.3.0-SNAPSHOT API)

java.lang.Object
- com.goebl.david.Request

```
public class Request
extends Object
```
Builder for an HTTP request.
You can some "real-life" usage examples at github.com/hgoebl/DavidWebb.

Author:

hgoebl

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Request.Method

Nested Classes
Modifier and Type	Class and Description
`static class`	`Request.Method`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Response<byte[]>`	`asBytes()` Execute the request and expect the result to be convertible to `byte[]`.
`Response<org.json.JSONArray>`	`asJsonArray()` Execute the request and expect the result to be convertible to `JSONArray`.
`Response<org.json.JSONObject>`	`asJsonObject()` Execute the request and expect the result to be convertible to `JSONObject`.
`Response<InputStream>`	`asStream()` Execute the request and expect the result to be convertible to `InputStream`.
`Response<String>`	`asString()` Execute the request and expect the result to be convertible to `String`.
`Response<Void>`	`asVoid()` Execute the request and expect no result payload (only status-code and headers).
`Request`	`body(Object body)` Set the payload for the request.
`Request`	`compress()` Enable compression for uploaded data.
`Request`	`connectTimeout(int connectTimeout)` See URLConnection.setConnectTimeout
`Request`	`ensureSuccess()` By calling this method, the HTTP status code is checked and a `WebbException` is thrown if the status code is not something like 2xx.
`Request`	`followRedirects(boolean auto)` See .
`String`	`getUri()` Get the URI of this request.
`Request`	`header(String name, Object value)` Set (or overwrite) a HTTP header value.
`Request`	`ifModifiedSince(long ifModifiedSince)` See URLConnection.setIfModifiedSince()
`Request`	`multipleValues()` Turn on a mode where one parameter key can have multiple values.
`Request`	`param(String name, Iterable<Object> values)` Set (or overwrite) a parameter with multiple values.
`Request`	`param(String name, Object value)` Set (or overwrite) a parameter.
`Request`	`params(Map<String,Object> valueByName)` Set (or overwrite) many parameters via a map.
`Request`	`readTimeout(int readTimeout)` See
`Request`	`retry(int retryCount, boolean waitExponential)` Set the number of retries after the first request failed.
`Request`	`useCaches(boolean useCaches)` See URLConnection.useCaches If you don't want your requests delivered from a cache, you don't have to call this method, because `false` is the default.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - multipleValues
```
public Request multipleValues()
```
    Turn on a mode where one parameter key can have multiple values.
    Example: order.php?fruit=orange&fruit=apple&fruit=banana
    This is only necessary when you want to call param(String, Object) multiple times with the same parameter name and this should lead to having multiple values. If you call param(String, Iterable) or already provide an Array as value parameter, you don't have to call this method and it should work as expected.
    
    Returns:
    
    this for method chaining (fluent API)
    
    Since:
    
    1.3.0
  - param
```
public Request param(String name,
                     Object value)
```
    Set (or overwrite) a parameter.
    The parameter will be used to create a query string for GET-requests and as the body for POST-requests with MIME-type application/x-www-form-urlencoded.
    Please see multipleValues() if you have to deal with parameters carrying multiple values.
    Handling of multi-valued parameters exists since version 1.3.0
    
    Parameters:
    
    name - the name of the parameter (it's better to use only contain ASCII characters)
    
    value - the value of the parameter; null will be converted to empty string, Arrays of Objects are expanded to multiple valued parameters, for all other objects to toString() method converts it to String
    
    Returns:
    
    this for method chaining (fluent API)
  - param
```
public Request param(String name,
                     Iterable<Object> values)
```
    Set (or overwrite) a parameter with multiple values.
    The parameter will be used to create a query string for GET-requests and as the body for POST-requests with MIME-type application/x-www-form-urlencoded.
    If you use this method, you don't have to call multipleValues(), but you should not mix using param(String, Object) and this method for the same parameter name as this might cause unexpected behaviour or exceptions.
    
    Parameters:
    
    name - the name of the parameter (it's better to use only contain ASCII characters)
    
    values - the values of the parameter; will be expanded to multiple valued parameters.
    
    Returns:
    
    this for method chaining (fluent API)
    
    Since:
    
    1.3.0
  - params
```
public Request params(Map<String,Object> valueByName)
```
    Set (or overwrite) many parameters via a map.
    
    Parameters:
    
    valueByName - a Map of name-value pairs,
    the name of the parameter (it's better to use only contain ASCII characters)
    the value of the parameter; null will be converted to empty string, for all other objects to toString() method converts it to String
    
    Returns:
    
    this for method chaining (fluent API)
  - getUri
```
public String getUri()
```
    Get the URI of this request.
    
    Returns:
    
    URI
  - header
```
public Request header(String name,
                      Object value)
```
    Set (or overwrite) a HTTP header value.
    Setting a header this way has the highest precedence and overrides a header value set on a Webb instance (Webb.setDefaultHeader(String, Object)) or a global header (Webb.setGlobalHeader(String, Object)).
    Using null or empty String is not allowed for name and value.
    Parameters:
    
    name - name of the header (HTTP-headers are not case-sensitive, but if you want to override your own headers, you have to use identical strings for the name. There are some frequently used header names as constants in Webb, see HDR_xxx.
    value - the value for the header. Following types are supported, all other types use toString of the given object:
    
    Date is converted to RFC1123 compliant String
    
    Calendar is converted to RFC1123 compliant String
    Returns:
    
    this for method chaining (fluent API)
  - body
```
public Request body(Object body)
```
    Set the payload for the request.
    Using this method together with param(String, Object) has the effect of body being ignored without notice. The method can be called more than once: the value will be stored and converted to bytes later.
    Following types are supported for the body:
    - null clears the body
    - JSONObject, HTTP header 'Content-Type' will be set to JSON, if not set
    - JSONArray, HTTP header 'Content-Type' will be set to JSON, if not set
    - String, HTTP header 'Content-Type' will be set to TEXT, if not set; Text will be converted to UTF-8 bytes.
    - byte[] the easiest way for DavidWebb - it's just passed through. HTTP header 'Content-Type' will be set to BINARY, if not set.
    - File, HTTP header 'Content-Type' will be set to BINARY, if not set; The file gets streamed to the web-server and 'Content-Length' will be set to the number of bytes of the file. There is absolutely no conversion done. So if you want to upload e.g. a text-file and convert it to another encoding than stored on disk, you have to do it by yourself.
    - InputStream, HTTP header 'Content-Type' will be set to BINARY, if not set; Similar to File. Content-Length cannot be set (which has some drawbacks compared to knowing the size of the body in advance).
      You have to care for closing the stream!
    Parameters:
    
    body - the payload
    
    Returns:
    
    this for method chaining (fluent API)
  - compress
```
public Request compress()
```
    Enable compression for uploaded data.
    
    Before you enable compression, you should find out, whether the web server you are talking to supports this. As compression has not to be implemented for HTTP and standard RFC2616 had only compression for downloaded resources in mind, in special cases it makes absolutely sense to compress the posted data.
    Your web application should inspect the 'Content-Encoding' header and implement the compression token provided by this client. By now only 'gzip' encoding token is used. If you need 'deflate' create an issue.
    
    Returns:
    
    this for method chaining (fluent API)
  - useCaches
```
public Request useCaches(boolean useCaches)
```
    See URLConnection.useCaches
    If you don't want your requests delivered from a cache, you don't have to call this method, because false is the default.
    
    Parameters:
    
    useCaches - If true, the protocol is allowed to use caching whenever it can.
    
    Returns:
    
    this for method chaining (fluent API)
  - ifModifiedSince
```
public Request ifModifiedSince(long ifModifiedSince)
```
    See URLConnection.setIfModifiedSince()
    
    Parameters:
    
    ifModifiedSince - A nonzero value gives a time as the number of milliseconds since January 1, 1970, GMT. The object is fetched only if it has been modified more recently than that time.
    
    Returns:
    
    this for method chaining (fluent API)
  - connectTimeout
```
public Request connectTimeout(int connectTimeout)
```
    See URLConnection.setConnectTimeout
    
    Parameters:
    
    connectTimeout - sets a specified timeout value, in milliseconds. 0 means infinite timeout.
    
    Returns:
    
    this for method chaining (fluent API)
  - readTimeout
```
public Request readTimeout(int readTimeout)
```
    See
    
    Parameters:
    
    readTimeout - Sets the read timeout to a specified timeout, in milliseconds. 0 means infinite timeout.
    
    Returns:
    
    this for method chaining (fluent API)
  - followRedirects
```
public Request followRedirects(boolean auto)
```
    See .
    Use this method to set the behaviour for this single request when receiving redirect responses. If you want to change the behaviour for all your requests, call Webb.setFollowRedirects(boolean).
    
    Parameters:
    
    auto - true to automatically follow redirects (HTTP status code 3xx). Default value comes from HttpURLConnection and should be true.
    
    Returns:
    
    this for method chaining (fluent API)
  - ensureSuccess
```
public Request ensureSuccess()
```
    By calling this method, the HTTP status code is checked and a WebbException is thrown if the status code is not something like 2xx.
    
    Be careful! If you request resources e.g. with ifModifiedSince(long), an exception will also be thrown in the positive case of 304 Not Modified.
    
    Returns:
    
    this for method chaining (fluent API)
  - retry
```
public Request retry(int retryCount,
                     boolean waitExponential)
```
    Set the number of retries after the first request failed.
    When `waitExponential` is set, then there will be Thread.sleep(long) between the retries. If the thread is interrupted, there will be an `InterruptedException` in the thrown `WebbException`. You can check this with Throwable.getCause(). The `interrupted` flag will be set to true in this case.
    
    Parameters:
    
    retryCount - This parameter holds the number of retries that will be made AFTER the initial send in the event of a error. If an error occurs on the last attempt an exception will be raised.
    Values > 10 are ignored (we're not gatling)
    
    waitExponential - sleep during retry attempts (exponential backoff). For retry-counts more than 3, true is mandatory.
    
    Returns:
    
    this for method chaining (fluent API)
  - asString
```
public Response<String> asString()
```
    Execute the request and expect the result to be convertible to String.
    
    Returns:
    
    the created Response object carrying the payload from the server as String
  - asJsonObject
```
public Response<org.json.JSONObject> asJsonObject()
```
    Execute the request and expect the result to be convertible to JSONObject.
    
    Returns:
    
    the created Response object carrying the payload from the server as JSONObject
  - asJsonArray
```
public Response<org.json.JSONArray> asJsonArray()
```
    Execute the request and expect the result to be convertible to JSONArray.
    
    Returns:
    
    the created Response object carrying the payload from the server as JSONArray
  - asBytes
```
public Response<byte[]> asBytes()
```
    Execute the request and expect the result to be convertible to byte[].
    
    Returns:
    
    the created Response object carrying the payload from the server as byte[]
  - asStream
```
public Response<InputStream> asStream()
```
    Execute the request and expect the result to be convertible to InputStream.
    
    Returns:
    
    the created Response object carrying the payload from the server as InputStream
  - asVoid
```
public Response<Void> asVoid()
```
    Execute the request and expect no result payload (only status-code and headers).
    
    Returns:
    
    the created Response object where no payload is expected or simply will be ignored.

Class Request

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

multipleValues

param

param

params

getUri

header

body

compress

useCaches

ifModifiedSince

connectTimeout

readTimeout

followRedirects

ensureSuccess

retry

asString

asJsonObject

asJsonArray

asBytes

asStream

asVoid