Chapter 2. ProActive Installation

ProActive is available for download under the AGPL 3 license. ProActive requires JDK 1.5 or later to be installed on your computer. Please note that ProActive will NOT run with any version prior to 1.5 since some features introduced in JDK 1.5 are essential.

2.1. ProActive Installation Overview

2.1.1. Testing ProActive With Examples

Download and expand the ProActive archive
Set the JAVA_HOME variable to the Java distribution you want to use
If you have already a PROACTIVE_HOME and/or a PROACTIVE variable set, then unset them or set them to your new ProActive home. If you do not do that, scripts will try to use them.
Launch the scripts located in the ProActive/examples directory.

2.1.2. Developing With ProActive

Download and unzip the ProActive archive
Normally, sources have already been compiled. If not, please go to the compile directory and type build[.bat] deploy.all (build script has to be executable. If not, type chmod 744 build). To see all the possible targets, just type build[.bat].
Include in your CLASSPATH the ProActive jar file ProActive/dist/lib/ProActive.jar. Normally, only this JAR file is needed. However, it defined some required other JAR files as indexes such as ProActive/dist/lib/javassist.jar, ProActive/dist/lib/log4j.jar, ProActive/dist/lib/xercesImpl.jar, ProActive/dist/lib/fractal.jar, ProActive/dist/lib/asm-2.2.3.jar, ProActive/dist/lib/ibis-1.4.jar, ProActive/dist/lib/bouncycastle.jar, ProActive/dist/lib/servlet-api.jar, ProActive/dist/lib/jetty-*.jar and ProActive/dist/lib/virtualization-core.jar. Thus, theses files have to be placed into the same directory as ProActive.jar. It is a piece of information to keep in mind in particular if you want to move ProActive.jar toward your own lib directory. In this case, you have also to move the 7 others JAR files.
Depending on your project needs, you might need to include other libraries located in the ProActive/dist/lib directory.
Launch the JVM with a security policy file using the option -Djava.security.policy=pathToFile. A basic policy file can be found at ProActive/examples/proactive.java.policy. You can also specify a log4j configuration file with the property -Dlog4j.configuration=file:pathToFile. If a configuration file is not specified a default logger that logs on the console will be created.

The next sections details these different steps to install ProActive.

2.2. ProActive Detailed Installation Steps

2.2.1. Download And Expand The ProActive Archive

You can download the archive file (a zip or a tar.gz file) containing ProActive from the download section of the ProActive home page. You will be asked to accept the license agreement and provide a few details including your email address. You will be then redirected towards the download page.

Unzip this archive using your favorite program for uncompressing, such as 7Zip under Windows or the unzip and tar command-line utilities under most Linux/Unix systems. Uncompressing archive creates a ProActive directory and all the files contained in this archive go into this directory and its subdirectories. As already said, ProActive should be compiled. If it is not the case, you have to compile it using the build[.bat] deploy.all in the compile directory.

Here is a quick overview of the directory structure of the archive:

Directory or File	Description
`dist/lib/ProActive.jar`	ProActive bytecode that you need to include in your `CLASSPATH` in order to use ProActive
`dist/lib/ProActive_examples.jar`	Bytecode and resources of all examples included with ProActive. This jar file needs to be included in your `CLASSPATH` only when trying to run examples. All examples rely on ProActive and therefore the `ProActive.jar` file must be included in the `CLASSPATH` as well. This is done automatically by the scripts (`env.sh` on Linux/Unix and `init.bat` on Windows) driving the examples. The source code is also included in the `src` directory (see below)
`lib`	External libraries used by ProActive
`doc/built/ProActive`	ProActive documentation including a HTML version, a PDF version, the API JavaDoc... If this directory does not exist, please go to the `ProActive/compile` directory and run `build doc.ProActive.docs`. This command will create all the ProActive documentation versions. If you just want a specific version of documentation, run `build` to see all the target possibilities and choose the most appropriate one.
`examples`	Unix sh scripts and Windows bat files for running examples
`src`	The full source code of ProActive
`compile`	Scripts to compile ProActive using Ant.

Table 2.1. ProActive archive contents

2.2.2. Set the `CLASSPATH` for using ProActive to write applications

In order to use ProActive to write your own application, you need to place the dist/lib/ProActive.jar file in your CLASSPATH. As said previously, it makes references to other JAR files which have to be in the same directory as ProActive.jar. If it not the case, you have to include the following JAR files to your CLASSPATH:

dist/lib/javassist.jar - used to handle bytecode manipulation.
dist/lib/log4j.jar - logging mechanism used by ProActive.
dist/lib/xercesImpl.jar - used to parse and validate XML files, like deployment descriptors, configuration files and component files (see "XML_Descriptors", "Configuration" and "intro").
dist/lib/fractal.jar - component model used for ProActive Components (see "configuration_html_Controllers_and_interceptors_n").
dist/lib/bouncycastle.jar - used by the ProActive security framework (see "Security").
dist/lib/ibis-1.4.jar - communication library used by the ProActive components.
dist/lib/asm-2.2.3.jar - used by the ProActive components for bytecode manipulations.
dist/lib/servlet-api.jar and dist/lib/jetty-*.jar - used for dynamic class loading through the embedded Jetty server.
dist/lib/virtualization-core.jar - used by ProActive deployments on virtual infrastructures.

	Note
	You do not need to modify your `CLASSPATH` permanently if you include the entries above using a Java IDE or a shell script.

