Remote Procedure Calls (RPC)

Remote Procedure Calls allow you to call functions on a remote system via a network and return the result back. In terms of the jWebSocket Network this means that a JavaScript web client can call Java methods on the server and receive the corresponding result.

The approach of the jWebSocket model goes even further because it not only allows the client to run server side functions but also vice versa. The server can call functions on the client and process the client's result and optionally distribute the results from one client to others.

It ipossible to exchange arbitrary complex objects when using JSON or XML, however, when using CSV the calls are limited to plains objects (i.e. objects that contain simple data fields only). The RPC module is implemented as a server and client side plug-in as described here.

Waiting for Results

Remote Procedure Calls (RPC's) can be performed in two ways, single-threaded and multi-threaded. Both methodologies are described below.

Single-Threaded RPCs

Single-Threaded means that whenever the server receives a RPC request from a client it simply invokes the requested method and sends the result back to the client as soon as the method finishes. Of course, this does not block the entire server but only the receive queue of the current connection. The next RPC will be executed once the previous one has finished. This mechanism could also be called sequential RPC. In this scenario it is ensured that the results are sent back to the client in the same order as they were requested.

Multi-Threaded RPCs

Multi-Threaded means that when the server receives a RPC request from a client it creates a new thread and calls the requested method within that thread. In this case the receive queue immediately is released when the thread has started. This means that you can run multiple RPCs concurrently on the server with the consequence that the results can be returned in a different order than they were requested depending on what is done in the method and how long it takes.

Result Processing

To allow the client to assign a certain result to a previous request the client assigns a token-id to each request. The server always returns this token-id together with the result so that the client can easily associate a result with the corresponding previous request. The jWebSocket client already does the work for you. For each RPC request you simply can provide a temporary local callback method which is called as soon as the result arrives. In this callback then you can process the result from the server according to your needs.

Request Token

The request token for a Remote Procedure Call (RPC) contains the following fields. The spawnThread field is optional, if it is not passed it is assumed to be false, which runs the RPC in the single threaded model.

Token Datatype Description
type String Always "rpc".
ns String Namespace "org.jWebSocket.plugins.rpc".
class String Name of the class of which a certain method is to be invoked.
method String Name of the method within the class to be invoked.
args Object Arguments to be passed the the remote procedure.
Boolean Specifies whether the call is supposed to run in a separate thread or within the connection's thread.

Response Token

For a Remote Procedure Call a response token is returned. The call could either be successful (i.e. the method could be called) or not (i.e. the method was not called at all). A successful call does not necessarily mean that the procedure could do what it was supposed to. In this case the Remote Procedure has to return a result which can be interpreted accordingly by the client.

Token Datatype Description
result Object This field is set if the Remote Procedure Call could successfully be executed. In this case the error field is not passed back.
error String This field is set if the Remote Procedure Call could not successfully be executed. In this case the result field is not passed back.

Learn more about WebSockets in general, get background information and gain deeper insight!

Join jWebSocket

Wether developer, designer or translator – join the jWebSocket team and grow together with our success!

Copyright © 2013 Innotrade GmbH. All rights reserved.