diff options
| -rw-r--r-- | doc/ivy-java.sgml | 48 |
1 files changed, 27 insertions, 21 deletions
diff --git a/doc/ivy-java.sgml b/doc/ivy-java.sgml index 866a08d..dd8223e 100644 --- a/doc/ivy-java.sgml +++ b/doc/ivy-java.sgml @@ -18,8 +18,8 @@ <artheader> <copyright> -<year>2004</year> -<holder>CENA, Centre d'Etudes de la Navigation Aérienne</holder> +<year>2005</year> +<holder>DGAC/DSNA/DTI</holder> </copyright> <title>The Ivy Java library guide</title> @@ -32,18 +32,18 @@ <affiliation><address><email>jestin@cena.fr</email></address></affiliation> </author> </authorgroup> -<date>August 27, 2004</date> +<date>November 22, 2005</date> <copyright> -<year>2004</year> -<holder>Centre d'Études de la Navigation Aérienne</holder> +<year>2005</year> +<holder>DGAC/DSNA/DTI</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 +version 1.2.8 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> @@ -141,12 +141,14 @@ Those could be included in the jar file, but not in the debian package. <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> +$ <userinput>java fr.dgac.ivy.tools.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. + +Alternatively, you can use the jprobe shell script. </para> </sect2> @@ -214,19 +216,19 @@ $ <sect2><title>Testing</title> <para> -We are going to test our application with <command>fr.dgac.ivy.Probe</command>. +We are going to test our application with <command>fr.dgac.ivy.tools.Probe</command>. In a shell, launch ivyTranslater: <screen> $ <userinput>java ivyTranslater</userinput> </screen> -In another shell, launch <command>java fr.dgac.ivy.Probe '(.*)'</command>. +In another shell, launch <command>java fr.dgac.ivy.tools.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> +$ <userinput>java fr.dgac.ivy.tools.Probe '(.*)'</userinput> you want to subscribe to (.*) broadcasting on 127.255.255.255:2010 IvyTranslater connected @@ -328,7 +330,7 @@ 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 (the bug has been corrected since 1.2.8). +again. </para></sect2> <sect2><title>Emitting messages</title> @@ -409,8 +411,7 @@ 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. +matching and message sending will be done for the sender too. <programlisting> public void sendToSelf(boolean b); public boolean isSendToSelf(); @@ -460,8 +461,8 @@ 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. +mechanism in Java has been made available since the ivy-java-1.2.3, but it +won't be much documented, in order to make it harder to use. </para> </sect2> @@ -472,7 +473,7 @@ 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 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 +set up (since 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. Furthermore, to avoid concurrent access to the @@ -544,7 +545,7 @@ For a code sample, see the Probe utility source code. <para> 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 +log the messages, etc. To use it, either run fr.dgac.ivy.tools.Probe, or run the jar file directly with <command>$ java -jar ivy.jar</command> </para> @@ -576,8 +577,8 @@ be useful when running different probes </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 ) +VY_DEBUG property ( java -DIVY_DEBUG fr.dgac.ivy.tools.Probe is the same as java +fr.dgac.ivy.tools.Probe -d ) </para></listitem> <listitem><para> -h dumps the command line options help. @@ -618,14 +619,19 @@ 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 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> +switches ( use <command>$ java fr.dgac.ivy.tools.IvyDaemon -h</command> ). +First, spawn an ivy Damon: <command>$ java fr.dgac.ivy.tools.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> +<sect2><title>After</title> +<para> +TODO +</sect2> + </sect1><sect1><title>programmer's style guide</title> <para> TODO |