JBoss.orgCommunity Documentation

Chapter 53. AJAX Client

53.1. Generated JavaScript API
53.1.1. JavaScript API servlet
53.1.2. JavaScript API usage
53.1.3. Work with @Form
53.1.4. MIME types and unmarshalling.
53.1.5. MIME types and marshalling.
53.2. Using the JavaScript API to build AJAX queries
53.2.1. The REST object
53.2.2. The REST.Request class
53.3. Caching Features

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:

Warning

The following special parameter names are subject to change.

Table 53.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.

@Form is a RESTEasy specific annotation that allows you to re-use any @*Param annotation within an injected class. The generated JavaScript API will expand the parameters for use automatically. Support we have the following form:

public class MyForm {

    @FormParam("stuff")
    private String stuff;
    @FormParam("number")
    private int number;
    @HeaderParam("myHeader")
    private String header;
}

And the resource is like:

@Path("/")

public class MyResource {
    @POST
    public String postForm(@Form MyForm myForm) {...}
}

Then we could call the method from JavaScript API like following:

MyResource.postForm({stuff:"A", myHeader:"B", number:1});

Also, @Form supports prefix mappings for lists and maps:

public static class Person {

    @Form(prefix="telephoneNumbers") List<TelephoneNumber> telephoneNumbers;
    @Form(prefix="address") Map<String, Address> addresses;
}
public static class TelephoneNumber {
    @FormParam("countryCode") private String countryCode;
    @FormParam("number") private String number;
}
public static class Address {
    @FormParam("street") private String street;
    @FormParam("houseNumber") private String houseNumber;
}
@Path("person")
public static class MyResource {
    @POST
    public void postForm(@Form Person p) {...} 
}

From JavaScript we could call the API like this:

MyResource.postForm({
	telephoneNumbers:[
		{"telephoneNumbers[0].countryCode":31},
		{"telephoneNumbers[0].number":12345678},
		{"telephoneNumbers[1].countryCode":91},
		{"telephoneNumbers[1].number":9717738723}
	],
	address:[
		{"address[INVOICE].street":"Main Street"},
		{"address[INVOICE].houseNumber":2},
		{"address[SHIPPING].street":"Square One"},
		{"address[SHIPPING].houseNumber":13}
	]
});

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 53.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 53.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.Request class is used to build custom requests. It has the following members:

Table 53.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.

RESTEasy AJAX Client works well with server side caching features. But the buggy browsers cache will always prevent the function to work properly. If you'd like to use RESTEasy's caching feature with its AJAX client, you can enable 'antiBrowserCache' option:

REST.antiBrowserCache = true;

The above setting should be set once before you call any APIs.