path: root/doc/ivy-java.sgml

<!--
	The Ivy java guide

	Copyright (c) 1999-2000
	Centre d'Etudes de la Navigation Aerienne

	SGML source file

	Authors: Yannick Jestin <jestin@cena.fr>

-->

<?XML VERSION='1.0' ?>
<!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

<article>

<artheader>

<copyright>
<year>2000</year>
<holder>CENA, Centre d'Etudes de la Navigation Aérienne</holder>
</copyright>

<title>The Ivy C++ and java library guide</title>
<subtitle>CENA NT02-819</subtitle>
<titleabbrev>NT02-819 © CENA</titleabbrev>

<authorgroup>
<author>
<firstname>Yannick</firstname><surname>Jestin</surname>
<affiliation><address><email>jestin@cena.fr</email></address></affiliation>
</author>
</authorgroup>
<date>August 4, 2000</date>

<copyright>
<year>2000</year>
<holder>Centre d'Études de la Navigation Aérienne</holder>
</copyright>

<abstract>
<para>
This document is a programmer's guide that describes how to use the Ivy
Java library to connect applications to an Ivy bus. This guide describes
version 1.2 of the library. This document itself is part of the java
package, available on the <ulink
url="http://www.tls.cena.fr/products/ivy/">Ivy web site</ulink>.
</para>
</abstract>
</artheader>

<sect1><title>Foreword</title>

<para>
This document was written in SGML according to the DocBook DtD, so
as to be able to generate PDF and html output. However, the authors
have not yet mastered the intricacies of SGML, the DocBook DtD, the
DocBook Stylesheets and the related tools, which have achieved the
glorious feat of being far more complex than LaTeX and Microsoft Word
combined together. This explains why this document, in addition to being
incomplete, is so ugly. We'll try and improve it. 
</para>

<para>
The Windows ivy-c++ port has been written with the same API. Most of the
documentation for the Ivy java library applies to the windows c++ library.
There is a section dedicated to the description of the intrinsics. There is
also a unix port of this library, which is a C++ wrapper on top of the C
library. There is also a section dedicated to this port.
</para>
</sect1>


<sect1><title>What is Ivy?</title>

<para>
Ivy is a software bus designed at <ulink url="http://www.cena.fr/">CENA</ulink> (France). A software bus is a system 
that allows software applications to exchange information with the illusion of
broadcasting that information, selection being performed by the receiving
applications. Using a software bus is very similar to dealing with events in a
graphical toolkit: on one side, messages are emitted without caring about who
will handle them, and on the other side, one decide to handle the messages that
have a certain type or follow a certain pattern. Software buses are mainly aimed 
at facilitating the rapid development of new agents, and at managing a dynamic
collection of agents on the bus: agents show up, emit messages and receive some, 
then leave the bus without blocking the others.
</para>

<para>
Ivy is implemented as a collection of libaries for several languages and
platforms. If you want to read more about the principles Ivy before reading
this guide of the java 
library, please refer to <citetitle>The Ivy sofware bus: a white
paper</citetitle>. If you want more details about the internals of Ivy, have a
look at <citetitle>The Ivy architecture and protocol</citetitle>. And finally,
if you are more interested in other languages, refer to other guides such as
<citetitle>The Ivy Perl library guide</citetitle>, or <citetitle>The Ivy C library guide</citetitle>. All those documents should be 
available from <ulink url="http://www.tls.cena.fr/products/ivy/">the Ivy Web site </ulink>.
</para>
</sect1>

<sect1><title>The Ivy java library</title>

<sect2><title>What is it?</title>
<para>
The Ivy java library (aka ivy-java or fr.dgac.ivy) is a java package that
allows you to connect applications to an Ivy bus. You can use it to write
applications in java. You can also use it to integrate any thread-safe java
application. So far, this library has been tested and used on a variety of
java virtual machines (from 1.1.8 to 1.4.0), and on a variety of architectures
(GNU/Linux, Solaris, Windows NT,XP,2000, MacOSX).
</para>

<para>
The Ivy C library was originally developed by François-Régis Colin and then
by Yannick Jestin at CENA. It is maintained by a group at CENA (Toulouse, France)
</para>
</sect2>

