JBoss.orgCommunity Documentation

Chapter 5. Remote Procedure Calls (RPC)

5.1. Making calls
5.1.1. Proxy Injection
5.2. Handling exceptions
5.3. Session and request objects in RPC endpoints

ErraiBus supports a high-level RPC layer to make typical client-server RPC communication easy on top of the bus. While it is possible to use ErraiBus without ever using this API, you may find it to be a more useful and concise approach to exposing services to the clients.

Please note that this API has changed since version 1.0. RPC services provide a way of creating type-safe mechanisms to make client-to-server calls. Currently, this mechanism only support client-to-server calls, and not vice-versa.

Creating a service is straight forward. It requires the definition of a remote interface, and a service class which implements it. See the following:


public interface MyRemoteService {
  public boolean isEveryoneHappy();

The @Remote annotation tells Errai that we'd like to use this interface as a remote interface. The remote interface must be part of of the GWT client code. It cannot be part of the server-side code, since the interface will need to be referenced from both the client and server side code. That said, the implementation of a service is relatively simple to the point:


public class MyRemoteServiceImpl implements MyRemoteService {
  public boolean isEveryoneHappy() {
    // blatently lie and say everyone's happy.
    return true;

That's all there is to it. You use the same @Service annotation as described in Section 2.4. The presence of the remote interface tips Errai off as to what you want to do with the class.

Calling a remote service involves use of the MessageBuilder API. Since all messages are asynchronous, the actual code for calling the remote service involves the use of a callback, which we use to receive the response from the remote method. Let's see how it works:

In the above example, we declare a remote callback that receives a Boolean, to correspond to the return value of the method on the server. We also reference the remote interface we are calling, and directly call the method. However, don't be tempted to write code like this :

The above code will never return a valid result. In fact, it will always return null, false, or 0 depending on the type. This is due to the fact that the method is dispatched asynchronously, as in, it does not wait for a server response before returning control. The reason we chose to do this, as opposed to emulate the native GWT-approach, which requires the implementation of remote and async interfaces, was purely a function of a tradeoff for simplicity.

Handling remote exceptions can be done by providing an ErrorCallback on the client:

As remote exceptions need to be serialized to be sent to the client, the @ExposeEntity annotation needs to be present on the corresponding exception class (see Chapter 4, Marshalling ). Further the exception class needs to be part of the client-side code. For more details on ErrorCallbacks see Section 2.4, “Handling Errors” .

Before invoking an endpoint method, Errai sets up an RpcContext that provides access to message resources otherwise not visible to RPC endpoints.