This document is targeted at the developers trying to quickly start developing and using DIXI. Those that want to compile and use the software as-is are kindly redirected to the DIXI.txt document.

Contents of this document:

1. Prerequisites
2. Compiling the code from command line
3. Testing the code from command line
3. Importing the source code into Eclipse
4. Defining the user library XOSLIBS
5. Running XOSd
6. Running the XConsole
7. Deploying VOPS using ant
	7.1 Source
	7.2 Binary
	7.3 Test using Support/runscript/maintenance scripts
8. Troubleshooting

The following are instructions on how to run the key components of the AEM package and how to import the AEM projects into Eclipse to compile and run the framework. Please refer to README for further details.

1. Prerequisites
================

 * Sun Java JDK >= 1.6 
 * Eclipse IDE >= 3.2.0 (for running from Eclipse).
 
2. Compiling the code from command line
=======================================

 * To compile the projects in the terminal shell, simply issue

	$ ant

 * To produce the .jar libraries, e.g. needed for importing into other projects that depend on the classes within the project, issue

	$ ant build-jars

 * To produce individual .jar libraries, use one (or more) of the following ant targets:
	* build-main-jar
	* build-main-services-jar
	* build-security-vops-jar
	* build-rca-server-jar
	* build-rca-node-jar
	* build-aem-jar
	* build-xati-jar
	* build-aem-vnode-jar

 * For testing the code by using the deploy folder (please refer to 3. Testing the code from command line for further instructions), prepare the test environment into Support/deploy by issuing

	$ ant deploy

 * If your development environment does not need to use the C libraries related with JNI and AEM's ExecMng, it is possible to skip compilation of the C code:
	* To skip the compilation of C code for the invocation of ant only, provide a definition of the skip-build-c parameter:

		$ ant -Dskip-build-c=yes

	* To permanently implicitely enable skipping the building of the C code, create a non-empty file named skip-build-c:

		$ echo yes > skip-build-c

	* To re-enable the building of the C code, simply remove the skip-build-d file.

3. Testing the code from command line
=====================================

 * In the terminal shell, invoke the building and deploying of the compiled binaries:

	$ ant deploy

 * Change directory to Support/deploy which is the target of the deploy folder.
 
	 $ cd Support/deploy/

 * Start the XtreemOS service daemon (xosd):

	 $ ./xosd.sh

	* Note: the daemon will attempt to access configuration in /etc/xos/config. To use a different configuration folder, use the -C parameter. For instance, to have the xosd put and use the configuration files in the deploy folder, issue the following:

		$ ./xosd.sh -C .
	 
 * Open another terminal shell window, change to Support/deploy and run the client (xconsonsole);
 
	 $ cd Support/runscript/
	 $ ./xconsole_dixi.sh
 
 * In the XConsole, one can now execute commands like listing all nodes:
 
 	$ xrs -a

 * To connect another node:
	* repeat the first step (calling ./xosd.sh with, optionally, the -C switch) on another node that is on the same LAN subnet as the first one,
	* press Ctrl+C to stop the xosd,
	* in a text editor, open XOSdConfig.conf and edit the line containing rootaddress.host to point to the address of the first node,
	* re-run the ./xosd.sh.

 * To stop the xosd, perform one of the following:
	* switch to the shell running xosd and press Ctrl+C, or
	* from the client's shell run ./xosdkill.sh

 * Note that in the XtreemOS Linux installed environment, the following transformations occur:
	* the *.sh commands are renamed to *, e.g., ./rca_list_pending.sh is installed as rca_list_pending
	* the xosd does not need to be run as a shell command. Instead, the use of "service xosd start" as root is recommended.

4. Importing the source code into Eclipse
=========================================

 * Open Eclipse. 
 * Click Window -> Open perspective -> Other. The Open perspective window is opened. 
 * Select SVN Repository Exploring and click OK. 
 * On the left side of the perspective, you should see the SVN Repository tab. 
 * Right-click somewhere inside it, and select New -> Repository Location. 
 * Set up the connection to your SVN repository and wait for the view in the SVN Repository tab to be updated. 
 * Expand the location of your repository, and select all of the projects there. 
 * Right-click on them, and select Checkout. 
 * Click Next, if you wish, set an alternate location and click Finish.
 