<sect2><title>Getting and installing the Ivy Java library</title>

<para>
You can get the latest versions of the Ivy C library from <ulink
URL="http://www.tls.cena.fr/products/ivy/">the Ivy web site</ulink>. It is
packaged either as a jar file or as a debian package. We plan to package it
according to different distribution formats, such as .msi (Windows) or .rpm
(Redhat and Mandrake linux). 
</para>

<para>
The package is mainly distributed as a JAR file. In order to use it, either add
it in your CLASSPATH, or put the jar in your $JAVA_HOME/jre/lib/ext/
directory, if you use a java 2 virtual machine. If running windows, be sure to
add it to the right place for runtime (C:\Program Files\JavaSoft\...). The package contains the documentation, the sources and the class files for the fr.dgac.ivy package.
</para>

<para>
In order to test the presence of Ivy on your system once installed, run the following command: 
<screen>
$ <userinput>java fr.dgac.ivy.Probe</userinput>
</screen>
If it spawns a line about broadcasting on a strange address, this is OK, it is
ready and working. If it complains about a missing class (
java.lang.NoClassDefFoundError ), then you have not pointed your virtual
machine to the jar file.
</para>

</sect2>

</sect1>

<sect1><title>Your first Ivy application</title>

<para>
We are going to write a "Hello world translater" for an Ivy bus. The application will subscribe to all messages starting with "Hello", and re-emit them after
translating "Hello" into "Bonjour". In addition, the application will quit when
it receives any message containing exactly "Bye".
</para>

<sect2><title>The code</title>
<para>
Here is the code of "ivyTranslater.java":

<programlisting>
import fr.dgac.ivy.* ;

class ivyTranslater implements IvyMessageListener {

  private Ivy bus;

  ivyTranslater() {
    // initialization
    bus = new Ivy("IvyTranslater","Hello le monde",null);
    bus.bindMsg("^Hello(.*)",this);
    bus.bindMsg("^Bye$",new IvyMessageListener() {
      // callback for "Bye" message
      public void receive(IvyClient client, String[] args) {System.exit(0);}
    });
    try {
       // starts the bus on the default domain or IVY_DOMAIN property
       bus.start(null);
    } catch (IvyException ie) {
      System.err.println("can't run the Ivy bus" + ie.getMessage());
    }
  }

  // callback associated to the "Hello" messages"
  public void receive(IvyClient client, String[] args) {
    bus.sendMsg("Bonjour"+((args.length&gt;0)?args[0]:""));
  }

  public static void main(String args[]) { new ivyTranslater(); }
}
</programlisting>
</para>

</sect2>

<sect2><title>Compiling it</title>
<para>
You should be able to compile the application with the
following command (if the ivy-java jar is in your development classpath):
<screen>
$ <userinput>javac ivyTranslater.java</userinput>
$
</screen>
</para>
</sect2>


<sect2><title>Testing</title>
<para>
We are going to test our application with <command>fr.dgac.ivy.Probe</command>. In a terminal window, launch <command>ivyTranslater</command>.
<screen>
$ <userinput>java ivyTranslater</userinput>

</screen>

Then in another terminal window, launch <command>java fr.dgac.ivy.Probe '(.*)'</command>. You are then ready to start. Type "Hello Paul", and you should get "Bonjour Paul". Type "Bye", and your application should quit:
<screen>
$ <userinput>java fr.dgac.ivy.Probe '(.*)'</userinput>
you want to subscribe to (.*)
broadcasting on 127.255.255.255:2010
IvyTranslater connected
IvyTranslater subscribes to ^Bye$
IvyTranslater subscribes to ^Hello(.*)
IvyTranslater sent 'Hello le monde'
<userinput>Hello Paul</userinput>
-&gt; Sent to 1 peers
IvyTranslater sent 'Bonjour Paul'
<userinput>Bye</userinput>
-&gt; Sent to 1 peers
IvyTranslater disconnected
<userinput>&lt;Ctrl-D&gt;</userinput>
$
</screen>

</para>
</sect2>
</sect1>

<sect1><title>Basic functions</title>

