The Ivy java library guide
Prev Next

Basic functions

Initialization and Ivy loop

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 the Ivy constructor:
fr.dgac.ivy.Ivy(java.lang.String name, java.lang.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 applicatino, 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.

    Here are more details on the start() method:
    public void start(java.lang.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.

    Here are more details on the stop() method:
    public void stop()
     
    This methods stops the threads, closes the sockets and does some clean up. You can reconnect to the bus by calling start() once again.

    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.
    public int sendMsg(String s)
     
    Will send each remote agent the substring in case there is a regexp matching. The int result is the number of messages actually sent.

    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.

    Prev Home Next
    Your first ivy java application   Advanced Functions