1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
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>
|