<sect2><title>Initialization and Ivy threads</title>

<para>
Initializing a java Ivy agent is a two step process. First of all, you must
create an <function>fr.dgac.ivy.Ivy</function> 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 <function>start()</function> method on
your Ivy object. This will run two threads that will remain active until you
call the <function>stop()</function> method on your Ivy object. Once the
<function>start()</function> method has been called, your agent is ready to handle messages on the bus !
</para>

<para>
Here are more details on those functions:

<programlisting>
  fr.dgac.ivy.Ivy(String name,String message, IvyApplicationListener appcb)
</programlisting>
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 <parameter>name</parameter> is
the name of the application on the bus, and will by transmitted to other
application, and possibly be used by them. The <parameter>message</parameter>
is the first message that will be sent to other applications, with a slightly
different broadcasting scheme than the normal one ( see <citetitle>The Ivy
architecture and procotol</citetitle> document for more information). If
<parameter>message</parameter> is null, nothing will be sent.
<parameter>appcb</parameter>, 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.

<programlisting>
public void start(String domainbus) throws IvyException
</programlisting>
This method connects the Ivy bus to a domain or list of domains.
<parameter>domainbus</parameter> 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
<parameter>null</parameter>, the API will check for the property
<parameter>IVY_DOMAIN</parameter>, 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.

<programlisting>
public void stop() 
</programlisting>
This methods stops the threads, closes the sockets and performs some clean-up.
You can reconnect to the bus by calling <function>start()</function> once again.

</para>
</sect2>

<sect2><title>Emitting messages</title>

<para>
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.

<programlisting>
public int sendMsg(String message) 
</programlisting>
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.

</para>
</sect2>

<sect2><title>Subscribing to messages</title>

<para>
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 <function>bindMsg()</function> method to bind a callback to a pattern, and the <function>unbindMsg</function> method to delete the binding.  

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

</para>
</sect2>
</sect1>


<sect1><title>Advanced functions</title>

<sect2><title>fr.dgac.ivy.Probe utility</title>

<para>
fr.dgac.ivy.Probe is your swiss army knife as an Ivy java developper. Use it
to try your regular expressions, to check the installation of the system, to
log the messages, etc. 
</para>

<para>
The command line options ( available with the --help switch ) are the
following:
<itemizedlist>
<listitem><para>
-b allows you to specify the ivy bus. This overrides the -DIVY_BUS
java property. The default value is 127.255.255.255:2010.
</para></listitem>
<listitem><para>
-n NAME allows you to specify the name of this probe agent on the bus. It
defaults to JPROBE, but it might be difficult to differenciate which jprobe
sent which message with a handful of agents with the same name
</para></listitem>
<listitem><para>
-q allows you to spawn a silent jprobe, with no terminal output.
</para></listitem>
<listitem><para>
-d allows you to use JPROBE on debug mode. It is the same as setting the
VY_DEBUG property ( java -DIVY_DEBUG fr.dgac.ivy.Probe is the same as java
fr.dgac.ivy.Probe -d )
</para></listitem>
<listitem><para>
-h dumps the command line options help.
</para></listitem>
</itemizedlist>
</para>

<para>
The run time commands are preceded by a single dot (.) at the beginning of the
line. Issue ".help" at the prompt ( without the double quotes ) to have the
list of availables comands. If the lines does not begin with a dot, jprobe tries
to send the message to the other agents, if their subscriptions allows it. The
dot commands are the following
<itemizedlist>
<listitem><para>
.die CLIENTNAME issues an ivy die command, presumably forcing the first agent
with this name to leave the bus
</para></listitem>
<listitem><para>
.bye (or .quit) forces the JPROBE application to exit. This is the same as issing an end of file character on a single input line ( ^D ).
</para></listitem>
<listitem><para>
.list gives the list of clients seen on the ivy bus
</para></listitem>
<listitem><para>
.ping issues a ping request. This is only available for ivy java clients so
far, and allows you to try and send a packet to a remote agent, in order to
check the connectivity.
</para></listitem>
</itemizedlist>
</para>
</sect2>

