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.