5. Defining the user library XOSLIBS
====================================

The project will not compile yet because it is missing the path to the libraries. We provide them through a user library XOSLIBS.

 * Right-click on one of the newly checked-out projects (e.g., XUtilities) and select Properties. The Properties window is opened. 
 * Select Java build path, then the Libraries tab. 
 * Click Add Library. 
 * Select User Library and click Next. 
 * If the library XOSLIBS doesn't exist in the list yet, click User libraries, New enter XOSLIBS and click OK. 
 * Select the XOSLIBS library and click Add JARs. 
 * Navigate to Support/libs directory, and select all JARs there. Click OK. 
 * Click OK, then Finish.
 
6. Running XOSd
===============

To start the XOS daemon, you should run the main method in XOSd.java (project XOSd). You also need to provide the location of the configuration files and the base folder of the runtime environment as an argument. The base folder is the folder where all the projects reside. The configuration files go by default into /etc/xos/config (usually requiring the folder to exist, and root privileges). In the development environment, they can reside in the XOSd project folder. Just enter the following: 

-C /home/matej/Documents/Projekti/XtreemOS/xOSV2 -

into the Arguments window. If this is your first run and/or the file does not exist, it will be created. You can edit it later and set the options to your liking, for example, to use SSL and to set the certificate location. 

The XOSd folder contains a log4.properties file. To enable its usage, the run configuration needs to have the folder in the class path. Switch to the Classpath tab of the Run Configurations window, select User Entries, click Advanced..., click Add Folders and OK, and select XOSd project, then click OK.

To run the XOS daemon from command line, please see the runningDaemon.txt file, in the Support/Documentation directory.

Next steps:
 * Edit XOSdConfig.conf to enable services needed (ExecMng can usually be disabled, as
   it requires certain runtime libraries to be present on the system).

7. Running the XConsole
=======================
To run the XConsole, create another run cofiguration for project XATI, main class eu.xtreemos.xati.test.XATItest and provide -c as an argument.
 
8. Deploying VOPS using ant
===========================

In the root of the project resides ant file - build.xml. There exist three rules
regarding VOPS deployment:

	o build-vops-jar (depends on build) 
 	o deploy-vops-src
	o deploy-vops-bin

Former packages binaries needed by VOPS to run as a standalone service. Jar file
"vops.jar" is created under root directory. This package is needed when deploying
VOPS binary.

	8.1 Source
	==========

The second rule (deploy-vops-src) creates new directory containing source code for 
developing VOPS as standalone service. Default location for deploying VOPS source
is ./WP35-VOPS but can be changed manually by changing next line inside build.xml
ant file:

	<property name="VOPSSrcDestination.location" value="./WP35-VOPS" />

value can be arbitrary directory. Directory structure is as follows:

./CDAMng - cda service (VOPS depends on several classes, this will change)
./Daemons - service has to be included, XOSd depends on this service
./VOPS - main source code of the VOPS
./Support - dependencies 
./XOS_SEDA - communication libraries (part of DIXI)
./XServices - services' definitions (part of DIXI)
./XOSd - DIXI (part of DIXI)
./XOSdCommon common classes used by services
./XUtilities common utilities


	8.2 Binary
	==========

The third rule creates deployvops directory under Support directory where all
files needed by the VOPS are copied:
	o Support/libs - dependencies
	o Support/runscript - scripts for running vops
	o VOPS/files - contains VOPS storage

Structure under Support/deployvops is created as follows:

.
./libs
./log4j.properties
./VOPS
./VOPS/files
./vops.jar
./xosd.sh

It is high likely that when trying to run xosd.sh for the first time, you will 
get an exception message. If not already there, new files will be created. 

./XOSdConfig.conf
./VOPSConfig.conf

Edit them and see that they resemble the following code:

	o XOSdConfig.conf

