Exploring the Errai Framework

Posted: April 11th, 2013 | Author: | Filed under: Technology | Tags: , , , | No Comments »

JAX-RS

Now that we have completed a basic overview, let’s begin reviewing the sample application in depth. We need to make a communication from the client side to the server side. Errai provides us with options ranging from basic RPC to JAX-RS (Restful services).  In the application, we exposed a JAX-RS interface called MathService to perform the various math operations. This interface is shared between server side and client side components and is located in the com.redhat.errai.math.local.shared package. Similar to GWT, the files contained within in this packaged and the aforementioned com.redhat.errai.math.client.local package are compiled into JavaScript for use by the browser. The model objects for the application are also placed into the shared folder.  By opening the MathService interface, you will notice that at most two parameters are received from the client, the appropriate operation is performed and a Result is returned. Also present in each method signature is a where the User-Agent header parameter is retrieved which will be used to display operating system and browser information. If you inspect the other model classes available within the shared package, you will notice each one has a @Portable annotation at the top of the class. This allows Errai to be able to serialize the objects between client and server. The Result class does not have this annotation, but instead a typical JAXB @XmlRootElement. This was done intentionally to demonstrate how to configure Errai to map classes which do not have the @Portable annotation, such in the case of preexisting rest services. As long as the class is already contained within a GWT module, we can add a configuration to the ErraiApp.properties file. This ErraiApp.properties file is required for all Errai applications and must be present at the root of the classpath. In a Maven project, it will be located in the src/main/resources folder. This file may be left empty, but may be configured for instances such as this. To allow Errai to marshall the Result class, we have configured the ErraiApp.properties file with the following to allow the marshalling framework to produce the appropriate marshaller:

errai.marshalling.serializableTypes=com.redhat.errai.math.client.shared.Result

To access these rest service from the client, we have configured the application to utilize the JAX-RS module by adding the following to the ErraiMath.gwt.xml file:

<inherits name="org.jboss.errai.enterprise.Jaxrs"/>

In addition, since we are using Jackson marshalling, we needed enable Jackson marshalling support. This is done by adding the following to the root GWT host page ErraiMath.html located in the src/main/webapp folder

<script type="text/javascript">

  erraiJaxRsJacksonMarshallingActive = true;

</script>

With these configurations in place, we can focus on how to invoke rest services. There are two ways of invoking rest services:  by calling RestClient.create()  directly for each request or by using an injectable proxy via the @Inject CDI annotation (The inject annotation will be covered in further detail in the CDI section). Proxy injection is favorable as it simplifies configuration. For proxy injection support, the following was added to the ErraiMath.gwt.xml file:

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

Since client side GWT code runs as JavaScript, a callback must be provided when a Rest call is made. This callback must be an instance of RemoteCallback and is required whether using RestClient directly or caller injection using proxies. Optionally, an ErrorCallback may also be provided as a mechanism to handle execution failure. The following example depicts how a request is be made on our MathService:

@Inject
Caller<MathService> mathService;

// Later on in the code
mathService.call(resultCallback, errorCallback).add("1", "5", "FF");

The above code shows our injection of the MathService and the subsequent invocation of the add method of the service. Notice we are passing in values of both our RemoteCallback (resultCallback) and our ErrorCallback (errorCallback).

Also keep in mind that we are publishing a regular JAX-RS endpoint within our application. We needed to add the following to our web.xml deployment descriptor file to designate the location of our endpoint.

<servlet-mapping>
	<servlet-name>javax.ws.rs.core.Application</servlet-name>
	<url-pattern>/</url-pattern>
</servlet-mapping>

We can also invoke our rest service directly instead of using the Errai Application. If we wanted to add two numbers together, navigate to /math/add?LHS=5&RHS=5. Our service will produce either an XML or JSON representation of the Result object depending on the request.

1 2 3 4 5

Leave a Reply