15.11. RESTEasy JavaScript API
15.11.1. About the RESTEasy JavaScript API
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. The JavaScript object contains each JAX-RS method as properties.
Example 15.18. Simple JAX-RS JavaScript API Example
@Path("foo")
public class Foo{
@Path("{id}")
@GET
public String get(@QueryParam("order") String order, @HeaderParam("X-Foo") String header,
@MatrixParam("colour") String colour, @CookieParam("Foo-Cookie") String cookie){
&
}
@POST
public void post(String text){
}
}
We can use the previous JAX-RS API in JavaScript using the following code:
var text = Foo.get({order: 'desc', 'X-Foo': 'hello',
colour: 'blue', 'Foo-Cookie': 123987235444});
Foo.put({$entity: text});
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 API parameter properties. The properties are available here: Section 15.11.3, “RESTEasy Javascript API Parameters”.
15.11.2. Enable the RESTEasy JavaScript API Servlet
Summary
The RESTEasy JavaScript API is not enabled by default. Follow these steps to enable it using the web.xml file.
Procedure 15.6. Edit web.xml to enable RESTEasy JavaScript API
- Open the
web.xmlfile of the application in a text editor. - Add the following configuration to the file, inside the
web-apptags:<servlet> <servlet-name>RESTEasy JSAPI</servlet-name> <servlet-class>org.jboss.resteasy.jsapi.JSAPIServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>RESTEasy JSAPI</servlet-name> <url-pattern>/URL</url-pattern> </servlet-mapping>
15.11.3. RESTEasy Javascript API Parameters
| Property | Default Value | Description |
|---|---|---|
| $entity | The entity to send as a PUT, POST request. | |
| $contentType | The MIME type of the body entity sent as the Content-Type header. Determined by the @Consumes annotation. | |
| $accepts | */* | The accepted MIME types sent as the Accept header. Determined by the @Provides annotation. |
| $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 | Set to the base URI of the 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. |
15.11.4. Build AJAX Queries with the JavaScript API
Summary
The RESTEasy JavaScript API can be used to manually construct requests. This topic covers examples of this behavior.
Example 15.19. The REST Object
The REST object can be used to override RESTEasy JavaScript API client behavior:
// Change the base URL used by the API:
REST.apiURL = "http://api.service.com";
// log everything in a div element
REST.log = function(text){
jQuery("#log-div").append(text);
};
The REST object contains the following read-write properties:
- 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.
Example 15.20. The REST.Request Class
The REST.Request class can be used to build custom requests:
var r = new REST.Request();
r.setURI("http://api.service.com/orders/23/json");
r.setMethod("PUT");
r.setContentType("application/json");
r.setEntity({id: "23"});
r.addMatrixParameter("JSESSIONID", "12309812378123");
r.execute(function(status, request, entity){
log("Response is "+status);
});
15.11.5. REST.Request Class Members
| Member | Description |
|---|---|
| execute(callback) | Executes the request with all the information set in the current object. The value is passed to the optional argument callback, not returned. |
| 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. This will be persistent in the 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. |
