path: root/doc/ivy-java.sgml

<!--
	The Ivy java guide

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

	SGML source file

	Author: Yannick Jestin <jestin@cena.fr>

-->

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

<article>

<artheader>

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

<title>The Ivy 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 27, 2004</date>

<copyright>
<year>2004</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.6 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 quite ugly. We'll try and improve it. 
</para>

</sect1>


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

<para>
Ivy is a software bus designed at <ulink
url="http://www.cena.fr/">CENA</ulink>.  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> (not yet written), 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 libivy-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 on an Ivy bus. So far, this library has been tested and used on a variety of
java virtual machines (from 1.1.7 to 1.4.2), and on a variety of architectures
(GNU/Linux, Solaris, Windows NT,XP,2000, MacOSX).
</para>

<para>
The Ivy java library was originally developed by François-Régis Colin and is
now maintained by Yannick Jestin at CENA within 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). Contributors are welcome for package management.
</para>

<para>
The package is mainly distributed as a jar file. In order to use it, either add
it in your CLASSPATH environment variable, put the it in your $JAVA_HOME/jre/lib/ext/
directory, or C:\Program Files\JavaSoft\... for Windows. The best way to avoid
mistakes is to put it in the command line each time you want to use ivy
<command>$ java -classpath .:/path/to/ivy.jar:/path/to/regexp.jar:/path/to/getopt.jar className</command>
</para>

