JBoss.orgCommunity Documentation

Chapter 44. AJAX Client

44.1. Generated JavaScript API
44.1.1. JavaScript API servlet
44.1.2. JavaScript API usage
44.1.3. MIME types and unmarshalling.
44.1.4. MIME types and marshalling.
44.2. Using the JavaScript API to build AJAX queries
44.2.1. The REST object
44.2.2. The REST.Request class

RESTEasy resources can be accessed in JavaScript using AJAX using a proxy API generated by RESTEasy.

RESTEasy can generate a JavaScript API that uses AJAX calls to invoke JAX-RS operations.

Each JAX-RS resource class will generate a JavaScript object of the same name as the declaring class (or interface), which will contain every JAX-RS method as properties.

Each JavaScript API method takes an optional object as single parameter where each property is a cookie, header, path, query or form parameter as identified by their name, or the following special parameters:


The following special parameter names are subject to change.

Table 44.1. API parameter properties
Property name Default Description
$entity The entity to send as a PUT, POST request.
$contentType As determined by @Consumes. The MIME type of the body entity sent as the Content-Type header.
$accepts Determined by @Provides, defaults to */*. The accepted MIME types sent as the Accept header.
$callback Set to a function(httpCode, xmlHttpRequest, value) for an asynchronous call. If not present, the call will be synchronous and return the value.
$apiURL Determined by container Set to the base URI of your JAX-RS endpoint, not including the last slash.
$username If username and password are set, they will be used for credentials for the request.
$password If username and password are set, they will be used for credentials for the request.

The Accept header sent by any client JavaScript function is controlled by the $accepts parameter, which overrides the @Produces annotation on the JAX-RS endpoint. The returned value however is controlled by the Content-Type header sent in the response as follows:

Table 44.2. Return values by MIME type
MIME Description
text/xml,application/xml,application/*+xml The response entity is parsed as XML before being returned. The return value is thus a DOM Document.
application/json The response entity is parsed as JSON before being returned. The return value is thus a JavaScript Object.
Anything else The response entity is returned raw.

The Content-Type header sent in the request is controlled by the $contentType parameter which overrides the @Consumes annotation on the JAX-RS endpoint. The value passed as entity body using the $entity parameter is marshalled according to both its type and content type:

Table 44.3. Controlling sent entities
Type MIME Description
DOM Element Empty or text/xml,application/xml,application/*+xml The DOM Element is marshalled to XML before being sent.
JavaScript Object (JSON) Empty or application/json The JSON object is marshalled to a JSON string before being sent.
Anything else Anything else The entity is sent as is.

The RESTEasy JavaScript API can also be used to manually construct your requests.

The REST object contains the following read-write properties:

Table 44.4. The REST object
Property Description
apiURL Set by default to the JAX-RS root URL, used by every JavaScript client API functions when constructing the requests.
log Set to a function(string) in order to receive RESTEasy client API logs. This is useful if you want to debug your client API and place the logs where you can see them.

The REST.Request class is used to build custom requests. It has the following members:

Table 44.5. The REST.Request class
Member Description
execute(callback) Executes the request with all the information set in the current object. The value is never returned but passed to the optional argument callback.
setAccepts(acceptHeader) Sets the Accept request header. Defaults to */*.
setCredentials(username, password) Sets the request credentials.
setEntity(entity) Sets the request entity.
setContentType(contentTypeHeader) Sets the Content-Type request header.
setURI(uri) Sets the request URI. This should be an absolute URI.
setMethod(method) Sets the request method. Defaults to GET.
setAsync(async) Controls whether the request should be asynchronous. Defaults to true.
addCookie(name, value) Sets the given cookie in the current document when executing the request. Beware that this will be persistent in your browser.
addQueryParameter(name, value) Adds a query parameter to the URI query part.
addMatrixParameter(name, value) Adds a matrix parameter (path parameter) to the last path segment of the request URI.
addHeader(name, value) Adds a request header.