JBoss.orgCommunity Documentation

Chapter 7. Errai JAX-RS

7.1. Creating Requests
7.1.1. Proxy Injection
7.2. Handling Responses
7.3. Wire Format
7.4. Errai JAX-RS Configuration

JAX-RS (Java API for RESTful Web Services) is a Java EE standard (JSR-311) for implementing REST-based Web services in Java. Errai JAX-RS brings this standard to the browser and simplifies the integration of REST-based services in GWT client applications. Errai can generate proxies based on JAX-RS interfaces which will handle all the underlying communication and serialization logic. All that's left to do is to invoke a Java method. We have provided a Maven archetype which will create a fully function CRUD application using JAX-RS. See the Quickstart Guide for details.

The JAX-RS interface needs to be visible to the GWT compiler and should therefore reside within the client packages (e.g. client.shared).

Assuming the following simple JAX-RS interface should be used:


To create a request on the client, all that needs to be done is to invoke RestClient.create() , thereby providing the JAX-RS interface, a response callback and to invoke the corresponding interface method:


For details on the callback mechanism see Section 7.2, “Handling Responses” .

An instance of Errai's RemoteCallback<T> has to be passed to the RestClient.create() call, which will provide access to the JAX-RS resource method's result. T is the return type of the JAX-RS resource method. In the example below it's just a Long representing a customer ID, but it can be any serializable type (see Chapter 4, Marshalling ).

RemoteCallback<Long> callback = new RemoteCallback<Long>() {

  public void callback(Long id) {
    Window.alert("Customer created with ID: " + id);
  }
};

A special case of this RemoteCallback is the ResponseCallback which provides access to the Response object representing the underlying HTTP response. This is useful when more details of the HTTP response are needed, such as headers, the status code, etc. This ResponseCallback can be provided as an alternative to the RemoteCallback for the method result.

ResponseCallback callback = new ResponseCallback() {

  public void callback(Response response) {
    Window.alert("HTTP status code: " + response.getStatusCode());
    Window.alert("HTTP response body: " + response.getText());
  }
};

For handling errors, Errai's error callback mechanism can be reused and an instance of ErrorCallback can optionally be passed to the RestClient.create() call. In case of an HTTP error, the ResponseException provides access to the Response object. All other Throwables indicate a communication problem.

ErrorCallback errorCallback = new ErrorCallback() {

  public boolean error(Message message, Throwable throwable) {
    try {
      throw throwable;
    }
    catch (ResponseException e) {
      Response response = e.getResponse();
      // process unexpected response
      response.getStatusCode();
    }
    catch (Throwable t) {
      // process unexpected error (e.g. a network problem)
    }
    return false;
  }
};

Errai's JSON format will be used to serialize/deserialize your custom types. See Chapter 4, Marshalling for details. A future extension to Errai's marshaller capabilities will support pluggable/custom serializers. So in the near future you will have the flexibility to use your own wire format.

All paths specified using the @Path annotation on JAX-RS interfaces are by definition relative paths. Therefore, by default, it is assumed that the JAX-RS endpoints can be found at the specified paths relative to the GWT client application's context path.

To configure a relative or absolute root path, the following JavaScript variable can be set in either

the host HTML page

or by using a JSNI method:

or by simply invoking:

The root path will be prepended to all paths specified on the JAX-RS interfaces. It serves as the base URL for all requests sent from the client.