In this brief "how-to", you will learn how to get TuCSoN4JADE (t4j for short), build it and run a first example showcasing its features.
Assumptions are you are familiar with Java (compilation), JADE (usage), Git (cloning repositories) and, optionally, ANT (buildfiles).
1.1 Downloading
1.2 Compiling
1.3 Deploying
1.4 Running
If you want the ready-to-use distribution of t4j, download t4j.jar archive from the "Downloads" section, here > http://bitbucket.org/smariani/tucson4jade/downloads.
If you want the source code of t4j, clone the t4j Git repository hosted here on Bitbucket, at > http://smariani@bitbucket.org/smariani/tucson4jade.git (e.g., from a command prompt type $> git clone https://smariani@bitbucket.org/smariani/tucson4jade.git) [1].
In the former case, skip to the "Running" section below. In the latter case, keep reading.
By cloning t4j you have downloaded a folder named tucson4jade/, with the following directory structure:
tucson4jade/
|__...
|__t4j/
|__...
|__ant-scripts/
|__build.xml
|__environment.properties
|__eclipse-config/
|__how-to/
|__license-info/
|__src/
t4j depends on 3 other Java libraries to function properly [2]:
Once you got the above libraries, you are ready to compile t4j source code.
The easiest way to do so is by exploiting the ANT script named build.xml within folder ant-scripts/, which takes care of the whole building process for you, from compilation to deployment (covered in next section). To do so, you need to have ANT installed on your machine [3]. If you don't want to use ANT, build t4j jar archive using the tools you prefer, then skip to the "Running" section below.
To compile t4j using ANT:
Edit the environment.properties file according to your system configuration:
1.1 Tell ANT where your JDK and your java tool are
1.2 Tell ANT which libraries are needed to compile t4j (those you just downloaded, that is JADE, TuCSoN and tuProlog)
1.3 Tell ANT where you put such libraries (e.g. if you put them into t4j/libs/ you are already set)
[1.4 Tell ANT your Bitbucket username (for automatic syncing with t4j repository, not supported at the moment)]
Launch the ANT script using target compile (e.g., from a command prompt position yourself into the ant-scripts/ folder then type $> ant compile) [4]. This will create folder classes/ within folder t4j/ and therein store Java .class files.
Other ANT targets are available through the build.xml file: to learn which, launch the ANT script using target help.
Deploying t4j is as simple as giving a different build target to the ANT script build.xml:
if you only want the t4j jar archive, ready to be included in your JADE project, launch the script using target lib. This will compile t4j source code into binaries (put into t4j/classes/ folder) then package them to t4j.jar into t4j/lib/ folder [5].
if you want a ready-to-release distribution of t4j, including also documentation and support libraries, launch the script using target dist. This will:
t4j/classes/ foldert4j/lib/ foldert4j/doc/ foldercreate folder jade/add-ons/TuCSoN4JADE-${version} including:
docs/ including the generated Javadoc information as well as this "how-to"libs/ including JADE, TuCSoN and tuProlog libraries used to build t4jrel/ including t4j jar archivesThe complete directory structure obtained by launching ant dist build process should look like the following (assuming you put JADE, TuCSoN and tuProlog libraries in folder t4j/libs/):
tucson4jade/
|__...
|__t4j/
|__...
|__ant-scripts/
|__build.xml
|__environment.properties
|__classes/
|__doc/
|__eclipse-config/
|__how-to/
|__jade/
|__add-ons/
|__TuCSoN4JADE-${version}/
|__docs/
|__how-to/
|__javadoc/
|__libs/
|__rel/
|__...
|__lib/
|__libs/
|__license-info/
|__src/
Other ANT targets are available through the build.xml file: to learn which, launch the ANT script using target help.
To run t4j, you need:
Supposing you built t4j using the provided ANT script [6] and that you are comfortable with using a command prompt to launch Java applications [7]:
t4j/lib/ or t4j/jade/add-ons/TuCSoN4JADE-${version}/rel/ folderlaunch the JADE platform specifying you want to exploit TuCSoN services provided by t4j, e.g. as follows [8]:
java -cp t4j.jar:../libs/tucson.jar:../libs/2p.jar:../libs/jade.jar jade.Boot -gui -services it.unibo.tucson.jade.service.TucsonService
JADE GUI should appear as well as the t4j ASCII logo on the command prompt, as depicted below.
As long as no JADE agents start exploiting TuCSoN coordination services wrapped by t4j, nothing happens. Thus, here follows instructions on how to launch the example application shipped within t4j.jar, showcasing its features: the "Book Trading" MAS (package it.unibo.tucson.jade.examples.bookTrading).
Supposing you successfully launched the JADE platform as described above, to launch the "Book Trading" example:
operate on JADE gui to launch one "seller agent" (it.unibo.tucson.jade.examples.bookTrading.BookSellerAgent), whose name should adhere to TuCSoN agents naming rules (roughly, lowercase letters [9])
operate on JADE gui to launch at least one "buyer agent" (it.unibo.tucson.jade.examples.bookTrading.BookBuyerAgent), whose name should adhere to TuCSoN agents naming rules
You should see many prints on the command prompt, tracking what happens in the MAS [10].
NB: To showcase TuCSoN4JADE features, the example is designed to start & stop a default TuCSoN node (from the seller agent), thus:
If you want to try a setting with more sellers, comment out node starting/stopping code in seller agent's source code and start the TuCSoN node separately [11].
Author of this "how-to":
Authors of the add-on:
[1] Git standalone clients are available for any platform (e.g., SourceTree for Mac OS and Windows). Also, if you are using Eclipse IDE for developing in JADE, the EGit plugin is included in the Java Developers version of the IDE.
[2] Recommended JADE version is 4.3.2. Regarding TuCSoN and tuProlog, recommended version is 1.11.0.0209 and 2.9.1, respectively. Others (both newer and older) may work properly, but they have not been tested.
[3] Binaries available here, installation instructions covering Linux, MacOS X, Windows and Unix systems here.
[4] If you are using Eclipse IDE for developing in JADE, ANT is included: click "Window > Show View > Ant" then click "Add buildfiles" from the ANT view and select file build.xml within ant-scripts/ folder. Now expand the "TuCSoN4JADE build file" from the ANT view and finally double click on target compile to start the build process.
[5] Actually, also a t4j-noexamples.jar is built. It is the same as t4j.jar except for the explanatory example in package it.unibo.tucson.jade.examples.bookTrading, which is excluded.
[6] If you directly downloaded t4j jar or if you built it from sources without using the provided ANT script, simply adjust the given command to suit your configuration.
[7] If you do not want to use the command prompt to launch Java applications, adjust the given command to suit your configuration, e.g., if your are using Eclipse IDE: right-click on "jade.jar > Run As > Run Configurations..." then double-click on "Java Application", select "Boot - jade" as the main class, finally in the arguments tab put -gui -services it.unibo.tucson.jade.service.TucsonService as program arguments (-cp t4j.jar:../libs/tucson.jar:../libs/2p.jar:../libs/jade.jar is automatically added by Eclipse according to project's build path settings).
[8] Separator : works on Mac & Linux only, use ; on Windows.
[9] Actually, a TuCSoN agent identifier can be any valid tuProlog ground term. See tuProlog documentation, here.
[10] Because the seller agent starts the TuCSoN node, the whole MAS runs in the same JVM process, thus sharing the same standard output. If you want to better distinguish what the agents do from what the TuCSoN node does, comment out node starting/stopping code in seller agent's source code and start the TuCSoN node separately [11].
[11] E.g., in a command prompt type java -cp tucson.jar:2p.jar alice.tucson.service.TucsonNodeService. More on TuCSoN in its documentation, here.