diff options
| -rw-r--r-- | doc/ivy-java.sgml | 152 |
1 files changed, 102 insertions, 50 deletions
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><Ctrl-D></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> |