diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ivy-java.1 | 46 | ||||
| -rw-r--r-- | doc/ivy-java.sgml | 549 |
2 files changed, 310 insertions, 285 deletions
diff --git a/doc/ivy-java.1 b/doc/ivy-java.1 index 5887da2..0056891 100644 --- a/doc/ivy-java.1 +++ b/doc/ivy-java.1 @@ -1,31 +1,30 @@ .\" '\" .\" '\" Ivy, Java interface \- library managing connexions to a software bus .\" '\" -.\" '\" Copyright (C) 1997-1999 +.\" '\" Copyright (C) 1997-2004 .\" '\" Centre d'Études de la Navigation Aérienne .\" '\" .\" '\" See the file "license.terms" for information on usage and redistribution .\" '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. .\" '\" .\" '\" -.TH "Ivy-java" "" "" "Yannick Jestin" "" +.TH "Ivy-java" "" "" "Yannick Jestin <jestin@cena.fr>" "" .SH "NAME" ivy\-java \- a software bus library java implementation .SH "SYNOPSIS" Ivy\-java provides a useful set of Java library classes for communicating between different processes through a software bus .SH "DESCRIPTION" -Ivy is a software bus, ie a system that allows any software component to freely - exchange data. +Ivy is a software bus, i.e. a system that allows any software component to + exchange data freekly. The basic principle of a software bus is to ease the rapid implementation of new -agents, and to manage a dynamic collection of agents on the bus: agents connect, -send and receive messages, and disconnect without perturbing the overall +agents, and to manage a dynamic collection of agents on the bus. Agents connect, +send messages, receive messages, and disconnect without hindering the overall functionnality of the bus. -Each time an application initializes a connection on the bus, a "ready" message -is sent to all other applications already connected, and the list of the messages -subscribed by this application is dispatched.The format for the messages is free. +Each time an application initializes a connection on the bus, it publishes the +list of the messages it has subscribed to and then emits a a ready message. .nf The essential classes of Ivy Java are: @@ -34,30 +33,32 @@ The essential classes of Ivy Java are: \ API for the connexion to the software bus .nf .I IvyApplicationListener: -\ contains 4 virtual methods for handling connexion/deconnexion, +\ contains 4 virtual methods for handling connexion, deconnexion, die and direct messages .nf .I IvyApplicationAdapter: \ to implement the IvyApplicationListener methods .nf .I Probe: -\ to test the regular expressions in a terminal +\ a tool to connect to the bus and exchange with the other agents .nf .I IvyDaemon: \ a daemon to access the bus via a simple socket: you connect (default port : -3456 ), write a msg, and exit, the daemon will send the message. This is -useful in shell scripts, in cunjunction with netcat ( echo "coucou" | nc \-q 0 -localhost 3456 ) +3456 ), write a message, and exit. The IvyDaemon firts sets up the Ivy +mechanisms and listens to that socket, and each time a string is sent on the +socket, it is forwarded to the bus. This is useful in shell scripts, in cunjunction +with the TCP/UP swiss army knif netcat. For instance: echo "coucou" | nc \-q 0 localhost 3456 .SH "ENVIRONMENT" .I the IVYBUS property can be given via the \-DIVYBUS=xxx.yyy.zzz:port command line argument. It can be a list of addresses followed by a port number. The default is a datagram local address on a non priviledged port 127.255.255.255:2010 , it can also be shortened to 127:2010. You can specify other datagram adresses with respect to your -local configuration (see ifconfig(1) ), and you can specify a multicast -address 228.5.6.7:8910 for instance. You can supply multiple domains, separated by colons +local configuration (see ifconfig(1) ), and you can specify an IP multicast +address 228.5.6.7:8910 for instance. You can supply multiple domains, +separated by colons. -.I the IVYBUS shell variable is not used, since the policy of the JDK has +.I the IVYBUS shell variable is not used any more, since the policy of the JDK has changed on this point since 1.3 . You can still use it on a previous JDK. .nf @@ -77,11 +78,10 @@ java fr.dgac.ivy.Probe \-b 10.192.36:2021 '^coucou (.*)' .SH "NEEDED LIBRARIES" .I jdk from 1.1 to 1.4 .nf -.I libgnu\-regexp\-java version 1.1.3 +.I the apache jakarta project regexp library ( supersedes libgnu\-regexp\-java +since ivy 1.2.6 ) .nf -.I libgnu\-getopt\-java version 1.0.9 -.nf -.I If you want to run the TestIvySwing example with a 1.1 VM, you will need a swing jar +.I libgnu\-getopt\-java .SH "BUGS" See the BUGS files for details. @@ -90,7 +90,7 @@ See the BUGS files for details. .nf Yannick Jestin <jestin@cena.fr> .nf -initially: Francois\-Regis Colin <fcolin@cena.fr> +Francois\-Regis Colin <fcolin@cena.fr> .SH "SEE ALSO" ivy\-c (1) .nf @@ -99,6 +99,8 @@ ivy\-perl (1) ivy\-c\-functions (1) .nf ivyprobe (1) +.nf +pcrepattern (3) .sp For further details, please refer to the Ivy html page at http://www.tls.cena.fr/products/ivy/ diff --git a/doc/ivy-java.sgml b/doc/ivy-java.sgml index 5408851..1691119 100644 --- a/doc/ivy-java.sgml +++ b/doc/ivy-java.sgml @@ -1,12 +1,12 @@ <!-- The Ivy java guide - Copyright (c) 1999-2000 + Copyright (c) 1999-2004 Centre d'Etudes de la Navigation Aerienne SGML source file - Authors: Yannick Jestin <jestin@cena.fr> + Author: Yannick Jestin <jestin@cena.fr> --> @@ -18,11 +18,11 @@ <artheader> <copyright> -<year>2000</year> +<year>2004</year> <holder>CENA, Centre d'Etudes de la Navigation Aérienne</holder> </copyright> -<title>The Ivy C++ and java library guide</title> +<title>The Ivy java library guide</title> <subtitle>CENA NT02-819</subtitle> <titleabbrev>NT02-819 © CENA</titleabbrev> @@ -32,10 +32,10 @@ <affiliation><address><email>jestin@cena.fr</email></address></affiliation> </author> </authorgroup> -<date>August 4, 2000</date> +<date>August 27, 2004</date> <copyright> -<year>2000</year> +<year>2004</year> <holder>Centre d'Études de la Navigation Aérienne</holder> </copyright> @@ -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 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> @@ -59,33 +59,26 @@ 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. +incomplete, is quite 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 +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. +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> @@ -96,7 +89,8 @@ 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 +<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> @@ -105,17 +99,18 @@ available from <ulink url="http://www.tls.cena.fr/products/ivy/">the Ivy Web sit <sect2><title>What is it?</title> <para> -The Ivy java library (aka ivy-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 -application. So far, this library has been tested and used on a variety of -java virtual machines (from 1.1.7 to 1.4.1), and on a variety of architectures +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 then -by Yannick Jestin at CENA. It is maintained by a group at CENA (Toulouse, France) +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> @@ -126,14 +121,24 @@ 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). +(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 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. +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> @@ -141,29 +146,24 @@ In order to test the presence of Ivy on your system once installed, run the foll <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 ( +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. +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 "Hello", and re-emit them after -translating "Hello" into "Bonjour". In addition, the application will quit when -it receives any message containing exactly "Bye". +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.* ; @@ -171,35 +171,38 @@ class ivyTranslater implements IvyMessageListener { private Ivy bus; - ivyTranslater() { - // initialization - bus = new Ivy("IvyTranslater","Hello le monde",null); + 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() { - // callback for "Bye" message - public void receive(IvyClient client, String[] args) {System.exit(0);} + public void receive(IvyClient client, String[] args) { + // leaves the bus, and as it is the only thread, quits + bus.stop(); + } }); - 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()); - } + bus.start(null); // starts the bus on the default domain } // callback associated to the "Hello" messages" public void receive(IvyClient client, String[] args) { - bus.sendMsg("Bonjour"+((args.length>0)?args[0]:"")); + try { + bus.sendMsg("Bonjour"+((args.length>0)?args[0]:"")); + } catch (IvyException ie) { + System.out.println("can't send my message on the bus"); + } } - public static void main(String args[]) { new ivyTranslater(); } + public static void main(String args[]) throws IvyException { + new ivyTranslater(); + } } </programlisting> -</para> -</sect2> +</para></sect2><sect2><title>Compiling it</title> -<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): @@ -207,19 +210,21 @@ following command (if the ivy-java jar is in your development classpath): $ <userinput>javac ivyTranslater.java</userinput> $ </screen> -</para> -</sect2> - -<sect2><title>Testing</title> +</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>. +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> -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: +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 (.*) @@ -227,7 +232,14 @@ broadcasting on 127.255.255.255:2010 IvyTranslater connected IvyTranslater subscribes to ^Bye$ IvyTranslater subscribes to ^Hello(.*) -IvyTranslater sent 'Hello le monde' +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> -> Sent to 1 peers IvyTranslater sent 'Bonjour Paul' @@ -238,110 +250,232 @@ IvyTranslater disconnected $ </screen> -</para> -</sect2> -</sect1> - -<sect1><title>Basic functions</title> +</para></sect2> -<sect2><title>Initialization and Ivy threads</title> +</sect1><sect1><title>Basic functions</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 ! +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> -<para> -Here are more details on those functions: +<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) +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 +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. The <parameter>message</parameter> -is the first message that will be sent to other applications, with a slightly +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. -<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. +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. -<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 +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_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. +<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. -You can reconnect to the bus by calling <function>start()</function> once again. +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></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. - +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 substring in case there is a regexp matching. -The int result is the number of messages actually sent. The main issue here is +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. +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> -<sect2><title>Subscribing to messages</title> +</sect1><sect1><title>Advanced functions</title> +<sect2><title>Sending to self</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. - +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 int bindMsg(String regex, IvyMessageListener callback); -public void unBindMsg(int id); +public void sendToSelf(boolean b); +public boolean isSendToSelf(); </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> +<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> -</sect1> +<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> -<sect1><title>Advanced functions</title> +<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> -<sect2><title>fr.dgac.ivy.Probe utility</title> +</sect1><sect1><title>Utilities</title> + +<sect2><title>Probe</title> <para> -fr.dgac.ivy.Probe is your swiss army knife as an Ivy java developper. Use it +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. +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 --help switch ) are the +The command line options ( available with the -h command line switch ) are the following: <itemizedlist> <listitem><para> @@ -354,7 +488,17 @@ 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. +-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 @@ -365,9 +509,6 @@ fr.dgac.ivy.Probe -d ) -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 @@ -386,158 +527,40 @@ with this name to leave the bus the numeric id </para></listitem> <listitem><para> -.list gives the list of clients seen on the ivy bus +.bind REGEXP and .unbind REGEXP will change Probe's subscription </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. +.list gives the list of clients seen on the ivy bus </para></listitem> </itemizedlist> </para> </sect2> -<sect2><title>fr.dgac.ivy.IvyDaemon utility</title> +<sect2><title>IvyDaemon</title> <para> -As the launching and quitting of an ivy bus is a bit slow, it is not +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. ( java fr.dgac.ivy.IvyDaemon -h ). -</para> - -<para>First, spawn an ivy Damon: $ java fr.dgac.ivy.IvyDaemon</para> -<para>then, within your shell scripts, use a short tcp connexion ( for instance -netcat ) : $ echo "hello world" | nc -q 0 localhost 3456 -</para> -<para>The message will be sent on the default Ivy Bus.</para> +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> -<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. The full direct message -mechanism in java has been made available since the ivy-java-1.2.3. -</para> -</sect2> - -</sect1> +</sect1><sect1><title>programmer's style guide</title> +<para>TODO -<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 <iostream.h> - -#include <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->BindMsg( "^Hello(.*)", BUS_CALLBACK_OF(cIvyTranslater, HelloCallback )); - count = bus->BindMsg( "^Bye$", BUS_CALLBACK_OF(cIvyTranslater, ByeCallback )); - - bus->start("127.255.255.255:2010"); -} - -void cIvyTranslater::HelloCallback(IvyApplication *app, int argc, const char **argv) -{ - const char* arg = (argc < 1) ? "" : argv[0]; - cout << "cIvyTranslater received msg: Hello'" << arg - << "'" << endl; - bus->SendMsg( "Bonjour%s!", arg ); -} - -void cIvyTranslater::ByeCallback(IvyApplication *app, int argc, const char **argv) -{ - cout << "cIvyTranslater stops bus" << endl; - if (bus) { - TheGrassIsGreenAndTheWindBlows = false; - bus->stop(); - delete bus; // This statement is never reached! Don't know why! - } - -} - -void cIvyTranslater::OnApplicationConnected(IvyApplication *app) -{ - cout << "cIvyTranslater is ready to accept messages from " - << app->GetName() << endl; -} - -void cIvyTranslater::OnApplicationDisconnected(IvyApplication *app) -{ - cout << "cIvyTranslater good buy '" << app->GetName() - << "'" << endl; -} - - -void main(int argc, char* argv[]) -{ - cIvyTranslater aIvyTL; - - while (TheGrassIsGreenAndTheWindBlows) { - Sleep(2000); - cout << "new cycle..." << endl; - } - cout << "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></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@tls.cena.fr</email>. -</para> -</sect1> +(protocol, applications, etc), please join and use the Ivy mailing list +<email>ivy@cena.fr</email>. -</article> +</para></sect1></article> |