Under Linux/Unix:

Open a Linux/Unix terminal and go to your ProActive directory using the cd command. Then, set the CLASSPATH as follows:

cd [Your ProActive install directory]
PA_PATH=$(pwd)
export CLASSPATH=.:${PA_PATH}/dist/lib/ProActive_examples.jar:${PA_PATH}/dist/lib/ProActive.jar

Under Windows:

Open a Windows command terminal by executing either cmd or command in Start-> Run

Go to the ProActive installation folder by using cd and set the CLASSPATH by executing the following commands:

cd [Your ProActive install directory]
set CLASSPATH=.;%CD%\dist\lib\ProActive_examples.jar;%CD%\dist\lib\ProActive.jar;

	Note
	Keep in mind that some JAR files are needed by ProActive.jar and so, they have to be in the same directory. If not, add them to the `CLASSPATH`.

In addition to the jar files above, you may want to add the following jar files. None of them are used directly by the core functionalities of ProActive but only in part of the library. They are not needed at runtime if those specific functionalities are not used but they are needed to compile all the code.

trilead-ssh2.jar - used when tunneling with rmissh.
cryptix.jar, cog-jglobus-1.2.jar, puretls.jar, cryptix32.jar, cryptix-asn1.jar, cog-ogce.jar, cog-jglobus.jar - used to interface with Globus
fractal.jar, fractal-adl.jar - used by the Fractal components
commons-discovery.jar, saaj-api.jar, commons-logging-1.0.4.jar, jaxrpc.jar, activation.jar, wsdl4j-1.5.1.jar, mail.jar, xml-apis.jar, axis.jar, soap.jar - used by the Web Services features
bcel-5.1.jar, ibis-util-1.0.jar, colobus-0.1.jar, ibis-connect-1.0.jar, ibis-1.4.jar, bcel-5.1-fixes-1.0.jar - used by Ibis if configured as communication protocol
ajo.jar, njs_client.jar, scriptPlugin.jar, jh.jar - used when deploying to a UNICORE site.

The jar files can be found under Proactive/lib and under ProaActive/dist/lib.

2.2.3. Create a `proactive.java.policy` File To Set Permissions

See Permissions in the JavaTM 2 SDK to learn more about Java permissions. The option -Djava.security.policy=pathToFile will specify which security policy file to use within ProActive. As a first approximation, you can create a simple security policy file granting all permissions:

grant {
  permission java.security.AllPermission;

  // Reflect access private Members
  // Used by:
  //         -Unicore Process
  permission java.lang.RuntimePermission "accessDeclaredMembers";
  permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
};

	Note
	If you use the scripts provided with the distribution to run examples, an existing policy file named `proactive.java.policy` will be used by default. It is exactly the same as described above.

2.2.4. A simple `proactive-log4j` file

See for logging using the Apache log4j. The option -Dlog4j.configuration=file:pathToFile will specify which logging policy file to use within ProActive. As a first approximation, you can create a simple logging policy file:

# This file represents the log4j config file for non regression tests.
# It is given as property (in the proactive.xml) when starting nonregression tests

# The default logging level is INFO
# The root logger logs in the test.log file

log4j.rootLogger=INFO,CONSOLE
 
# If INFO is enabled Jetty is too verbose at startup
log4j.logger.org.mortbay = WARN


########### The following are existing categories in ProActive
#log4j.logger.proactive = INFO
#log4j.logger.proactive.pnp = TRACE
#log4j.logger.proactive.classloader = DEBUG
#log4j.logger.proactive.events = DEBUG
#log4j.logger.proactive.runtime = DEBUG
#log4j.logger.proactive.body = DEBUG
#log4j.logger.proactive.mop = DEBUG
#log4j.logger.proactive.groups = DEBUG
#log4j.logger.proactive.sync_call = DEBUG
#log4j.logger.proactive.deployment = DEBUG
#log4j.logger.proactive.deployment.log = DEBUG
#log4j.logger.proactive.deployment.process = DEBUG
#log4j.logger.proactive.deployment.filetransfer = DEBUG,CONSOLE
#log4j.logger.proactive.filetransfer = DEBUG
#log4j.logger.proactive.nfe = FATAL
#log4j.logger.proactive.gc = DEBUG
#log4j.logger.proactive.ft = DEBUG
#log4j.logger.proactive.ft.cic = DEBUG
#log4j.logger.proactive.ft.pml = DEBUG
#log4j.logger.proactive.communication.transport.http = DEBUG
#log4j.logger.proactive.communication.rmi = DEBUG
#log4j.logger.proactive.communication.ssh = DEBUG
#log4j.logger.proactive.communication.transport.http = DEBUG
#log4j.logger.proactive.migration = DEBUG
#log4j.logger.proactive.communication.requests = DEBUG
#log4j.logger.proactive.examples = DEBUG

