From fe015aed1f9aa5f2d7247f9262d7f12c59536379 Mon Sep 17 00:00:00 2001
From: jestin
Date: Wed, 6 Jul 2005 20:03:33 +0000
Subject: mises à jour de la doc pour nouvelles fonctions de l'API, tout ça
 tout ça

---
 doc/ivy-java.sgml | 152 ++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 102 insertions(+), 50 deletions(-)

(limited to 'doc')

diff --git a/doc/ivy-java.sgml b/doc/ivy-java.sgml
index 175b684..866a08d 100644
--- a/doc/ivy-java.sgml
+++ b/doc/ivy-java.sgml
@@ -1,5 +1,5 @@
 <!--
-	The Ivy java guide
+	The Ivy Java guide
 
 	Copyright (c) 1999-2004
 	Centre d'Etudes de la Navigation Aerienne
@@ -22,7 +22,7 @@
 <holder>CENA, Centre d'Etudes de la Navigation Aérienne</holder>
 </copyright>
 
-<title>The Ivy java library guide</title>
+<title>The Ivy Java library guide</title>
 <subtitle>CENA NT02-819</subtitle>
 <titleabbrev>NT02-819 © CENA</titleabbrev>
 
@@ -43,7 +43,7 @@
 <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
+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>
@@ -51,7 +51,6 @@ url="http://www.tls.cena.fr/products/ivy/">Ivy web site</ulink>.
 </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
@@ -61,12 +60,10 @@ 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
@@ -82,10 +79,10 @@ 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
+Ivy is implemented as a collection of libraries 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
+this guide of the Java 
+library, please refer to <citetitle>The Ivy software 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
@@ -95,20 +92,20 @@ available from <ulink url="http://www.tls.cena.fr/products/ivy/">the Ivy Web sit
 </para>
 </sect1>
 
-<sect1><title>The Ivy java library</title>
+<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
+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
+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
+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
+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>
@@ -153,7 +150,9 @@ machine to the jar file or your installation is incomplete.
 </para>
 </sect2>
 
-</sect1><sect1><title>Your first Ivy application</title>
+</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
@@ -201,8 +200,9 @@ class ivyTranslater implements IvyMessageListener {
 }
 </programlisting>
 
-</para></sect2><sect2><title>Compiling it</title>
+</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):
@@ -210,15 +210,15 @@ following command (if the ivy-java jar is in your development classpath):
 $ <userinput>javac ivyTranslater.java</userinput>
 $
 </screen>
+</para></sect2>
 
-</para></sect2><sect2><title>Testing</title>
+<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
@@ -249,11 +249,11 @@ IvyTranslater disconnected
 <userinput>&lt;Ctrl-D&gt;</userinput>
 $
 </screen>
-
 </para></sect2>
 
