Make sure you’ve obtained the archive interfaces.middleware.zip (it is in the Android\giraff.android folder from the svn checkout). This file contains the AIDL interface needed to communicate with the middleware. In order to setup your application you need to extract this file to the src/ directory of the project.

The middleware is implemented as an Android’s bound service that can be activated with the action “it.cnr.isti.giraff.android.BIND_TO_MIDDLEWARE”.

Files provided in the archive come with in-code documentation.

Follows a quick tutorial that explains step-by-step how to implement a service.

Note that all you need to know is the documentation of the interface, everything else follows the standard Android’s AIDL practices so you can refer the official documentation.

Make sure to add the following import:

import it.cnr.isti.giraff.android.interfaces.middleware.*;

In order to request the binding to the service you need to implement a ServiceConnection object that manages the connection to the middleware:

private IMiddleware middleware;
 
private ServiceConnection middlewareConnection = new ServiceConnection() {
 
    @Override
    public void onServiceConnected(ComponentName className, IBinder binder) {
        middleware = IMiddleware.Stub.asInterface(binder);
    }
 
    @Override
    public void onServiceDisconnected(ComponentName className) {
        middleware = null;
    }
};

Some methods requires a listener that need to be implemented on the service application:

private IMiddlewareCallback.Stub callback = new IMiddlewareCallback.Stub() {
 
    @Override
    public void serviceFound(Bundle descriptor) throws RemoteException {
        // ...
    }
 
    @Override
    public void serviceRemoved(Bundle descriptor) throws RemoteException {
        // ...
    }
 
    @Override
    public void serviceChanged(Bundle descriptor) throws RemoteException {
        // ...
    }
 
    @Override
    public void messageReceived(String topic, String payload) throws RemoteException {
        // ...
    }
};

Each method in the API takes an optional (can be null) errorListener parameter used to asynchronously report errors:

private IMiddlewareErrorCallback.Stub errorCallback = new IMiddlewareErrorCallback.Stub() {
 
    @Override
    public void error(Bundle info) throws RemoteException {
        // ...
    }
};

Your application must request a connection to the middleware by using an intent with a specific action string and passing the previously created ServiceConnection object:

Intent intent = new Intent("it.cnr.isti.giraff.android.BIND_TO_MIDDLEWARE");
bindService(intent, middlewareConnection, Context.BIND_AUTO_CREATE);

Make sure to unbind from the middleware when you’re done, for example in the onDestroy method of your main activity:

@Override
protected void onDestroy() {
    super.onDestroy();
    if (middlewareConnection != null) {
        unbindService(middlewareConnection);
    }
}

Once you have the IMiddleware object you can call remote methods on it, for example:

middleware.subscribe("topic", callback, errorCallback);