README


### 1. Description #############################################################

This project is a Web front-end for the ProActive Scheduler and Resource
Manager REST API. It does not require the REST API to be built, but will not be
able to properly run without it.

Information about the REST API, the Scheduler and Resource Manager software
can be found at the following locations:
  - Project: http://proactive.inria.fr/
  - SCM: http://gitorious.ow2.org/ow2-proactive
  - Mailing: http://mail.ow2.org/wws/arc/proactive

This project is Open Source and distributed under the terms of the GNU AGPLv3,
a copy of which was included along with this file.



### 2. Building ################################################################

This project is written in Java using GWT <http://code.google.com/webtoolkit/>,
which means you will need a JDK to build and run it.

A note about Java versions and implementations:

Implementation    Version    Status
Sun               5          does NOT work
Sun               6          OK, preferred platform
OpenJDK           6          OK
OpenJDK           7          OK
GCJ               *          does NOT work

The only prerequisite is downloading a supported JDK (preferrably Sun Java6)
and setting JAVA_HOME to the installation folder:
  - Unix:    $ export JAVA_HOME=/path/to/jdk/
    You may also want to make this setting permanent by writing it to your
    ~/.bashrc or /etc/rc.local or equivalent.
  - Windows: > setx JAVA_HOME C:\path\to\jdk\

To build the project, use the /compile/build[.bat] script:
  - Unix:    $ cd compile
             $ ./build wars
  - Windows: > cd compile
             > build.bat wars

This will output two .war files in the dist/ directory. These files are
Web ARchives that are ready to be deployed on a Java Web Application Server.



### 3. Deploying ###############################################################

Deploying either the Scheduler or Resource Manager web portal requires a Java
Application Server.

This document will describe the procedure for Apache Tomcat 6 which can be
downloaded here: http://tomcat.apache.org/
Other versions of Apache Tomcat, and other Application Servers such as Jetty
<http://jetty.codehaus.org/jetty/> should work similarly.

Follow these steps:
  - Stop Tomcat if it was running using /bin/shutdown.[sh|bat]
  - Copy both .war files from dist/ to the webapps/ directory in the Tomcat
    installation directory.
  - Unpack both .war files, ie for the rm.war file:
    Unix:    $ cd webapps
             $ unzip rm.war -d rm
    Windows: > cd webapps
             > mkdir rm
             > cd rm
             > "%JAVA_HOME%"\bin\jar -xf ..\rm.war
  - Edit the configuration file of each application to specify the URL
    of the REST server that the application will connect to.
	  - For the Scheduler, the file is /webapps/scheduler/scheduler.conf,
        and the configuration key "sched.rest.url".
      - For the RM, the file is /webapps/rm/rm.conf, and the configuration
        key "rm.rest.url".
    ie. for the rm: "rm.rest.url = http://my.example.com:8080/rm_rest/"
    This step requires that you run the REST API server somewhere. This
    can be a remote server, but the REST API server may as well run in the
    same application server as the Web Portal.
  - Start the Tomcat server using /bin/startup.[sh|bat]
  - Check the logs in /logs/catalina.out
  - If the logs show a security exception, ie.:
      java.security.AccessControlException: access denied
    Kill tomcat, and restart it using /bin/startup.[sh|bat] -security
    to use a security manager.


### 4. Architecture ############################################################

This section describes briefly the project's architecture.
If you do not wish to understand the internals of the project, read or edit its
sourcecode, then this section is of no use to you.

Here is how the applications tiers interact with each others:

      .------.      .-----------.      |Comm layer + Platform |
      |  RM  +------. Scheduler |      +-----------+----------+
      `--+---'      `-----+-----'      |           | Java     |
         |                |            |           |          |
         |                |            |Java RPC   |          |
    .----+----.     .-----+------.     |           |          |
    | RM REST |     | Sched REST |     |           |          |
    `----+----'     `-----+------'     |           | Tomcat   |
         |                |            |           |          |
         |                |            |Java RPC   |          |
   .-----+-----.   .------+-------.    |           |          |
   | RM Portal |   | Sched Portal |    |           |          |
   `-----+-----'   `------+-------'    |           | Tomcat   |
         .................|            |           |          |
                 |                     |           |          |
           .-----+-------.             |HTTP(S)    |          |
           | Web Browser |             |           |          |
           `-------------'             |           | Any web  |
                                       |           | browser  |

In the above diagram:
  - The end user uses a Web Browser to connect to the Portal. The Portal
    displays information retrieved from the REST API through an HTTP connection.
  - The REST API retrieves information from the Scheduler or RM server using
    native ProActive Java RPC communications, and stores it locally.
    This has two effects:
      - the REST server acts as a caching layer, preventing
      the scheduler from suffering from the load of too many connected clients.
      - clients can connect through the REST API without using Java or
      ProActive and only through a simple HTTP client.
  - The Scheduler handles the job execution workflow. It is the central piece
    of the application.
  - The Resource Manager aggregates physical resources and provides them
    to the Scheduler so that it may execute tasks.


The RM and Scheduler applications are very close. They are built upon the same
architecture, use the same technologies, and even share some of the same code.

This simplified architecture diagram applies to both client-side applications:

                .------------.
                |AsyncService|
                `-----^------'
                      |network comm
                      |
                .-----v----.                .---------.
                |Controller+---------------->ModelImpl|
                `-----+----'       writes   `--+------'
         +------------+-------+                |Implements
         |!logged    XOR      |logged          |
    .----v----.            .--v-.              |  .-----.
    |LoginPage|            |Page|              +-->Model|
    `---------'            `--+-'              |  `-----'
                     +--------+-----+          |
                     |  includes    |          |  .---------------.
                  .--v--.        .--v--.       +-->EventDispatcher|
                  |View1|        |View2|          `---+-----------'
                  `--+--'        `--+--'              |
                     |              |                 |
                     |implements    |                 |
                .----v----.     .---v-----.           |
                |Listener1|     |Listener2|           |
                `----^----'     `---^-----'           |
                     +--------------+-----------------+
                                            onEvent

This client side application is written in Java and compiled to Javascript
using GWT which will allow execution in a web browser environment.
The server side application (AsyncService on the diagram) runs in native Java
in an application server, and communicates with client-initiated Ajax calls.
The server consists in a collection of servlets that communicate with the REST
API using an HTTP client.



### 5. Troubleshooting #########################################################

If you have questions regarding this document or the project, you can use the
ProActive mailing list.

If you have found a bug, you can check the project's bug tracker to either
search for open entries, or submit a new reproducible issue.

  - Mailing: http://mail.ow2.org/wws/arc/proactive
  - Tracker: https://bugs.activeeon.com/browse/PORTAL