JBoss.orgCommunity Documentation
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:
Example 7.1. CustomerService.java
@Path("customers")
public interface CustomerService {
@GET
@Produces("application/json")
public List<Customer> listAllCustomers();
@POST
@Consumes("application/json")
@Produces("text/plain")
public long createCustomer(Customer customer);
}
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:
Example 7.2. App.java
...
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 Section 7.2, “Handling Responses” .
Injectable proxies can be used as an alternative to calling
RestClient.create()
.
@Inject
private Caller<CustomerService> customerService;
To create a request, the callback objects need to be provided to the
call
method before the corresponding interface method is invoked.
customerService.call(callback).listAllCustomers();
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
<script type="text/javascript">
erraiJaxRsApplicationRoot = "/MyJaxRsEndpointPath";
</script>
or by using a JSNI method:
private native void setMyJaxRsAppRoot(String path) /*-{
$wnd.erraiJaxRsApplicationRoot = path;
}-*/;
or by simply invoking:
RestClient.setApplicationRoot("/MyJaxRsEndpointPath");
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.