# Class RequestBuilder

java.lang.Object
com.codename1.io.rest.RequestBuilder

public class RequestBuilder extends Object
This class is used to build, invoke the http request and to get the http response

- ## Method Summary

  Modifier and Type
  Method
  Description
  `RequestBuilder`
  `acceptJson()`
  Add accept json header to the request
  `RequestBuilder`
  `basicAuth(String username, String password)`
  Add a basic authentication Authorization header
  `RequestBuilder`
  `bearer(String token)`
  Add an authorization bearer header, this is shorthand for `header("Authorization", "Bearer " + token)`
  `RequestBuilder`
  `body(Data body)`
  Sets the request body lazily.
  `RequestBuilder`
  `body(PropertyBusinessObject body)`
  Sets the request body to the JSON matching the given object
  `RequestBuilder`
  `body(String bodyContent)`
  Sets the request body
  `RequestBuilder`
  `cacheMode(ConnectionRequest.CachingMode cache)`
  Sets the caching mode for this request, see `com.codename1.io.ConnectionRequest#getCacheMode()`
  `RequestBuilder`
  `contentType(String s)`
  Sets the value of the content type
  `RequestBuilder`
  `cookiesEnabled(boolean cookiesEnabled)`
  Sets the cookiesEnabled parameter.
  `ConnectionRequest`
  `fetchAsBytes(OnComplete<Response<byte[]>> callback)`
  Executes the request asynchronously and writes the response to the provided Callback
  `ConnectionRequest`
  `fetchAsJsonList(OnComplete<Response<List>> callback)`
  Executes the request asynchronously when the server is expected to return a top-level JSON array (`[{...}, {...}]`).
  `ConnectionRequest`
  `fetchAsJsonMap(OnComplete<Response<Map>> callback)`
  Executes the request asynchronously and writes the response to the provided Callback
  `<T> ConnectionRequest`
  `fetchAsMapped(Class<T> type, OnComplete<Response<T>> callback)`
  Executes the request asynchronously, parses the JSON response, and hands the typed DTO to `callback`.
  `<T> ConnectionRequest`
  `fetchAsMappedList(Class<T> type, OnComplete<Response<List<T>>> callback)`
  List-typed variant of `#fetchAsMapped(Class, OnComplete)`.
  `ConnectionRequest`
  `fetchAsProperties(OnComplete<Response<PropertyBusinessObject>> callback, Class type)`
  Executes the request asynchronously and writes the response to the provided Callback.
  `ConnectionRequest`
  `fetchAsPropertyList(OnComplete<Response<List<PropertyBusinessObject>>> callback, Class type)`
  Executes the request asynchronously and writes the response to the provided Callback.
  `ConnectionRequest`
  `fetchAsPropertyList(OnComplete<Response<List<PropertyBusinessObject>>> callback, Class type, String root)`
  Executes the request asynchronously and writes the response to the provided Callback.
  `ConnectionRequest`
  `fetchAsString(OnComplete<Response<String>> callback)`
  Executes the request asynchronously and writes the response to the provided Callback
  `Response<byte[]>`
  `getAsBytes()`
  Executes the request synchronously
  `void`
  `getAsBytesAsync(Callback<Response<byte[]>> callback)`
  Executes the request asynchronously and writes the response to the provided Callback
  `Response<Map>`
  `getAsJsonMap()`
  Executes the request synchronously
  `ConnectionRequest`
  `getAsJsonMap(SuccessCallback<Response<Map>> callback)`
  Executes the request asynchronously and writes the response to the provided Callback
  `ConnectionRequest`
  `getAsJsonMap(SuccessCallback<Response<Map>> callback, FailureCallback<? extends Object> onError)`
  Executes the request asynchronously and writes the response to the provided Callback
  `void`
  `getAsJsonMapAsync(Callback<Response<Map>> callback)`
  Executes the request asynchronously and writes the response to the provided Callback
  `Response<PropertyBusinessObject>`
  `getAsProperties(Class type)`
  Executes the request synchronously
  `Response<List<PropertyBusinessObject>>`
  `getAsPropertyList(Class type)`
  Executes the request synchronously
  `Response<List<PropertyBusinessObject>>`
  `getAsPropertyList(Class type, String root)`
  Executes the request synchronously
  `Response<String>`
  `getAsString()`
  Executes the request synchronously
  `void`
  `getAsStringAsync(Callback<Response<String>> callback)`
  Executes the request asynchronously and writes the response to the provided Callback
  `String`
  `getRequestUrl()`
  `RequestBuilder`
  `gzip()`
  Sets the request to be a gzip request
  `RequestBuilder`
  `header(String key, String value)`
  Add a header to the request
  `RequestBuilder`
  `insecure(boolean insecure)`
  Turns off checking to make sure that SSL certificate is valid.
  `RequestBuilder`
  `jsonContent()`
  Sets both the content type and accept headers to "application/json"
  `RequestBuilder`
  `onError(ActionListener<NetworkEvent> error)`
  Invoked for exceptions or failures such as disconnect.
  `RequestBuilder`
  `onError(ActionListener<NetworkEvent> error, boolean replace)`
  Invoked for exceptions or failures such as disconnect
  `RequestBuilder`
  `onErrorCode(ErrorCodeHandler<PropertyBusinessObject> err, Class errorClass)`
  In case of an error this method is invoked asynchronously to process the error content with the JSON data and places it into a business object in the callback
  `RequestBuilder`
  `onErrorCodeBytes(ErrorCodeHandler<byte[]> err)`
  In case of an error this method is invoked asynchronously to process the error content with the byte array data
  `RequestBuilder`
  `onErrorCodeJSON(ErrorCodeHandler<Map> err)`
  In case of an error this method is invoked asynchronously to process the error content with the JSON data
  `RequestBuilder`
  `onErrorCodeString(ErrorCodeHandler<String> err)`
  In case of an error this method is invoked asynchronously to process the error content with the JSON data
  `RequestBuilder`
  `pathParam(String key, String value)`
  Add a path param to the request.
  `RequestBuilder`
  `postParameters(Boolean postParameters)`
  Overrides the default behavior of methods so they can be sent using the post/get method
  `RequestBuilder`
  `priority(byte priority)`
  Sets the priority of the request.
  `RequestBuilder`
  `queryParam(String key, String value)`
  Add a query parameter to the request
  `RequestBuilder`
  `queryParam(String key, String[] values)`
  Add multiple query parameter values to the request using same key.
  `RequestBuilder`
  `readTimeout(int timeout)`
  Sets the request read timeout.
  `RequestBuilder`
  `timeout(int timeout)`
  Sets the request timeout
  `RequestBuilder`
  `useBoolean(boolean useBoolean)`
  Indicates if JSON should treat boolean values as Boolean.
  `RequestBuilder`
  `useLongs(boolean useLongs)`
  Indicates if JSON should treat non-decimal numeric values as Long.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### insecure

    public RequestBuilder insecure(boolean insecure)

    Turns off checking to make sure that SSL certificate is valid.

    ###### Parameters

    - `insecure`: true to disable ssl certificate checking

    ###### Returns

    this request builder

  - ### useBoolean

    public RequestBuilder useBoolean(boolean useBoolean)

    Indicates if JSON should treat boolean values as Boolean. This values is set implicitly to true when reading property business objects

    ###### Parameters

    - `useBoolean`: true to return Boolean objects in JSON Maps

    ###### Returns

    this request builder

  - ### useLongs

    public RequestBuilder useLongs(boolean useLongs)

    Indicates if JSON should treat non-decimal numeric values as Long. If not set, uses the current default from the static value in JSONParser.isUseLongs

    ###### Parameters

    - `useLongs`: true to return Long objects in JSON Maps

    ###### Returns

    this request builder

  - ### cacheMode

    public RequestBuilder cacheMode(ConnectionRequest.CachingMode cache)

    Sets the caching mode for this request, see `com.codename1.io.ConnectionRequest#getCacheMode()`

    ###### Parameters

    - `cache`: the cache mode

    ###### Returns

    RequestBuilder instance

  - ### postParameters

    public RequestBuilder postParameters(Boolean postParameters)

    Overrides the default behavior of methods so they can be sent using the post/get method

    ###### Parameters

    - `postParameters`: true to force post, false to use get method. Defaults to true for all methods other than GET

    ###### Returns

    RequestBuilder instance

  - ### contentType

    public RequestBuilder contentType(String s)

    Sets the value of the content type

    ###### Parameters

    - `s`: the content type

    ###### Returns

    RequestBuilder instance

  - ### priority

    public RequestBuilder priority(byte priority)

    Sets the priority of the request.

    ###### Parameters

    - `priority`: The priority.

    ###### Returns

    RequestBuilder instance.

    ###### Since

    8.0

    ###### See also

    - ConnectionRequest#setPriority(byte)

  - ### cookiesEnabled

    public RequestBuilder cookiesEnabled(boolean cookiesEnabled)

    Sets the cookiesEnabled parameter.

    ###### Parameters

    - `cookiesEnabled`: True to enable cookies. False to disable.

    ###### Returns

    RequestBuilder instance.

    ###### Since

    8.0

  - ### pathParam

    public RequestBuilder pathParam(String key, String value)

    Add a path param to the request. For example if the request url is: http://domain.com/users/{id} The path param can be - key="id", value="1" When the request executes the path would be: http://domain.com/users/1

    ###### Parameters

    - `key`: the identifier key in the request.

    - `value`: the value to replace in the url

    ###### Returns

    RequestBuilder instance

  - ### queryParam

    public RequestBuilder queryParam(String key, String value)

    Add a query parameter to the request

    ###### Parameters

    - `key`: param key

    - `value`: param value

    ###### Returns

    RequestBuilder instance

  - ### queryParam

    public RequestBuilder queryParam(String key, String[] values)

    Add multiple query parameter values to the request using same key.

    ###### Parameters

    - `key`: param key

    - `values`: param values

    ###### Returns

    RequestBuilder instance

    ###### Since

    8.0

  - ### header

    public RequestBuilder header(String key, String value)

    Add a header to the request

    ###### Parameters

    - `key`

    - `value`

    ###### Returns

    RequestBuilder instance

  - ### body

    public RequestBuilder body(String bodyContent)

    Sets the request body

    ###### Parameters

    - `bodyContent`: request body content

    ###### Returns

    RequestBuilder instance

  - ### body

    public RequestBuilder body(Data body)

    Sets the request body lazily.

    ###### Parameters

    - `body`: Wrapper for the request body that knows how to append to an output stream.

    ###### Returns

    RequestBuilder instances

    ###### Since

    7.0

    ###### See also

    - #body(java.lang.String)

  - ### body

    public RequestBuilder body(PropertyBusinessObject body)

    Sets the request body to the JSON matching the given object

    ###### Parameters

    - `body`: request body

    ###### Returns

    RequestBuilder instance

  - ### onErrorCodeBytes

    public RequestBuilder onErrorCodeBytes(ErrorCodeHandler<byte[]> err)

    In case of an error this method is invoked asynchronously to process the error content with the byte array data

    ###### Parameters

    - `err`: the content of the error response

    ###### Returns

    RequestBuilder instance

  - ### onErrorCodeJSON

    public RequestBuilder onErrorCodeJSON(ErrorCodeHandler<Map> err)

    In case of an error this method is invoked asynchronously to process the error content with the JSON data

    ###### Parameters

    - `err`: the content of the error response

    ###### Returns

    RequestBuilder instance

  - ### onErrorCode

    public RequestBuilder onErrorCode(ErrorCodeHandler<PropertyBusinessObject> err, Class errorClass)

    In case of an error this method is invoked asynchronously to process the error content with the JSON data and places it into a business object in the callback

    ###### Parameters

    - `err`: the content of the error response

    - `errorClass`: the class of the business object into which the data is parsed

    ###### Returns

    RequestBuilder instance

  - ### onErrorCodeString

    public RequestBuilder onErrorCodeString(ErrorCodeHandler<String> err)

    In case of an error this method is invoked asynchronously to process the error content with the JSON data

    ###### Parameters

    - `err`: the content of the error response

    ###### Returns

    RequestBuilder instance

  - ### onError

    public RequestBuilder onError(ActionListener<NetworkEvent> error)

    Invoked for exceptions or failures such as disconnect. Replaces any existing callbacks previously registered with `#onError(com.codename1.ui.events.ActionListener)`

    ###### Parameters

    - `error`: callback for a networking error

    ###### Returns

    RequestBuilder instance

    ###### See also

    - #onError(com.codename1.ui.events.ActionListener, boolean)

  - ### onError

    public RequestBuilder onError(ActionListener<NetworkEvent> error, boolean replace)

    Invoked for exceptions or failures such as disconnect

    ###### Parameters

    - `error`: callback for a networking error

    - `replace`: @param replace If true, replaces the existing errorCallback(s) with the handler provided.

    ###### Returns

    RequestBuilder instance

    ###### Since

    7.0

  - ### timeout

    public RequestBuilder timeout(int timeout)

    Sets the request timeout

    ###### Parameters

    - `timeout`: request timeout in milliseconds

    ###### Returns

    RequestBuilder instance

  - ### readTimeout

    public RequestBuilder readTimeout(int timeout)

    Sets the request read timeout. Only used if `ConnectionRequest#isReadTimeoutSupported()` is true on this platform.

    ###### Parameters

    - `timeout`: The timeout.

    ###### Returns

    RequestBuilder instance.

  - ### gzip

    public RequestBuilder gzip()

    Sets the request to be a gzip request

    ###### Returns

    RequestBuilder instance

  - ### acceptJson

    public RequestBuilder acceptJson()

    Add accept json header to the request

    ###### Returns

    RequestBuilder instance

  - ### jsonContent

    public RequestBuilder jsonContent()

    Sets both the content type and accept headers to "application/json"

    ###### Returns

    RequestBuilder instance

  - ### basicAuth

    public RequestBuilder basicAuth(String username, String password)

    Add a basic authentication Authorization header

    ###### Returns

    RequestBuilder instance

  - ### bearer

    public RequestBuilder bearer(String token)

    Add an authorization bearer header, this is shorthand for `header("Authorization", "Bearer " + token)`

    ###### Parameters

    - `token`: the authorization token

    ###### Returns

    RequestBuilder instance

  - ### fetchAsString

    public ConnectionRequest fetchAsString(OnComplete<Response<String>> callback)

    Executes the request asynchronously and writes the response to the provided Callback

    ###### Parameters

    - `callback`: invoked with the result of the builder query

    ###### Returns

    the ConnectionRequest instance

  - ### getAsStringAsync

    public void getAsStringAsync(Callback<Response<String>> callback)

    Executes the request asynchronously and writes the response to the provided Callback

    ###### Parameters

    - `callback`: writes the response to this callback

    ###### Deprecated

    please use `#fetchAsString(com.codename1.util.OnComplete)` instead

  - ### getAsString

    public Response<String> getAsString()

    Executes the request synchronously

    ###### Returns

    Response Object

  - ### fetchAsBytes

    public ConnectionRequest fetchAsBytes(OnComplete<Response<byte[]>> callback)

    Executes the request asynchronously and writes the response to the provided Callback

    ###### Parameters

    - `callback`: writes the response to this callback

    ###### Returns

    the connection request instance

  - ### getAsBytesAsync

    public void getAsBytesAsync(Callback<Response<byte[]>> callback)

    Executes the request asynchronously and writes the response to the provided Callback

    ###### Parameters

    - `callback`: writes the response to this callback

    ###### Deprecated

    use `#fetchAsBytes(com.codename1.util.OnComplete)` instead

  - ### getAsBytes

    public Response<byte[]> getAsBytes()

    Executes the request synchronously

    ###### Returns

    Response Object

  - ### fetchAsJsonMap

    public ConnectionRequest fetchAsJsonMap(OnComplete<Response<Map>> callback)

    Executes the request asynchronously and writes the response to the provided Callback

    ###### Parameters

    - `callback`: writes the response to this callback

    ###### Returns

    returns the Connection Request object so it can be killed if necessary

  - ### fetchAsJsonList

    public ConnectionRequest fetchAsJsonList(OnComplete<Response<List>> callback)

    Executes the request asynchronously when the server is expected to return a top-level JSON array (`[{...}, {...}]`). Internally this funnels through the same JSON parser as `#fetchAsJsonMap(OnComplete)`, which wraps top-level arrays under the synthetic key `"root"`; this builder unwraps that key for you so the callback receives the array directly:

        Rest.get("https://api.example.com/items")
            .header("Authorization", "Bearer " + token)
            .acceptJson()
            .fetchAsJsonList(response -> {
                List items = response.getResponseData();
                renderItems(items);
            });

    If the server returns a JSON object instead of an array, the callback receives an empty list. If you don't know up-front whether the response is an array or an object, use `#fetchAsJsonMap(OnComplete)` and branch on `data.get("root") instanceof List`.

    ###### Parameters

    - `callback`: writes the response (with the unwrapped list) to this callback. Always invoked on the EDT.

    ###### Returns

    returns the Connection Request object so it can be killed if necessary

  - ### fetchAsMapped

    public <T> ConnectionRequest fetchAsMapped(Class<T> type, OnComplete<Response<T>> callback)

    Executes the request asynchronously, parses the JSON response, and hands the typed DTO to `callback`. Uses the build-time POJO binding framework: `type` must be annotated with `@Mapped` (see `com.codename1.annotations.Mapped` / `com.codename1.mapping.Mappers`) so the build registers a typed mapper for it.

        // model
        @Mapped public final class Asset {
            @JsonProperty public String id;
            @JsonProperty public String originalFileName;
        }

        // call site
        Rest.get(url + "/assets/" + id)
            .header("Authorization", "Bearer " + token)
            .acceptJson()
            .fetchAsMapped(Asset.class, response -> {
                Asset a = response.getResponseData();   // already typed -- no Map casts
                render(a);
            });

    Compared to `#fetchAsJsonMap(OnComplete)`: no `(Map) cast`, no `m.get("id")` boilerplate, no key-typo surprises at runtime. The per-class mapper is generated by the Maven plugin's `process-annotations` mojo from the `@Mapped` annotation and lives in `<basePackage>.generated.<Class>Mapper`.

    If the type has no registered mapper at runtime, the listener completes with `null` data and a non-200 response code is not synthesised -- inspect `response.getResponseCode()` to differentiate "server returned an error" from "no mapper registered".

    ###### Parameters

    - `type`: the `@Mapped` class to deserialise into
    - `callback`: invoked on the EDT with the typed result

    ###### Returns

    the Connection Request object so it can be killed if necessary

  - ### fetchAsMappedList

    public <T> ConnectionRequest fetchAsMappedList(Class<T> type, OnComplete<Response<List<T>>> callback)

    List-typed variant of `#fetchAsMapped(Class, OnComplete)`. Use when the server returns a top-level JSON array of DTOs:

        Rest.get(url + "/albums")
            .header("Authorization", "Bearer " + token)
            .acceptJson()
            .fetchAsMappedList(Album.class, response -> {
                List<Album> albums = response.getResponseData();
                renderAlbums(albums);
            });

    Internally goes through the same `{"root": [...]}` envelope as `#fetchAsJsonList(OnComplete)`, then maps each element through the registered mapper for `type`.

    ###### Parameters

    - `type`: the per-element `@Mapped` class
    - `callback`: invoked on the EDT with `List<T>` data

    ###### Returns

    the Connection Request object so it can be killed if necessary

  - ### fetchAsProperties

    public ConnectionRequest fetchAsProperties(OnComplete<Response<PropertyBusinessObject>> callback, Class type)

    Executes the request asynchronously and writes the response to the provided Callback. This fetches JSON data and parses it into a properties business object

    ###### Parameters

    - `callback`: writes the response to this callback

    - `type`: the class of the business object returned

    ###### Returns

    returns the Connection Request object so it can be killed if necessary

  - ### getAsJsonMap

    public ConnectionRequest getAsJsonMap(SuccessCallback<Response<Map>> callback)

    Executes the request asynchronously and writes the response to the provided Callback

    ###### Parameters

    - `callback`: writes the response to this callback

    ###### Returns

    returns the Connection Request object so it can be killed if necessary

    ###### Deprecated

    use `#fetchAsJsonMap(com.codename1.util.OnComplete)` instead

  - ### getAsJsonMap

    public ConnectionRequest getAsJsonMap(SuccessCallback<Response<Map>> callback, FailureCallback<? extends Object> onError)

    Executes the request asynchronously and writes the response to the provided Callback

    ###### Parameters

    - `callback`: writes the response to this callback

    - `onError`: the error callback

    ###### Returns

    returns the Connection Request object so it can be killed if necessary

    ###### Deprecated

    use `#fetchAsJsonMap(com.codename1.util.OnComplete)` instead

  - ### getAsJsonMapAsync

    public void getAsJsonMapAsync(Callback<Response<Map>> callback)

    Executes the request asynchronously and writes the response to the provided Callback

    ###### Parameters

    - `callback`: writes the response to this callback

    ###### Deprecated

    use `#fetchAsJsonMap(com.codename1.util.OnComplete)` instead

  - ### getAsJsonMap

    public Response<Map> getAsJsonMap()

    Executes the request synchronously

    ###### Returns

    Response Object

  - ### getAsProperties

    public Response<PropertyBusinessObject> getAsProperties(Class type)

    Executes the request synchronously

    ###### Parameters

    - `type`: the type of the business object to create

    ###### Returns

    Response Object

  - ### fetchAsPropertyList

    public ConnectionRequest fetchAsPropertyList(OnComplete<Response<List<PropertyBusinessObject>>> callback, Class type, String root)

    Executes the request asynchronously and writes the response to the provided Callback. This fetches JSON data and parses it into a properties business object

    ###### Parameters

    - `callback`: writes the response to this callback

    - `type`: the class of the business object returned

    - `root`: the root element's key of the structured content

    ###### Returns

    returns the Connection Request object so it can be killed if necessary

  - ### fetchAsPropertyList

    public ConnectionRequest fetchAsPropertyList(OnComplete<Response<List<PropertyBusinessObject>>> callback, Class type)

    Executes the request asynchronously and writes the response to the provided Callback. This fetches JSON data and parses it into a properties business object

    ###### Parameters

    - `callback`: writes the response to this callback

    - `type`: the class of the business object returned

    ###### Returns

    returns the Connection Request object so it can be killed if necessary

  - ### getAsPropertyList

    public Response<List<PropertyBusinessObject>> getAsPropertyList(Class type, String root)

    Executes the request synchronously

    ###### Parameters

    - `type`: the type of the business object to create

    - `root`: the root element's key of the structured content

    ###### Returns

    Response Object

  - ### getAsPropertyList

    public Response<List<PropertyBusinessObject>> getAsPropertyList(Class type)

    Executes the request synchronously

    ###### Parameters

    - `type`: the type of the business object to create

    ###### Returns

    Response Object

  - ### getRequestUrl

    public String getRequestUrl()