#Properties File for the client application
#Mon Apr 07 14:47:04 CEST 2008
rootaddress.xmlport=55000
rootaddress.host=/192.168.0.233
useSSL=false
rootaddress.port=60000
services.size=11
services.0=eu.xtreemos.xosd.vops.service.VOPSHandler
services.1=eu.xtreemos.xosd.daemon.DaemonGlobal
rootaddress.externalAddress=/192.168.0.233
certificateLocation=../test_keystore.cert
xosdRootDir=..

xosdRootDir should point to directory where vops.jar resides.

	o VOPSConfig.conf

#Properties File for the client application
#Mon Apr 07 14:47:04 CEST 2008
globalVOPS.port=60000
globalVOPS.host=/192.168.0.233
policyStorage=/home/ales/eclipse-workspaces/AEM_GFORGE/trunk/Support/deployvops/VOPS/files/policy/test3

Make shure that policyStorage point to location on your policy storage (where
XACML files are stored).

If everything has been set up successfully, your server should start normally when 
running xosd.sh. 


	8.3 Test using Support/runscript/maintenance scripts
	====================================================

When residing in the root of the projects of AEM, someone can issue next commands:
	$ ant
	$ ant build-jar
	$ ant deploy
To test the functions provided by the VOPS, navigate to Support/deploy directory. Run the XOSd by issuing 
	$ ./xosd.sh
command. Open new terminal window and navigate to the same directory as before. Check that policy storage
points to the junit_test_storage directory (taken from VOPSConfig.conf):

#Properties File for the client application
#Mon Apr 28 14:19:01 CEST 2008
globalVOPS.port=60000
globalVOPS.host=/192.168.0.233
# This line should point to your policy storage
policyStorage=/home/ales/eclipse-workspaces/AEM_GFORGE/trunk/Support/deploy/VOPS/files/policy/junit_test_storage

Now execute 
	$ ./vops.sh

This command starts eu.xtreemos.xati.test.XATItest with the testVOPS() method. Some of the methods provided by
VOPS service are tested and these can be used as reference point to create your own application using functions
provided by the service. Note that test storage, request and policies were predefined. 

9. Troubleshooting
==================

If the projects still would not compile, it is very likely that the Eclipse is not set to Java 6.0 compliance, and the JRE is set to other than 1.6.

To change the compiler:

 * Click Window -> Preferences. The Workspace preferences window is opened. 
 * From the structure on the left, select Java -> Compiler. 
 * Make sure that in JDK compliance dropdown on the right, 6.0 is selected. If not, select it. 
 * Click OK.
 
To change the JRE:

 * Right-click on any of the newly checked-out projects and select Properties. The Properties window is opened. 
 * Select Java build path, then the Libraries tab. 
 * Make sure that the first entry in the window is the 1.6 JRE, not the 1.4.x. 
 * If not, select it and click Edit. Edit library window is opened. 
 * Select Alternate JRE and click Installed JREs. 
 * Click Add. 
 * Click Browse and navigate to the 1.6 JRE installation directory, then click OK. 
 * Click OK, Finish and OK. 
 * Clean and rebuild your workspace.
 
If there are still projects that would not compile:
 * Try to refresh the whole workspace:
    * fold all projects so that only project names appear in the Package Explorer,
    * click on the topmost project to select it,
    * scroll to the bottom of the Package Explorer list,
    * Shift-click the bottommost project to select all the projects,
    * right-click the selection and select Refresh (or press F5).
 * Try to rebuild the project:
    * click Project / Clean..., 
    * select Clean all projects,
    * check Start a build immediately (the option only appears if no Project / Build Automatically is not selected),
    * click OK.
 * Eclipse may take a while to compile all the projects. 
 * Sometimes, for unknown reasons, Eclipse fails to load the jar list of the user libraries in some of the projects. If a project is marked with errors, 
    * click the arrow next to the project's name in the Package Explorer to open the project's contents,
    * one of the entries in the project's list is the XOSLIBS library. The entry should have an arrow for listing the jar files associated with the library. If the arrow is not there or if the entry shows empty contents, then
    	* right-click the project's name,
    	* select Close Project,
    	* right-click the project's name again,
    	* select Open Project,
    	* have the workspace compile (either wait for the compilation to finish if set to Build Automatically, or select Project / Build All).
 
