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 <gossip server host>:<gossip server port>"

 - 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