-</sect1><sect1><title>Basic functions</title>
+</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
@@ -261,14 +261,14 @@ should be included in your ivy java package (or in
 on those functions.
 </para>
 
-<sect2><title>Initialization an Ivy object and joining the bus</title>
+<sect2><title>Initialisation an Ivy object and joining the bus</title>
 
 <para>
-Initializing a java Ivy agent is a two step process. First of all, you must
+Initialising 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,
+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
@@ -287,7 +287,7 @@ 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
+architecture and protocol</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
@@ -304,7 +304,7 @@ public void start(String domainbus) throws IvyException
 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
+rendezvous 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
@@ -328,10 +328,10 @@ 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>
+again (the bug has been corrected since 1.2.8).
+</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
@@ -348,8 +348,9 @@ message sent doesn't contains protocol characters: 0x01 to 0x08 and
 unfortunately 0x0D, the newline character. If you want to send newlines, see
 protectNewline, in advanced functions.
 
-</para></sect2><sect2><title>Subscription to messages</title>
+</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
@@ -376,7 +377,7 @@ 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
+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() {
@@ -390,13 +391,17 @@ 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></sect2>
+
+<sect2><title>Subscribing to application events</title>
 <para>
 TODO
 </para>
 </sect2>
 
-</sect1><sect1><title>Advanced functions</title>
+</sect1>
+
+<sect1><title>Advanced functions</title>
 
 <sect2><title>Sending to self</title>
 <para>
@@ -413,6 +418,26 @@ public boolean isSendToSelf();
 </para>
 </sect2>
 
+<sect2><title>Initializing a domain</title>
+<para>
+The default behaviour of an Ivy agent is to accept a command line switch ( -b
+10:2010, e.g. ), and if not present, to use the IVYBUS property, ( given by the
+-DIVYBUS=10:34567 parameter to the jvm ), and, if not present, to default to
+Ivy.DEFAULT_DOMAIN. This domain is given as a string ardument to the
+Ivy.start() function. To make this logic easier to follow, the Ivy class
+provides the programmer with two useful function:
+<programlisting>
+public static String getDomain(String arg);
+public static String getDomainArgs(String progname,String[] args);
+</programlisting>
+The getDomain() function, if arg is non null, will return arg, otherwise it
+will return the IVYBUS property, otherwise the DEFAULT_DOMAIN. A very simple
+way to start an Ivy agent is with ivy.start(getDomain(null)). The
+getDomainArgs(name,args) will add very simple processing of the args given to
+the main() function, and give higher priority to the command line argument.
+</para>
+</sect2>
+
 <sect2><title>Newline within messages</title>
 <para>
 As we have seen in <function>Ivy.sendMsg()</function>, you can not have
@@ -420,11 +445,11 @@ newline characters within the string you send on the bus. If you still want to
 send messages with newline, you can encode and decode them at the emitter and
 receiver's side. With <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
+and working between Java ivy applications, but not yet implemented in other
 ivy libraries. The newlines are replaced by ESC characters ( hex 0x1A ). As
-the encoding and decoding cost a little more CPU and is not yet standardized
+the encoding and decoding cost a little more CPU and is not yet standardised
 in the Ivy protocol, use it at your own risk. We should of course protect the
-other protocol special caracters.
+other protocol special characters.
 </para>
 </sect2>
 
@@ -435,7 +460,7 @@ 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
+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>
@@ -445,7 +470,7 @@ won't document it to make it harder to use.
 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
+the processing is serialised, 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.
@@ -465,7 +490,7 @@ thread will be created for each callback. The same
 
 <sect2><title>Waiting for someone: waitForClient and waitForMsg</title>
 <para>
-Very often, while developping an Ivy agent, you will be facing the need of the
+Very often, while developing an Ivy agent, you will be facing the need of the
 arrival of another agent on the bus to perform your task correctly. For
 instance, for your spiffy application to run, a gesture recognition engine
 will have to be on the bus, or another data sending application. The Ivy way
@@ -492,7 +517,23 @@ you'd wait for nothing. You had better be sure that the
 
 <sect2><title>Subscribing to subscriptions</title>
 <para>
-TODO
+A very common practice when beginning to play with ivy is to develop an ivy
+agent monitor (the good practice is to use the excellent ivymon written in
+perl by Daniel Etienne). If you want to notity the user that a remote agent
+has subscribed or unsubscribed to a regular expression after the
+protocol handshake, then your monitor agent has to subscribe to subscriptions.
+To do so, use the following functions:
+<programlisting>
+public int addBindListener(IvyBindListener callback);
+public void	 removeBindListener(int id)
+</programlisting>
+A <function>IvyBindListener</function> object must implement the following
+interface:
+<programlisting>
+public void bindPerformed(IvyClient client, int id, String regexp);
+public void unbindPerformed(IvyClient client, int id, String regexp);
+</programlisting>
+For a code sample, see the Probe utility source code.
 </para>
 </sect2>
 
@@ -501,7 +542,7 @@ TODO
 <sect2><title>Probe</title>
 
 <para>
-Probe is your swiss army knife as an Ivy java developper. Use it
+Probe is your swiss army knife as an Ivy Java developer. 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>
@@ -513,11 +554,11 @@ 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.
+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
+defaults to JPROBE, but it might be difficult to differentiate which jprobe
 sent which message with a handful of agents with the same name
 </para></listitem>
 <listitem><para>
@@ -544,7 +585,7 @@ fr.dgac.ivy.Probe -d )
 </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
+list of available commands. 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>
@@ -553,7 +594,7 @@ dot commands are the following
 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 ).
+.bye (or .quit) forces the JPROBE application to exit. This is the same as inputting 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
@@ -576,24 +617,35 @@ 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
+on the bus. The standard port and bus domain can be overridden 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
+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>
+TODO
+</para>
+</sect1>
 
-</para></sect1><sect1><title>Contacting the author</title>
+<sect1><title>Contacting the author</title>
 <para>
-The Ivy java library is now maintained by Yannick Jestin. For bug reports or
+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>
+
+<para>
+If you report a bug, try to identify the causal path leading to the
+bug, and submit a trace of the problem, if possible, using the -DIVY_DEBUG
+property to produce a trace of the ivy execution.
+</para>
+</sect1>
 
-</para></sect1></article> 
+</article> 
-- 
cgit v1.1