APPIA README.txt

Last Updated: 2011/01/04

Copyright (C) 2006-2007 University of Lisboa Copyright (C) 2008-2011 University of Lisboa / INESC-ID

Appia is a layered communication framework implemented in Java and providing extended configuration and programming possibilities. Appia contains protocols that provide group communication facilities.

This file describes how to install and use the Appia framework.

CONTENTS:

(1) REQUIREMENTS
(2) LICENSE
(3) CHOOSING THE APPIA DOWNLOAD
(4) INSTALLING APPIA
(5) RUNNING THE APPIA DEMO APPLICATIONS
(6) ADDITIONAL DOCUMENTATION

(1) REQUIREMENTS

Appia is written in Java thus it requires a java virtual machine installed in your computer. Appia currently requires the JDK version 1.5 or higher. Installing/Upgrading java is beyond the scope of this document. See http://java.sun.com/ for more info about this subject.

Appia was tested under Linux Ubuntu, Windows XP and MacOS X.

Appia requires at most 31Mb of disk space (space required if you compile all the source code, build the jars and the documentation).

(2) LICENSE

Since version 3.0, Appia is distributed under the Apache License version 2.0 (ALv2). More details can be found in the LICENSE file and in the web page: http://www.apache.org/licenses/LICENSE-2.0

The previous versions of Appia where released under the GNU Lesser General Public License (LGPL).

(3) CHOOSING THE APPIA DOWNLOAD

• Source code vs Binary code only

There are two packages that can be downloaded from the SourceForge.Net site, where Appia is currently hosted: Source distribution and Binary distribution. The source distribution is advisable as you can take a look at the Appia source code and learn how to program with Appia by understanding the provided examples. If you want to use Appia as a black box, you can download the binary version that provides the Appia jar file and the library dependencies.

• Appia source distribution

The Appia source distribution contains the source code, the libraries that are needed by Appia, a Makefile, an Apache Ant file, this Readme file, the License file and the changes log. It includes also some script files to run applications. One of these applications is the Gossip service, needed to form groups when Multicast is not available on the network.

• Appia binary distribution

The Appia binary distribution contains the Appia jar files, the libraries that are needed by Appia, and the Readme, License and changes files. It includes also some script files to run applications.

• Appia Documentation

The documentation files generated by javadoc. This file should also be download and unpacked into your hard drive, as it provides a fast reference to the Appia API.

(4) INSTALLING APPIA

The Appia installation depends on the downloaded distribution. There are two distributions of Appia: Source distribution and Binary distribution.

If you choose the binary distribution, just unzip the files and add all jar files into your CLASSPATH environment variable. Add also the bin directory to your PATH environment variable. This should be enough to use Appia.

If you choose the source distribution, you will need to compile Appia before using it. Appia is compiled using Apache Ant. For information about Apache Ant, see http://ant.apache.org. The apache ant file have the following tags:

• dist (default): creates an Appia distribution. Builds everything except the documentation;
• build-core: compiles the source code of the Appia core;
• build-groupcomm: compiles all the protocols that are related to group communication;
• build-test: compiles all the test code;
• build-all: compiles all the source code;
• core-jar: creates a jar file with the core classes;
• groupcomm-jar: creates a jar file with the group communication protocols;
• tests-jar: creates a jar file with the test protocols;
• jars: creates all the jar files;
• clean: removes all files generated by the script;
• doc: compiles the java documentation from the source code;

To install Appia using the source distribution, make the following steps:

1 - Compile the source code and build the Appia jar file running the following command:

 $ ant

this will compile the source and create the jar files. All the needed libraries are placed in the "dist" directory.

2 - Add all the jar files that are placed in the "dist" directory in the CLASSPATH environment variable. Add the bin directory to the PATH environment variable. The way to do this depends on the operating system that you use.

(5) RUNNING THE APPIA DEMO APPLICATIONS

The applications that use the Group Communication support offered by Appia require the operation of a Gossip server, when not using IP-Multicast for communication. By default the communication uses point-to-point UDP/IP. The "gossip" package contains a Gossip Server that can be started using the following command:

 On Linux or MacOS X    $ gossipServer.sh -port 10000
   or
 On Windows             $ gossipServer.bat -port 10000

The gossip server can be replicated by running multiple instances on different machines.

The Appia distribution comes with a set of demo applications. The main demo applications are:

• Appl - Uses Group Communication to create a group of communicating processes. To get the available options execute "java net.sf.appia.demo.Appl -help" After starting it type "help" to get the available commands. Example (see previous paragraph for how to start the gossip server): $ java net.sf.appia.demo.Appl -gossip :"

• Perf - Provides Appia Performance tests.

Note: These test application will soon be replaced by updated vaersions that use the jGCS interface instead of behaving as a protocol.

(6) ADDITIONAL DOCUMENTATION

For additional documentation, tutorials and mailing lists, please see the Appia website at:

• http://appia.di.fc.ul.pt