<sect2><title>Direct messages</title>
<para>
Direct messages is an ivy feature allowing the exchange of information between
two ivy clients. It overrides the subscription mechanism, making the exchange
faster ( there is no regexp matching, etc ). However, this features breaks the
software bus metaphor, and should be replaced with the relevant bounded
regexps, at the cost of a small CPU overhead. So far, the sending of direct
message is not available from java, but the receiving is available in the
fr.dgac.Ivy class.
</para>
</sect2>

</sect1>

<sect1><title>Ivy c++ Windows port</title>
<para>
The API is very similiar to the java port, that's why we include this little
section within the ivy java documentation. The author is not familiar with
windows programming or C++ programming so that this documentation might be
inaccurate. Here is a sample listing that might be useful:
</para>

<programlisting>
// ivytest.cpp : Defines the entry point for the console application.
#include &lt;iostream.h&gt;

#include &lt;stdlib.h>

#include "ivy.h"
#include "IvyApplication.h"

static bool TheGrassIsGreenAndTheWindBlows = true;

class cIvyTranslater : public IvyApplicationCallback 
{   
public:
    cIvyTranslater(void);
protected:
	void OnApplicationConnected   ( IvyApplication *app );
	void OnApplicationDisconnected( IvyApplication *app );
	void HelloCallback  ( IvyApplication *app, int argc, const char **argv );
	void ByeCallback    ( IvyApplication *app, int argc, const char **argv );
	Ivy *bus;
};



cIvyTranslater::cIvyTranslater(void) 
{
    // initialization
	bus = new Ivy( "cIvyTranslater","cIvyTranslater READY",this,FALSE);

    int count;
    count = bus-&gt;BindMsg( "^Hello(.*)", BUS_CALLBACK_OF(cIvyTranslater, HelloCallback ));
    count = bus-&gt;BindMsg( "^Bye$",      BUS_CALLBACK_OF(cIvyTranslater, ByeCallback ));
    
    bus-&gt;start("127.255.255.255:2010");
}

void cIvyTranslater::HelloCallback(IvyApplication *app, int argc, const char **argv)
{
    const char* arg = (argc &lt; 1) ? "" : argv[0];
	cout &lt;&lt; "cIvyTranslater received msg: Hello'" &lt;&lt; arg
	&lt;&lt; "'" &lt;&lt; endl;
    bus-&gt;SendMsg( "Bonjour%s!", arg );
}

void cIvyTranslater::ByeCallback(IvyApplication *app, int argc, const char **argv)
{
	cout &lt;&lt; "cIvyTranslater stops bus" &lt;&lt; endl;
    if (bus) {
        TheGrassIsGreenAndTheWindBlows = false;
        bus-&gt;stop(); 
        delete bus; // This statement is never reached! Don't know why!
    }
	
}

void cIvyTranslater::OnApplicationConnected(IvyApplication *app)
{
	cout &lt;&lt; "cIvyTranslater is ready to accept messages from "
	&lt;&lt; app-&gt;GetName() &lt;&lt; endl;
}

void cIvyTranslater::OnApplicationDisconnected(IvyApplication *app)
{
	cout &lt;&lt; "cIvyTranslater good buy '" &lt;&lt; app-&gt;GetName()
	&lt;&lt; "'" &lt;&lt; endl;
}


void main(int argc, char* argv[]) 
{
    cIvyTranslater aIvyTL;

    while (TheGrassIsGreenAndTheWindBlows) {
        Sleep(2000);
        cout &lt;&lt; "new cycle..." &lt;&lt; endl;
    }
	cout &lt;&lt; "Good buy, world\n";
}
</programlisting>

<sect2><title>Win32 API</title>
<para>
</para>
</sect2>

<sect1>
<title>programmer's style guide</title>
<para>
[to be written]
</para>
</sect1>

<sect1>
<title>Contacting the authors</title>
<para>
The Ivy java library is now maintained by Yannick Jestin. For bug reports or
comments on the library itself or about this document, please send him an
email at <email>jestin@cena.fr</email>. For comments and ideas about Ivy itself
(protocol, applications, etc), please join and use the Ivy mailing list:
<email>ivy@tls.cena.fr</email>. 
</para>
</sect1>

</article>