Client API. The Codename One framework your app is built on: this runs on the device, not in a backend.

public class RequestBuilder

  1. Object
  2. RequestBuilder
This class is used to build, invoke the http request and to get the http response

Methods

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

Inherited methods

From Object

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

Method details

insecure

public RequestBuilder insecure(boolean insecure)
Turns off checking to make sure that SSL certificate is valid.

Parameters

insecure boolean
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 boolean
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 boolean
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 ConnectionRequest.CachingMode
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 Boolean
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 String
the content type

Returns

RequestBuilder instance

priority

public RequestBuilder priority(byte priority)
Sets the priority of the request.

Parameters

priority byte
The priority.

Returns

RequestBuilder instance.

See also

cookiesEnabled

public RequestBuilder cookiesEnabled(boolean cookiesEnabled)
Sets the cookiesEnabled parameter.

Parameters

cookiesEnabled boolean
True to enable cookies. False to disable.

Returns

RequestBuilder instance.

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 String
the identifier key in the request.
value String
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 String
param key
value String
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 String
param key
values String[]
param values

Returns

RequestBuilder instance

header

public RequestBuilder header(String key, String value)
Add a header to the request

Returns

RequestBuilder instance

body

public RequestBuilder body(String bodyContent)
Sets the request body

Parameters

bodyContent String
request body content

Returns

RequestBuilder instance

body

public RequestBuilder body(Data body)
Sets the request body lazily.

Parameters

body Data
Wrapper for the request body that knows how to append to an output stream.

Returns

RequestBuilder instances

See also

body

public RequestBuilder body(PropertyBusinessObject body)
Sets the request body to the JSON matching the given object

Parameters

body PropertyBusinessObject
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 ErrorCodeHandler<byte[]>
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 ErrorCodeHandler<Map>
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 ErrorCodeHandler<PropertyBusinessObject>
the content of the error response
errorClass Class
the class of the business object into which the data is parsed

Returns

RequestBuilder instance

followRedirects

public RequestBuilder followRedirects(boolean follow)
In case of an error this method is invoked asynchronously to process the error content with the JSON data

Parameters

follow boolean
false to refuse redirects

Returns

RequestBuilder instance Whether this request may follow a redirect. Requests follow them by default.

Turn it off for a request that carries CREDENTIALS. A redirect is followed with the same headers, so a 307 hands the Authorization header – and the body – to whatever host the response names, including an http:// one, which silently undoes a caller that was careful to use HTTPS. A 302 or 303 is not safer, only different: it turns a POST into a GET and the final 2xx then reports success for a write that never happened.

ConnectionRequest has always had this per request; this passes it through, which is all that was missing.

onErrorCodeString

public RequestBuilder onErrorCodeString(ErrorCodeHandler<String> err)

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 ActionListener<NetworkEvent>
callback for a networking error

Returns

RequestBuilder instance

See also

onError

public RequestBuilder onError(ActionListener<NetworkEvent> error, boolean replace)
Invoked for exceptions or failures such as disconnect

Parameters

error ActionListener<NetworkEvent>
callback for a networking error
replace boolean
If true, replaces the existing errorCallback(s) with the handler provided.

Returns

RequestBuilder instance

timeout

public RequestBuilder timeout(int timeout)
Sets the request timeout

Parameters

timeout int
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 int
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 String
the authorization token

Returns

RequestBuilder instance

authorizer

public RequestBuilder authorizer(RequestAuthorizer authorizer)

Gives the request an authorizer: the source of its Authorization header, renewed and sent again once if the service answers 401. See RequestAuthorizer.

Without this call the request uses whatever NetworkManager.setAuthorizer(String, RequestAuthorizer) registered for its URL. A header set with header(String, String), bearer(String) or basicAuth(String, String) wins over either. The blocking methods of this builder, such as getAsString(), return the final answer like the asynchronous ones: a renewal and the second attempt happen before they do.

Parameters

authorizer RequestAuthorizer
the authorizer, or RequestAuthorizer.NONE to send this request without even the default one

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 OnComplete<Response<String>>
invoked with the result of the builder query

Returns

the ConnectionRequest instance

getAsStringAsync

public void getAsStringAsync(Callback<Response<String>> callback)
Deprecated. please use #fetchAsString(com.codename1.util.OnComplete) instead
Executes the request asynchronously and writes the response to the provided Callback

Parameters

callback Callback<Response<String>>
writes the response to this callback

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 OnComplete<Response<byte[]>>
writes the response to this callback

Returns

the connection request instance

getAsBytesAsync

public void getAsBytesAsync(Callback<Response<byte[]>> callback)
Deprecated. use #fetchAsBytes(com.codename1.util.OnComplete) instead
Executes the request asynchronously and writes the response to the provided Callback

Parameters

callback Callback<Response<byte[]>>
writes the response to this callback

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 OnComplete<Response<Map>>
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 OnComplete<Response<List>>
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 Class<T>
the @Mapped class to deserialise into
callback OnComplete<Response<T>>
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 Class<T>
the per-element @Mapped class
callback OnComplete<Response<List<T>>>
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 OnComplete<Response<PropertyBusinessObject>>
writes the response to this callback
type Class
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)
Deprecated. use #fetchAsJsonMap(com.codename1.util.OnComplete) instead
Executes the request asynchronously and writes the response to the provided Callback

Parameters

callback SuccessCallback<Response<Map>>
writes the response to this callback

Returns

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

getAsJsonMap

public ConnectionRequest getAsJsonMap(SuccessCallback<Response<Map>> callback, FailureCallback<? extends Object> onError)
Deprecated. use #fetchAsJsonMap(com.codename1.util.OnComplete) instead
Executes the request asynchronously and writes the response to the provided Callback

Parameters

callback SuccessCallback<Response<Map>>
writes the response to this callback
onError FailureCallback<? extends Object>
the error callback

Returns

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

getAsJsonMapAsync

public void getAsJsonMapAsync(Callback<Response<Map>> callback)
Deprecated. use #fetchAsJsonMap(com.codename1.util.OnComplete) instead
Executes the request asynchronously and writes the response to the provided Callback

Parameters

callback Callback<Response<Map>>
writes the response to this callback

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 Class
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 OnComplete<Response<List<PropertyBusinessObject>>>
writes the response to this callback
type Class
the class of the business object returned
root String
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 OnComplete<Response<List<PropertyBusinessObject>>>
writes the response to this callback
type Class
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 Class
the type of the business object to create
root String
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 Class
the type of the business object to create

Returns

Response Object

getRequestUrl

public String getRequestUrl()