Javascript API

Introduction

This page presents the different methods provided to control the Ivy bus. You must be a bit familar with how Ivy works (if not, visit Ivy page).

The javascript object to be used to control Ivy is window.ivyRequest or ivyRequest.

Let's now show the different methods :

Initialising the bus

The initialisation is done by

IvyRequest.init(String applicationName, String greetMessage)

The arguments are optionnal. If no arguments are provided, the bus is initialised with default arguments ("OWB", "Hello") If one of them is omited, it is ignored and the previous statement apply. If both parameters are provided, they are used to initialise the bus.

Starting the bus

Warning:

As it is the case in Ivy, starting the bus is different from running it. So after this stage, the application is not listening on the bus.

See also:

Running the bus

The Ivy bus is started with

IvyRequest.start(String IvyBus);

Once again, the paramater is optionnal but be aware that the default behaviour is to start on the loopback interface.

The IvyBus parameter is the bus adresse and possibly the port. For example : IvyRequest.start("192.168.1.255:2010");

Warning:

If the initialisation was not done, the method will automatically run it without arguments (default behaviour)

Running the bus

The bus is launched with :

IvyRequest.run();

After starting the bus, the application is listening to the bus. All listeners that were added before the call are now binded.

Warning:

The default way to prepare the bus is: ivyRequest.init(...) -> ivyRequest.start(...) -> ivyRequest.run() If one of the previous step was not done, ivyRequest.run() will automatically run it without arguments

Stopping the bus

The bus can be stopped at anytime with :

IvyRequest.stop();

Warning:

In order to keep the bus in a good state, this operation needs to unregister all the listeners

listeners to the bus

There are several types of listeners in Ivy. Currently only message, connection and disconnection listeners supported.

Message listeners

An Ivy listener is a String that represents the regular expression to match and a javascript function to callback. In order to register a listener, you need to provide both to the method :

IvyRequest.bindIvyMsg(callbackFunction, String regularExpression);
or 
IvyRequest.addIvyMsgListener(callbackFunction, String regularExpression);

By default the callback method can take 3 String as arguments : the name of the application that send the message, the host that send the message and the message itself.

Example of a simple callback method :

function mySimpleCallbackFunction(appName, hostName, message) {
    alert("Message " + message + " from "+ appName + "@" + hostName);
}

The registration for anything would be done with :

ivyRequest.bindIvyMsg(mySimpleCallbackFunction, "(.*)");

Another example would be to select only the messages that starts with "alert" :

ivyRequest.bindIvyMsg(mySimpleCallbackFunction, "$alert(.*)");

Note that your function will receive only what follows alert and not "alert" in this case.

Connection Listeners

Due to our implementation and Ivy's own limitation, you can only register on connection listener. That listener is called whenever an application connects on the bus.

Only one listener of this type is allowed and its binding is done with :

ivyRequest.setConnectListener(callbackFunction);

Warning:

The argument is optionnal but if omited, it will result in removing the connection listener

The callback function can take up to 2 String that represents the application's name that has just connected and the associated host.

Example : very simple callback

function mySimpleConnectCallbackFunction(appName, hostName) {
    alert("Connection from " + appName + "@" + hostName);
}

Disconnection Listeners

That listener is called whenever an application disconnects from the bus.

Only one listener of this type is allowed and its binding is done with :

ivyRequest.setDisconnectListener(callbackFunction);

Warning:

The argument is optionnal but if omited, it will result in removing the listener

The callback function can take up to 2 String that represents the application's name that has just disconnected and the associated host (same as for connection listener).

See previous section for an example.

listeners to the bus

Message listener

The unbinding takes the same arguments as the binding and can be achieved with :

ivyRequest.unbindIvyMsg(callbackFunction, String regularExpression);
or
ivyRequest.removeIvyMsgListener(callbackFunction, String regularExpression);

The two arguments must be the same as those used when binding the listener.

In our example, it would be

ivyRequest.unbingIvyMsg(mySimpleCallbackFunction, "(.*)");

Remove all message listener

It can be done with the method :

ivyRequest.removeAllIvyMsgListeners();

Remove Connection / Disconnection Listener

As stated in Connection Listeners, calling the setConnectListener without argument will remove the connection listener.

The same apply to setDisconnectionListener.

Remove all listeners

ivyRequest.removeAllIvyListener();

Status

The notion of status was included in the implementation to match XmlHttpRequest behaviour (as it is very close to Ivy's).

The status can be asked with

ivyRequest.getStatus();

The method returns a String that is one of those values :

• uninitialised : basic status (no method was called)
• initialised : ivyRequest.init was called
• ready : ivyRequest.start was called
• run : ivyRequest.run was called, the application is listening on the bus throught its listeners

---