-
Notifications
You must be signed in to change notification settings - Fork 9
/
README
235 lines (206 loc) · 11 KB
/
README
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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
README file for JADE, Version $Name$
INTRODUCTION
============
This package contains a Java framework to build agent-based systems
according to FIPA standard specifications.
LICENSE
=======
see file License.
FEEDBACK
=======
As you know already, this is still an on-going project.
We are still working on the framework and new versions will be distributed
as soon as available.
Your feedback as users is very important to us. Please, if you have new
requirements that you would like to see implemented or if you have examples
of usage or if you discover some bugs, send us information.
Check the website http://jade.tilab.com/
for how to report bugs and send suggestions.
SYSTEM REQUIREMENTS
===================
To build the framework a complete Java programming environment is
needed. At least a Java Development Kit version 1.4 is required.
KNOWN BUGS
==========
see http://jade.tilab.com/ ('Bugs' page) for the full list of reported bugs
CONTACT
=======
Fabio Bellifemine - TILab S.p.A.
e-mail: [email protected]
INSTALLATION AND TEST
==============================
You can download JADE in source form and recompile it yourself,
or get the pre-compiled binaries (actually they are JAR files).
The following is an excerpt from the programmer's guide.
5.1 Software requirements
=========================
The only software requirement to execute the system is the Java Run Time
Environment version 1.4
Further to the Java Compiler version 1.4, to build the system, the JavaCC
parser generator (version 3.2 of JavaCC since JADE 3.2),
the IDL to Java translator idltojava
(available from the Sun Developer Connection) are also needed. However,
pre-built IDL stubs and Java parser classes are included with the JADE
source distribution such that the Java compiler is sufficient to build
the full system, finally the ANT program to compile the source code of
JADE with build.xml file, ANT is available from http://jakarta.apache.org.
5.2 Getting the software
========================
All the software is distributed under the LGPL license limitations.
It can be downloaded from the JADE web site
http://jade.tilab.com/ Five compressed files are available:
1. the source code of JADE
2. the source code of the examples
3. the documentation, including the javadoc of the JADE API and
this programmer's guide
4. the binary of JADE, i.e. the jar files with all the Java classes
5. a full distribution with all the previous files
5.3 Running JADE from the binary distribution
=============================================
Having uncompressed the archive file, a directory tree is generated whose
root is jade and with a lib subdirectory. This subdirectory contains some
JAR files that have to be added to the CLASSPATH environment variable.
Having set the classpath, the following command can be used to launch the
main container of the platform. The main container is composed of the DF
agent, the AMS agent, and an RMI registry (that is used by JADE for
intra-platform communication).
java jade.Boot [options] [Agent list]
Additional agent containers can be then launched on the same host, or on
remote hosts, that connect themselves with the main container of the Agent
Platform, resulting in a distributed system that seems a single Agent
Platform from the outside.
An Agent Container can be started using the command:
java jade.Boot -container [options] [Agent list]
An alternative way of launching JADE is the following command:
java -jar lib\jade.jar -nomtp [options] [Agent list]
see the Administrator's guide for the list of
options available from the command line
5.3.2 Launching agents from the command line
============================================
A list of agents can be launched directly from the command line. As described
above, the [Agent list] part of the command is a sequence of strings separated
by a space.
Each string is broken in two parts separated by a colon ':' character. The
substring before the colon is taken as the agent name, whereas the substring
after the colon is the name of the Java class implementing the agent. This
class will be dynamically loaded by the Agent Container.
For example, a string Peter:myAgent means "create a new agent named Peter
whose implementation is an object of class myAgent". The name of the class
must be fully qualified, (e.g. Peter:myPackage.myAgent) and will be searched
for according to CLASSPATH definition.
5.3.3 Example
=============
First of all set the CLASSPATH to include the JAR files in the lib
subdirectory and the current directory. For instance, for Windows 9x/NT use
the following command:
set CLASSPATH=%CLASSPATH%;.;c:\jade\lib\jade.jar;
c:\jade\lib\jadeTools.jar; c:\jade\lib\Base64.jar;
c:\jade\lib\http.jar
Execute the following command to start the main-container of the platform.
Let's suppose that the hostname of this machine is "kim.cselt.it"
prompt> java jade.Boot -gui
Execute the following command to start an agent container on another machine,
by telling it to join the AgentPlatform, called "facts" running on the host
"kim.cselt.it", and start one agent (you must download and compile the
examples agents to do that):
prompt> java jade.Boot -host kim.cselt.it -container
sender1:examples.receivers.AgentSender
where "sender1" is the name of the agent,
while examples.receivers.AgentSender is the code that implements the agent.
Execute the following command on a third machine to start another agent
container telling it to join the Agent Platform, called "facts" running on
the host "kim.cselt.it", and then start two agents.
prompt> java jade.Boot -host kim.cselt.it -container
receiver2:examples.receivers.AgentReceiver
sender2:examples.receivers.AgentSender
where the agent named sender2 is implemented by the class
examples.receivers.AgentSender, while the agent named receiver2 is
implemented by the class examples.receivers.AgentReceiver.
5.4 Building JADE from the source distribution
==============================================
If you downloaded the source code of JADE, you can compile it by using the
"ant" program, a platform independent version of make.
The file "build.xml" in the JADE root directory is the input file for ant.
The "ant" program must
be installed on your computer, it can be downloaded from the Jakarta Project
at the Apache web site: <http://jakarta.apache.org/>.
5.4.1 Building the JADE framework
=================================
Just type
ant jade
you run ant on build.xml file in the root directory.
You will end up with all JADE classes in a classes subdirectory. You can add
that directory to your CLASSPATH and make sure that everything is OK by
running JADE, as described in the previous section.
5.4.2 Building JADE libraries
============================
Type:
ant lib
This will remove the content of the classes directory and will create some
JAR files in the lib directory. These JAR files are just the same you get
from the binary distribution. See section 5.3 for a description on how to
run JADE when you have built the JAR files.
NOTE: jade/lib/Base64.jar is only needed if you want to use the support for JADE
serialization and trasmitting sequences of bytes within an ACLMessage. In all
other cases, it is not necessary adding it to CLASSPATH .
5.4.3 Building JADE HTML documentation
======================================
Type:
ant doc
You will end up with Javadoc generated HTML pages, integrated within the
overall documentation. Beware that the Programmer's Guide is a PDF file that
cannot be generated at your site, but you must download it (it is, of course,
in the JADE documentation distribution).
5.4.4 Building JADE examples and demo application
=================================================
If you downloaded the examples/demo archive and have unpacked it within the
same source tree, you will have to set your CLASSPATH to contain either the
classes directory or the JAR files in the lib directory, depending on your
JADE distribution, and then type:
ant examples
In order to compile the Jess-based example, it is necessary to have the JESS
system, to set the CLASSPATH to include it and to set JESS_HOME. The example
can be compiled by typing:
ant jessexample
5.4.5 Cleaning up the source tree
=================================
If you type:
ant clean
you will remove all generated files (classes, HTML pages, JAR files, etc.)
from the source tree. If you use makefiles, you will find some other make
targets you can use. Feel free to try them, especially if you are modifying
JADE source code, but be aware that these other make targets are for internal
use only, so they have not been documented.
5.6 IIOP support and inter-platform messaging
=============================================
JADE supports FIPA compliant IIIOP communication for inter-platform agent
communication. This mechanism is used both to communicate with another JADE
platform and with a non-JADE platform. JADE achieves complete transparency
in message passing even when multiple agent platforms are involved, so agent
developers need not worry about IIOP: JADE selects local Java events, RMI or
CORBA/IIOP automatically on behalf of the application.
The only issue application developers and platform administrators must be
aware-of is agent naming. An agent identifier, in fact, must include a set
of URL representing the addresses where it can be contacted.
Every JADE agent inherits the addresses of its platform and its AID
(including the addresses) is fully generated automatically by JADE when
messages are sent externally to the platform.
Because most of the CORBA ORB implementations (including the one used by
JADE) do not yet allow to choose meaningful words as object keys, JADE
resorts to the alternate naming scheme, adopted also by FIPA,
using OMG standard stringified IOR as agent addresses. A valid agent address
can be both an URL like iiop://fipa.org:50/acc and an IOR as
IOR:000000000000001649444c644f4)
The IOR-based representation and the URL-based one are exactly equivalent,
the URL being far more readable for humans than the IOR. JADE generates
IOR-based addresses but can also deal with URL-based ones as long as the URL
contains only printable characters (i.e. has been created by an ORB allowing
explicit object key assignment) that can be parsed by a FIPA-compliant parser.
When starting up, JADE platform prints its IOR both on the standard output
and in a ASCII file named JADE.IOR, located in the current directory; the
URL for the platform (containing a binary string in the file part) is also
written to the file JADE.URL in the current directory. Every agent address
automatically includes this platform IOR that should be distributed to remote
platforms in order to allow remote agents to send messages to your JADE
agents. The distribution mechanism is not specified by FIPA and is
application dependent.