This section assumes you have already set up the CustomerService JAX-RS endpoint as described in the previous section.

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:

...

Button create = new Button("Create", new ClickHandler() {

  public void onClick(ClickEvent clickEvent) {

    Customer customer = new Customer(firstName, lastName, postalCode);

    RestClient.create(CustomerService.class, callback).createCustomer(customer);

  }

});

...

For details on the callback mechanism see Handling Responses .

@Inject

private Caller<CustomerService> customerService; 

customerService.call(callback).listAllCustomers();

  <inherits name="org.jboss.errai.ioc.Container"/>

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 5, 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 can be used as an alternative. It 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 and the status code. The ResponseCallback can also be used for JAX-RS interface methods that return a javax.ws.rs.core.Response type. In this case, the MarshallingWrapper class can be used to manually demarshall the response body to an entity of the desired type.

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 RestErrorCallback() {

  public boolean error(Request request, 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;

  }

};

Client-side remote call interceptors provide the ability to manipulate or bypass the request before it's being sent. This is useful for implementing crosscutting concerns like caching or security features e.g:

To have a JAX-RS remote call intercepted, either an interface method or the remote interface type has to be annotated with @InterceptedCall . If the type is annotated, all interface methods will be intercepted.

@Path("customers")

public interface CustomerService {


  @GET

  @Path("/{id}")

  @Produces("application/json")

  @InterceptedCall(MyCacheInterceptor.class)

  public Customer retrieveCustomerById(@PathParam("id") long id);

}

Note that an ordered list of interceptors can be used for specifying an interceptor chain e.g.

@InterceptedCall({MyCacheInterceptor.class, MySecurityInterceptor.class})

public Customer retrieveCustomerById(@PathParam("id") long id);

Implementing an interceptor is easy:

public class MyCacheInterceptor implements RestClientInterceptor {


  @Override

  public void aroundInvoke(final RestCallContext context) {

    RequestBuilder builder = context.getRequestBuilder();

    builder.setHeader("headerName", "value");

    context.proceed();

  }

}

The RestCallContext passed to the aroundInvoke method provides access to the context of the intercepted JAX-RS (REST) remote call. It allows to read and write the parameter values provided at the call site and provides read/write access to the RequestBuilder instance which has the URL, HTTP headers and parameters set.

Calling proceed executes the next interceptor in the chain or the actual remote call if all interceptors have already been executed. If access to the result of the (asynchronous) remote call is needed in the interceptor, one of the overloaded versions of proceed accepting a RemoteCallback has to be used instead.

The result of the remote call can be manipulated by calling RestCallContext.setResult() .

Not calling proceed in the interceptor bypasses the actual remote call, passing RestCallContext.getResult() to the RemoteCallBack provided at the call site.

Errai's JSON format will be used to serialize/deserialize your custom types. See Chapter 5, Marshalling for details.

Alternatively, a Jackson compatible JSON format can be used on the wire. See Configuration for details on how to enable Jackson marshalling.