diff options
Diffstat (limited to 'doc/html/guide/basic.html')
| -rw-r--r-- | doc/html/guide/basic.html | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/doc/html/guide/basic.html b/doc/html/guide/basic.html new file mode 100644 index 0000000..ae5daa0 --- /dev/null +++ b/doc/html/guide/basic.html @@ -0,0 +1,121 @@ +<html> +<head> + <title>ivy java basic functions</title> +</head> +<body> + <table width=100% border=0 cellpadding=0 cellspacing=0><tr><th colspan=3 align=center> + The Ivy java library guide</th></tr><tr> + <td width=10% align=left valign=bottom><a href="first.html">Prev</a></td> + <td width=80% align=center valign=bottom> + <td width=10% align=right valign=bottom><a href="advanced.html">Next</a></td> + </tr></table><hr> + + <h1>Basic functions</h1> + + <h2>Initialization and Ivy loop</h2> + + <p> Initializing a java Ivy agent is a two step process. First of all, + you must create an <em>fr.dgac.ivy.Ivy</em> 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 <em>start()</em> + method on your Ivy object. This will run two threads that will + remain active until you call the <em>stop()</em> method on your Ivy + object. Once the start() method has been called, your agent is ready + to handle messages on the bus ! + + <p>Here are more details on the Ivy constructor: + +<table cellpadding=0 cellspacing=0 width=100%> +<tr bgcolor=#e0e0e0 text=#000000><td> + fr.dgac.ivy.Ivy(java.lang.String name, java.lang.String message, IvyApplicationListener appcb) +<br> +</td></tr></table> + 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. + <li>The <em>name</em> is the name of the application on the bus, + and will by transmitted to other applicatino, and possibly be used + by them. + <li>The <em>message</em> is the first message that will be sent + to other applications, with a slightly different broadcasting scheme + than the normal one ( see <em>The Ivy architecture and procotol</em> + document for more information). If <em>message</em> is null, nothing + will be sent. + <li><em>appcb</em>, 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. + + <p>Here are more details on the start() method: +<table cellpadding=0 cellspacing=0 width=100%> +<tr bgcolor=#e0e0e0 text=#000000><td> +public void start(java.lang.String domainbus) throws IvyException +<br> +</td></tr></table> + + This method connects the Ivy bus to a domain or list of + domains. <em>domainbus</em> 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 list of domains, for instance + "10.0.0.1234,192.168:3456". If the domain is <em>null</em>, the API + will check for the property <em>IVY_DOMAIN</em>, 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. + <p>If an IvyException is thrown, your application is not able to talk to the + domain bus. + + <p>Here are more details on the stop() method: +<table cellpadding=0 cellspacing=0 width=100%> +<tr bgcolor=#e0e0e0 text=#000000><td> +public void stop() +<br> +</td></tr></table> + This methods stops the threads, closes the sockets and does some clean up. + You can reconnect to the bus by calling start() once again. + + <h2>Emitting messages</h2> + + 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. + +<table cellpadding=0 cellspacing=0 width=100%> +<tr bgcolor=#e0e0e0 text=#000000><td> +public int sendMsg(String s) +<br> +</td></tr></table> + Will send each remote agent the substring in case there is a regexp + matching. The int result is the number of messages actually sent. + + <h2>Subscribing to messages</h2> + + 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 bindMsg method to bind a callback to a pattern, and the unbindMsg method to delete the binding. + +<table cellpadding=0 cellspacing=0 width=100%> +<tr bgcolor=#e0e0e0 text=#000000><td> +public int bindMsg(String regex, IvyMessageListener callback) +<br>public void unBindMsg(int id) +<br> +</td></tr></table> + + The <em>regex</em> follows the gnu.regexp regular expression syntax. +Grouping is done with parenthesis. The callback is an object implementing the +IvyMessageListener interface, with the receive method. The thread listening on +the connexion with the sending agent will execute the callback. + + <p><hr><table width=100% border=0 cellpadding=0 cellspacing=0><tr> + <td width=33% align=left valign=top><a href="first.html">Prev</a></td> + <td width=34% align=center valign=top><a href="index.html">Home</a></td> + <td width=33% align=right valign=top><a href="advanced.html">Next</a></td> + </tr><tr> + <td width=33% align=left valign=top>Your first ivy java application</td> + <td width=34% align=center valign=top> </td> + <td width=33% align=right valign=top>Advanced Functions</a></td> + </tr></table> +</body> +</html> |