5. Basic functions

5.1. Initialization and Ivy threads

Initializing a java Ivy agent is a two step process. First of all, you must create an fr.dgac.ivy.Ivy object. Once this object is created, you can add subscriptions to Ivy events, be it messaged, arrival or departure of other agents, etc, but your agent is still not connected. In order to connect, you should call the start() method on your Ivy object. This will run two threads that will remain active until you call the stop() method on your Ivy object. Once the start() method has been called, your agent is ready to handle messages on the bus !

Here are more details on those functions:

  fr.dgac.ivy.Ivy(String name,String message, IvyApplicationListener appcb)
This constructor readies the structures for the software bus connexion. It is possible to have different busses at the same time in an application, be it on the same bus or on different ivy busses. The name is the name of the application on the bus, and will by transmitted to other application, and possibly be used by them. The message is the first message that will be sent to other applications, with a slightly different broadcasting scheme than the normal one ( see The Ivy architecture and procotol document for more information). If message is null, nothing will be sent. appcb, if non null, is an object implementing the IvyApplicationListener interface. Its different methods will be called upon arrival or departure of an agent on the bus, when your application itself will leave the bus, or when a direct message will be sent to your application.
public void start(String domainbus) throws IvyException
This method connects the Ivy bus to a domain or list of domains. domainbus is a string of the form 10.0.0:1234, it is similar to the netmask without the trailing .255. This will determine the meeting point of the different applications. Right now, this is done with an UDP broadcast. Beware of routing problems ! You can also use a comma separated list of domains, for instance "10.0.0.1234,192.168:3456". If the domain is null, the API will check for the property IVY_DOMAIN, if not present, it will use the default bus, which is 127.255.255.255:2010, and requires a loopback interface to be active on your system. This method will spawn two threads, one listening to broadcasts from other agents, and one listening on the service UDP socket, where remote agent will come and connect. If an IvyException is thrown, your application is not able to talk to the domain bus.
public void stop() 
This methods stops the threads, closes the sockets and performs some clean-up. You can reconnect to the bus by calling start() once again.

5.2. Emitting messages

Emitting a message is much like writing a string on a output stream. The message will be sent if you are connected to the bus and somebody is interested in its content.

public int sendMsg(String message) 
Will send each remote agent the substring in case there is a regexp matching. The int result is the number of messages actually sent. The main issue here is that the sender ivy agent is the one who takes care of the regexp matching, so that only useful information are conveyed on the network.

5.3. Subscribing to messages

Subscribing to messages consists in binding a callback function to a message pattern. Patterns are described by regular expressions with captures. When a message matching the regular expression is detected on the bus, the callback function is called. The captures (ie the bits of the message that match the parts of regular expression delimited by brackets) are passed to the callback function much like options are passed to main. Use the bindMsg() method to bind a callback to a pattern, and the unbindMsg method to delete the binding.

public int bindMsg(String regex, IvyMessageListener callback);
public void unBindMsg(int id);
The regex follows the gnu.regexp regular expression syntax. Grouping is done with parenthesis. The callback is an object implementing the IvyMessageListener interface, with the receive method. The thread listening on the connexion with the sending agent will execute the callback.