<para>
The package contains the documentation, the sources and the class files for the fr.dgac.ivy package,
alongside with examples and a couple of useful tools, IvyDaemon and Probe. You
will need the <ulink url="http://jakarta.apache.org/regexp/">Apache Jakarta
project regexp library</ulink>
and the <ulink url="http://www.urbanophile.com/arenn/coding/download.html">gnu getopt library</ulink>.
Those could be included in the jar file, but not in the debian 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 should display a line about broadcasting on a strange address, this is OK
and means 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 or your installation is incomplete.
</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 the "Hello" string, and re-emit them
on the bus having translated "Hello" into "Bonjour" (Hello in french).
In addition, the application will quit as soon as it receives a "Bye" message.
</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() throws IvyException {
    // initialization, name and ready message
    bus = new Ivy("IvyTranslater","IvyTranslater Ready",null);
    // classical subscription
    bus.bindMsg("^Hello(.*)",this);
    // inner class subscription ( think awt )
    bus.bindMsg("^Bye$",new IvyMessageListener() {
      public void receive(IvyClient client, String[] args) {
	// leaves the bus, and as it is the only thread, quits
        bus.stop();
      }
    });
    bus.start(null); // starts the bus on the default domain
  }

  // callback associated to the "Hello" messages"
  public void receive(IvyClient client, String[] args) {
    try {
      bus.sendMsg("Bonjour"+((args.length&gt;0)?args[0]:""));
    } catch (IvyException ie) {
      System.out.println("can't send my message on the bus");
    }
  }

  public static void main(String args[]) throws IvyException {
    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 shell, launch ivyTranslater:
<screen>
$ <userinput>java ivyTranslater</userinput>
</screen>

In another shell, launch <command>java fr.dgac.ivy.Probe '(.*)'</command>.
You can see that the IvyTranslater has joined the bus, published its
subscriptions, and sent the mandatory ready message. As your probe has
subscribed to the eager regexp .* and reports the matched string within the
brackets (.*), the ready message is printed.

<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 'IvyTranslater Ready'
</screen>

Probe is an interactive program. Type "Hello Paul", and you should receive "Bonjour Paul".
Type "Bye", and the ivyTranslater application should quit to the shell. Just
quit Probe, issuing a Control-D ( or .quit ) on a line, and Probe exists to
the shell.
<screen>
<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>

<para>
The javadoc generated files are available on line on the ivy web site, and
should be included in your ivy java package (or in
/usr/share/doc/libivy-java, alongside with this very manual). Here are more details
on those functions.
</para>

<sect2><title>Initialization an Ivy object and joining the bus</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. It will be the
repository of your agent name, network state, subscriptions, etc. Once this object is
created, you can subscribe to the various Ivy events: text messages through
perl compatible regular expressions, other agents' arrival, departure,
subscription or unsubscription to regexps, direct messages or die command
issued by other agents. At this point, your ivy application is still not connected. In
order to join the bus, call the <function>start(string domain)</function> method on
your Ivy object. This will spawn two threads that will remain active until you
call the <function>stop()</function> method on your Ivy object or until some
other agent sends you a die message. Once this <function>start()</function> method has been called,
the network machinery is set up according to the ivy protocol, and your agent is ready to
handle messages on the bus !
<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 more than one bus at the same time in an application, be it on
the same ivy broadcast address or one different ones. 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 (through <function>String IvyClient.getApplicationName()</function>).
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. Usually, other
application subscribe to this ready message to trigger actions depending on
the presence of your agent on the bus. The <parameter>appcb</parameter> is an object
implementing the IvyApplicationListener interface. Its different methods
are called upon arrival or departure of other agents on the bus, or when your
application itself leaves the bus, or when a direct message is sent to your
application. It is also possible to add or remove other application listeners
using the <function>Ivy.AddApplicationListener()</function> and
<function>Ivy.RemoveApplicationListener()</function> functions.

<programlisting>
public void start(String domainbus) throws IvyException
</programlisting>
This method connects the Ivy bus to a domain or list of domains. This spawns
network managing threads that will be stropped with
<function>Ivy.stop()</function> or when a die message is received. The
rendez-vous point is the String parameter <parameter>domainbus</parameter>, an
UDP broadcast address like "10.0.0:1234" (255 are added at the end to become an
IPv4 UDP broadcast address). This will determine the meeting point of the different
applications. For the gory details, this is done with an UDP broadcast or an
IP Multicast, so 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_BUS</parameter> (set at the invocation of the JVM, e.g $
java -DIVY_BUS=10:4567 myApp, or via an environment variable on older JVMs);
if not present, it will use the default bus, which is 127.255.255.255:2010.
The default address requires a broadcast enabled loopback interface to be
active on your system (CAUTION, on MacOSX and some releases of SunOS, the
default bus doesn't work ...). If an IvyException is thrown, your application
is not able to send or receive data on the specified domain. 

<programlisting>
public void stop() 
</programlisting>
This methods stops the threads, closes the sockets and performs some clean-up.
If there is no other thread running, the program quits. This is the preferred
way to quit a program within a callback (please don't use
<function>System.exit()</function> before
having stopped the bus, even if it works ... ). Note that it is still
possible to 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 echoing a string on a output channel. Portion
of the message will be sent to the connected agent if the message matches
their subscriptions.
<programlisting>
public int sendMsg(String message) 
</programlisting>
Will send each remote agent the substrings in case there is a regexp matching.
The default behaviour is not to send the message to oneself !
The 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. For instance, if
agent B has subscribed to "^a*(.*)c*" and agent A triggers
sendMsg("aaaaaaaaabccccccc"), the agent B will execute its callback with a "b"
parameter.

</para></sect2><sect2><title>Subscription 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. Since ivy-java
1.2.4, Perl Compatible Regular Expressions are used, with the Apache Jakarta
Project regexp library (see the <ulink url="http://jakarta.apache.org/regexp/">jakarta regexp
web site</ulink>). When a message matching the regular expression is detected
on the bus (the matching is done at the sender's side), the recipient's 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 regexp, IvyMessageListener callback);
public void unBindMsg(int id);
</programlisting>
The <parameter>regexp</parameter> follows the PCRE syntax (see man
pcrepattern(3)), grouping is done with brackets. 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>

<para>
There are two ways of defining the callback: the first one is to make an
object an implementation of the IvyMessageListener interface, and to implement
the <function>public void receive(Ivyclient ic, String[] args)</function>
method. But this is limited to one method per class, so the second method used
is the one of inner classes, introduced since java 1.1 and widely used in
swing programs, for instance:
<programlisting>
bindMsg("^a*(.*)c*$", new IvyMessageListener() {
  public void receive(IvyClient ic,String[] args) {
    ... // do some stuff
  }
});
</programlisting>
The processing of the ivy protocol and the execution of the callback are
performed within an unique thread per remote client. Thus, the callback will
be performed sequentially. If you want an asynchronous handling of callbacks,
see in the advanced functions.

</para></sect2><sect2><title>Subscribing to application events</title>
<para>
TODO
</para>
</sect2>

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

<sect2><title>Sending to self</title>
<para>
By default, an application doesn't send the messages to itself. Usually, there
are more efficient and convenient ways to communicate withing a program.
However, if you want to take benefit of the ease of ivy or to be as
transparent as possible, you can set the Ivy object so that the pattern
matching and message sending will be done for the sender too. This method
exists since 1.2.4.
<programlisting>
public void sendToSelf(boolean b);
public boolean isSendToSelf();
</programlisting>
</para>
</sect2>

<sect2><title>Sending to self</title>
<para>
using <command>Ivy.protectNewLine(boolean b)</command>, you can set your Ivy
object to ensure encoding and decoding of newlines characters. This is tested
and working between java ivy applications, but not yet implemented in other
ivy libraries. The newlines are protected by ESC characters ( hex 0x1A ). As
the encoding and decoding cost a little more CPU and is not yet standardized
in the Ivy protocol, use it at your own risk.
</para>
</sect2>

<sect2><title>Sending 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. The full direct message
mechanism in java has been made available since the ivy-java-1.2.3, but i
won't document it to make it harder to use.
</para>
</sect2>

<sect2><title>Asynchronous Subscription to messages</title>
<para>
For each and every remote agent on the bus, a thread is in charge of handling the encoding
and decoding of the messages and of the execution of the callbacks. Thus, if a
callback consumes much time, the rest of the communication is put on hold and
the processing is serialized, eventually leading to a stacking in the socket
buffer and to the blocking of the message sender. To alleviate this, we have
set up since ivy-java 1.2.4 an asynchronous subscription, where each and every
time a callback is performed, it is done in a newly created separate thread.
As creating a thread is quite expensive, one should use this method for
lengthy callbacks only.
<programlisting>
public int bindMsg(String regexp, IvyMessageListener callback,boolean async);
public int bindAsyncMsg(String regexp, IvyMessageListener callback);
</programlisting>
If the <parameter>async</parameter> boolean parameter is set to true, a new
thread will be created for each callback. The same
<function>unBindMsg()</function> can be called to cancel a subscription.
</para>
</sect2>

<sect2><title>Subscribing to subscriptions</title>
<para>
TODO
</para>
</sect2>

</sect1><sect1><title>Utilities</title>

<sect2><title>Probe</title>

<para>
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. To use it, either run fr.dgac.ivy.Probe, or run the jar
file directly with <command>$ java -jar ivy.jar</command>
</para>

<para>
The command line options ( available with the -h command line 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>
-s sends to self ( default off ), allows subscription to its own messages
</para></listitem>
<listitem><para>
-n NEWNAME changes JPROBE default Ivy name to another one, which can prove to
be useful when running different probes
</para></listitem>
<listitem><para>
-t add timestamps to messages
</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>
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>
.direct client id message sends the direct message to the remote client, using
the numeric id
</para></listitem>
<listitem><para>
.bind REGEXP and .unbind REGEXP will change Probe's subscription
</para></listitem>
<listitem><para>
.list gives the list of clients seen on the ivy bus
</para></listitem>
</itemizedlist>
</para>
</sect2>

<sect2><title>IvyDaemon</title>
<para>
As the launching and quitting of an ivy bus is a bit slow, it is not
convenient to spawn an Ivy client each time we want to send a simple message.
To do so, we can use the IvyDaemon, which is a TCP daemon sitting and waiting
on the port 3456, and also connected on the default bus. Each time a remote
application connects to this port, every line read until EOF will be forwarded
on the bus. The standard port and bus domain can be overriden by command line
switches ( use <command>$ java fr.dgac.ivy.IvyDaemon -h</command> ).
First, spawn an ivy Damon: <command>$ java fr.dgac.ivy.IvyDaemon</command>
then, within your shell scripts, use a short tcp connexion ( for instance
netcat ): <command>$ echo "hello world" | nc -q 0 localhost 3456</command>
The "hello world" message will be sent on the default Ivy Bus to anyone having
subscribe to a matching pattern</para>
</sect2>

</sect1><sect1><title>programmer's style guide</title>
<para>TODO

</para></sect1><sect1><title>Contacting the author</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@cena.fr</email>. 

</para></sect1></article>