Lightweight Bartering Grid
  P2P Grid middleware and discrete-event simulator
  Version:  see VERSION  or  src/lbg/LightweightBartergridGrid.java
  Copyright (c) 2005-2008, Cyril Briquet, parts Xavier Dalem
  Contact:  C.Briquet@ulg.ac.be

================================================================

(0) Introduction

Lightweight Bartering Grid (LBG) is a complete P2P Grid solution,
released under a Free and Open Source license (GPL2),
100% developed in Java (J2SE 5.0).

It is similar in scope and purpose to the OurGrid (http://www.ourgrid.org/)
"free-to-join P2P Grid" middleware that target Bag of Tasks applications.
LBG is strictly restricted to Java applications.
Both middlewares currently use incompatible protocols to communicate
but are good candidates for future interoperability.

Grid nodes (Peers, Resources and Users)
can run on real, networked computers, like OurGrid.

Additionally, in LBG, Grid nodes can run directly
(i.e. same implementation) within a virtualized environment
on a single (large) computer. Interactions of Grid nodes
can be simulated with a discrete-event system simulator
that is provided to study the behavior of P2P Grids.

================================================================

(1) Contents

This archive contains:
. build.xml               - Ant build file
. COPYING-*               - licensing information
. deployment/             - scripts, configuration files and examples
. HOWTO-*                 - user, administrator and developer guides
. jars/                   - libraries required to run LBG
. lbg-overview.html       - dummy file required to generate the JavaDoc
. README                  - this file
. src/                    - LBG source code
. VERSION                 - LBG version

================================================================

(2) Requirements

A J2SE 5.0 Runtime Environment is required to run LBG.
The current release may or may not run on a J2SE 6.0+ VM.

To build LBG and/or generate the JavaDoc, a J2SE 5.0 Development Kit is needed.
To automate the building process, an Apache Ant build file is provided.
To completely rebuild the project:

  ant dist

To only compile modified classes (use with caution):

  ant

The LBG middleware has been extensively tested
on standard x86 PC with 1 GB RAM running Linux,
but should also run on BSD, OSX and Windows and with less RAM.

The LBG simulator has been extensively tested
on standard x86 and IA64 PC with 512 MB RAM running Linux, OSX and Windows XP.
Take into account that a lot of RAM is needed to simulate large Grids.

The official (Sun) implementation of J2SE 5.0 has been used
to develop and test LBG.
However, LBG should be compatible with other J2SE 5.0-complying implementations.

================================================================

(3) Running the LBG middleware

A Grid of Peers, each managing zero, one or more Resources,
must be deployed before Users can submit Bags of Tasks to Peers.
At least one Peer and at least one Resource are needed on the Grid.

====

(3a) Deploying a Lightweight Bartering Grid

Users connect to Peers. Resources register themselves with their owner Peer.
Peers must first get to know other Peers, before they can barter Resources
with one another. A Peer search engine must be deployed.

It is recommended to first deploy the search engine, then Peers, then Resources.

Deployment scripts in deployment/scripts/ are available
for each type of Grid node.
Basically, a Grid node is launched as follows:

  java -cp <needed jars> lbg.middleware.Launch<Grid node type> -c <config file>

where

  <needed jars> is the a subset of the jars available in jars/
                (pending better documentation, you can include them all)
  <Grid node>   is either Peer or Resource or User or SearchEngine
  <config file> is a configuration file, structured as a properties file
                (see deployment/scripts/config/ for examples)

For Users and the search engine, there are less parameters,
which are usually given on the command line rather than
from a configuration file.

A Grid application must first be packaged into a jar and
the main class must implement the lbg.protocol.api.GridApplication interface.
A job description file (JDF) must be written (see deployment/jdf_examples/).
The JDF may then be given to the submission interface (User).

====

(3b) Network security

Multiple TCP ports must be available (not filtered) on each Grid node.

SearchEngine
  1 total
    |-- 1 to be contacted by Peers

Peer
  7 total
    |-- 1 to be contacted by other Peers
    |-- 1 to be contacted by its Resources
    |-- 1 to be contacted by its Users
    |-- 2 to serve and download files with FTP
    |-- 2 to serve and download files with BitTorrent

Resource
  3 total
    |-- 1 to be contacted by its owner Peer
    |-- 1 to download files with FTP
    |-- 1 to serve and download files with BitTorrent

User
  1 total
    |-- 1 to receive results from the Peer it is using

====

(3c) Submitting Bag of Tasks.

To immediately use the example scripts and configuration files
provided in deployment/scripts/ and deployment/scripts/config/,
the example Grid applications must first be compiled
(by default, they're not !).

  ant gridhasher
  ant hellogrid

To submit other Grid applications, you need to package all your classes
into a single jar file, with one class having a public default constructor
and implementing the lbg.protocol.api.GridApplication interface.

================================================================

(4) Running the LBG simulator

The LBG simulator simply needs a simulation description file.
To run the LBG simulator, simply type:

  java -jar jars/lightweight_bartering.jar \
       deployment/sdf_examples/scenario-example.sdf

You might want to redirect the standard output to a file
as the simulator dumps lots of statistics to the console
when a simulation is completed.

================================================================

(5) Reading the source code

The source code is indented with tabulations that are 4 characters wide.
You might want to configure your text editor accordingly.

================================================================

(6) Reading the JavaDoc

The JavaDoc can be easily generated:

  ant doc

================================================================

(7) Learning more about P2P Grids

To learn more about P2P Grids and the algorithms implemented in LBG,
you may read research papers available online
that report on research conducted at the University of Liege, Belgium.

  http://www.montefiore.ulg.ac.be/~briquet/

You may also read the following MS CS (4 years) thesis
"Implementation d'un Grid Peer-to-Peer" (in French).

  http://www.montefiore.ulg.ac.be/services/ail/tfe/tfedalem2007.pdf

================================================================

(8) Feedback

For any question, comment, suggestion, bug report, feature request, ...
please e-mail C.Briquet@ulg.ac.be

================================================================

Cyril Briquet and Xavier Dalem
March 14th, 2008