#log4j.logger.proactive.components = DEBUG
#log4j.logger.proactive.components.requests = DEBUG
#log4j.logger.proactive.components.activity = DEBUG
#log4j.logger.proactive.components.bytecodegeneration = DEBUG
#log4j.logger.proactive.components.adl = DEBUG
#log4j.logger.proactive.components.gui = DEBUG

#log4j.logger.proactive.security = DEBUG
#log4j.logger.proactive.security.node = DEBUG
#log4j.logger.proactive.security.session = DEBUG
#log4j.logger.proactive.security.body = DEBUG
#log4j.logger.proactive.security.manager = DEBUG
#log4j.logger.proactive.security.request = DEBUG
#log4j.logger.proactive.security.runtime = DEBUG
#log4j.logger.proactive.security.policy = DEBUG
#log4j.logger.proactive.security.policyserver = DEBUG
#log4j.logger.proactive.security.crypto = DEBUG
#log4j.logger.proactive.security.psm = DEBUG

#log4j.logger.proactive.skeletons = DEBUG
#log4j.logger.proactive.skeletons.taskpool = DEBUG
#log4j.logger.proactive.skeletons.structure = DEBUG
#log4j.logger.proactive.skeletons.environment = DEBUG
#log4j.logger.proactive.skeletons.application = DEBUG
#log4j.logger.proactive.skeletons.diagnosis     = DEBUG
#log4j.logger.proactive.skeletons.system = DEBUG

#log4j.logger.proactive.masterworker = DEBUG
#log4j.logger.proactive.masterworker.workermanager = DEBUG
#log4j.logger.proactive.masterworker.pinger = DEBUG
#log4j.logger.proactive.masterworker.repository = DEBUG
#log4j.logger.proactive.masterworker.workers = DEBUG


#log4j.logger.proactive.configuration = DEBUG
#log4j.logger.proactive.remoteobject = DEBUG

#log4j.logger.proactive.jmx = DEBUG
#log4j.logger.proactive.jmx.mbean = DEBUG
#log4j.logger.proactive.jmx.notification = DEBUG

#log4j.logger.proactive.webservices = DEBUG

################ Appenders ####################
#
# Appender output can be configured by using a pattern layout
# See: http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/PatternLayout.html
#
#   - %c the category of the logging event
#   - %d the date
#   - %m he application supplied message
#   - %n the platform dependent line separator character or characters
#   - %p the priority of the logging event
#   - %t the name of the thread that generated the logging event
#   - %X{hostname}         the hostname 
#   - %X{id@hostname}      the VMID and the hostname 
#   - %X{shortid@hostname} the short VMID and the hostname (a collision can occur between two shortids, you should use id@hostname) 
#   - %X{runtime}          the ProActive runtime url (does not work very well since a different MDC is associated to each thread)


# CONSOLE appender is used by default
log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
log4j.appender.CONSOLE.layout.ConversionPattern=%X{shortid@hostname} - [%d %p %20.20c{2}] %m%n

# Appender FILE writes to the file "tests.log".
# This file is recreated a file for each run
log4j.appender.FILE=org.apache.log4j.FileAppender
log4j.appender.FILE.File=tests.log
log4j.appender.FILE.Append=false
log4j.appender.FILE.layout=org.apache.log4j.PatternLayout
log4j.appender.FILE.layout.ConversionPattern=%5p [%t]: %m%n

	Note
	If you use the scripts provided with the distribution to run the examples, an existing log4j file named `proactive-log4j` will be used by default.

2.2.5. Run A Few Examples For Testing

You can try to run the test applications provided with ProActive. Each example comes with a script to launch the application. This script is located in ProActive/examples . All the example code sources can be found in the directory ProActive/src/Examples/org/objectweb/proactive/examples/.

2.2.5.1. Reader/Writer

This example is the ProActive version of the Readers/Writers canonical problem. To illustrate the ease-of-use of the ProActive model, different synchronization policies can be applied without even stopping the application. This example is based on a easy to use Swing GUI.

script: readers.sh or readers.bat
source: examples/readers

2.2.5.2. The Dining Philosophers

This example is one possible implementation of the well-known Dining Philosophers synchronization problem. This example is based on a easy to use Swing GUI.

script: philosophers.sh or philosophers.bat
source: examples/philosophers

2.2.5.3. The N-Body Simulation

This example can be used later on as a deployment example for several machines, and also for the fault-tolerance features.

script: nbody.sh or nbody.bat
source: examples/nbody

Prev	Up	Next
Chapter 1. ProActive Overview	Table of Contents	Chapter 3. ProActive Troubleshooting