Welcome at » Using the networking library openbasemovil-net

Using the networking library openbasemovil-net

The Networking library in OpenBaseMovil (openbasemovil-net) provides some very useful networking methods that you can use in your applications.

One of the most useful ones is the RemoteCall class. As you can guess it is a remote call procedure, and it is a binary one. If your target platform supports the remote call or webservice optional APIs, you can use them, but we wanted to provide an approach that could be used on any device (many of the current devices in the market do not support those optional APIs). We also decided to use a binary protocol since it is more compact and more efficient for binary data, instead of XML.

We also wanted to control how the network was reached and do it in a very simple way.

The library contains three main blocks: Net, Binding and RemoteCall.

Net has all the needed constants, and also some networking wide configuration settings. It also has a checkNetwork method that will allow you to check if you have signal and if your remote server is up and running.

The synchronization engine uses the deviceGuid and deviceId settings to perform simple authentication. Those settings are sent from the server to the device when the user successfully authenticates in our system using the company name, user name and password.
You can use them for your own purposes, or you can ignore them, they are not really needed. If not set, they will be sent as an empty string and 0 respectively to the server in the remote call protocol.

The checkNetwork method provides also a small example of RemoteCall usage, as it calls a remote Object called “LoginHandler” to a method called “ping”. That checks if our server is up and running. If it can not make the call, it checks if it can read the home page of yahoo (you could put any other well known service). That is used to check if the previous error was due to the server being down or to the lack of network connectivity (we assume yahoo is up :) ).

final RemoteCall rc = new RemoteCall(
    "LoginHandler", // remote object name
    "ping",         // remote object method name
    0               // number of parameters

The RemoteCall class allows you to set a default url to call, so you can later just call the no argument version of invoke, but you can also provide an url for each call using the other version of invoke.
In the previous example, the Net class assumes that you have previously set the defaultURL property in the RemoteCall class. That should be done at application startup.

The RemoteCall class sends a binary stream to a remote url, using a the POST method through the Binding class. RemoteCall will try to invoke the remote method up to MAX_RETRIES (currently 5) times if there’s a network error (not if the server returns an error), providing you with a level of network security (mobile networks can be very error prone).

The protocol is very simple, and it uses the openbasemovil-core serialization tools to send and receive the data, so complex objects can be sent and received (anything that can be serialized through the SerializerOutputStream).
It is already present as a comment in the code, but I will put it here:

Device request:
{byte       version}        // RPC version, currently 2
{byte       encryption}     // Encryption: 0 - none, 1 - Blowfish
{String     deviceGuid}     // Device Globally Unique Identifier
{long       deviceId}       // Device remote id
{String     object}         // Name of object to call
{String     method}         // Object method to call
{byte[]     parameters}     // Parameters serialized using
                            // SerializerOutputStream
                            // writeNullableObject method
{String     "END_OF_DATA"}      // Constant text to identify
                                // data boundary
{long       CRC}                // Adler32 CRC code of the data
Server response:
{int        responseCode}       // Result of the method call
{String     responseMessage}    // Result message
{byte[]     responseData}       // An object serialized using
                                // SerializerOutputStream
                                // writeNullableObject method
responseCode can be one of:
Everything went fine
The requested object is invalid
The object has no method with the requested name
The caller is not allowed to execute the requested method
The arguments passed are invalid
The method produced an exception when invoked
The CRC of the data sent is invalid

So you can code a Servlet (or whatever) in your server, handle the post request, and parse the data sent using the openbasemovil-core SerializerInputStream class. Then is your turn to locate the object, the method, make sure you want the device make that call, make the call, and finally send the response back using the SerializerOutputStream class.
For the response, the responseCode and responseMessage are mandatory, and if the call is successful then the responseData is also mandatory.
responseData will be read by the device using SerializerInputStream.readNullableObject.

Your server side code should check that after the incomming data the END_OF_STREAM string si found and also the CRC code. And you should also perform the CRC checking using the openbasemovil-core Adler32 class, to make sure that everything arrived ok.

A bit more complex example of RemoteCall use, calling a remote object called “MyServer”, to a method called “sendImage” which receives three paremeters, a String, a byte array, and a Vector of String objects.

// Somewhere in your code at startup you will set the default URL
RemoteCall.setDefaultURL( "http://myserver/rpc" );
// Now we will make the call
 * Send an image to the server.
 * @param name image file name
 * @param data image raw data
 * @param attributes image attributes, a collection of Strings
public Long sendImage(
                 final String name,
                 final byte[] data,
                 final Vector attributes
    throws RemoteCallException
    final RemoteCall rc = new RemoteCall(
    rc.setParameter( 0, name );
    rc.setParameter( 1, data );
    rc.setParameter( 2, attributes );
    return (Long) rc.invoke();

The RemoteCall method uses the Binding class to actually call the remote server with a POST method.

The Binding class provides an easy and extensible way to abstract you from the real method used to make the call. It also controls all the open bindings, allowing you to close them all at once to make sure that there’re no connections open.

Binding is an abstract class that by default uses the provided sublcass HttpBinding. As you can imagine, the HttpBinding class uses the javax.microedition.connection to actually create an http or https connection.

With the Binding framework you could create other Binding subclasses and use other means for connecting to the network. For example, in future versions we will provide a BluetotthBinding and a Java SE Proxy. With them you will be able to connect your phone through bluetooth using the proxy running on a PC. And everything will work exactly the same.

To create a new Binding class and use it you simply need to subclass Binding, implement the needed methods, and then set it as the binding factory with:

// For CLDC 1.0
Binding.setFactory( new BluetoothBinding().getClass() );


// For CLDC 1.1
Binding.setFactory( BluetoothBinding.class );

This introduction to the networking part of OpenBaseMovil will be included in the next revisions of the documentation.
We look forward for your comments to enhance and clarify it before it is actually included.

BlogLines Digg Facebook Google Google Reader Yahoo! MyWeb Newsgator Newsvine reddit SlashDot StumbleUpon Technorati

Leave a Reply

You must be logged in to post a comment.