VV2 prototype

[Robert Olson]

Here's the new README for the VV2 prototype code. There's an installed 
version on the green linux machines (tested on terra and shakey).

-----------------------------------------------------------------

AG 2.0 Virtual Venues Prototype implementation

Included in this subtree is the Virtual Venue prototype implementation. It 
comprises two
components: the Venue server and a client application.

The directory structure is as follows:

AG/apps/venueclient	Venues client application
AG/services/venue	Venues server code
AG/services/docking	Workspace Docking services code

Prerequisites
-------------

The venues code assumes Python 2.2 and a handful of other
packages. For Windows, you can find the Python distribution at

	  http://www.python.org/2.2.1/

In MCS, green Linux machines should work for this as well using the
stock python 2.2 installation.

We also use the Python Cryptography Toolkit:

	http://www.amk.ca/python/code/crypto.html

A version of this compiled for Windows is available at

	http://www-unix.mcs.anl.gov/~olson/AG/Software/NT/pycrypto-1.9a4.win32-py2.2.exe

The classad library is also required. A windows installation is
available here:

	http://www-unix.mcs.anl.gov/~olson/AG/Software/NT/classad-1.01.win32-py2.2.exe

The sources for this are in the /home/FuturesLab/Software/CVSMaster
archive, in module python-classad. The classad library itself is at

	http://www.cs.wisc.edu/condor/classad/

Apparently the 0.9.3 version has changed memory management such that
the python bindings crash; the code works fine with the 0.9.2 version.

To run a server you will need the ZODB 3.1b1 module installed:

	http://www.zope.org/Products/StandaloneZODB


To run the client you will need wxPython installed:

	http://www.wxpython.org/

A windows binary is available there.

Installed code
--------------

I have installed (well, checked out - `setup.py install' not run) a
copy of this code, as well as all of the prerequisite libraries, in
~olson/AG/VVPython on terra (and other green linux boxes of the same
general sort). If you

	source /homes/olson/AG/VVPython/setenv

and use /homes/olson/AG/VVPython as <base> below, you should be able
to run the client and server code. To run the server, you'll have to
be in a directory that you can write to, and run:

	python /home/olson/AG/VVPython/VV2/vv_core/AG/services/venue/VenueServer.py

This will create the persistent database files in the current directory.

Running the code
----------------

Due to a perhaps unfortunate decision in the package layout for the python 
code (*),
it is required to set an additional environment variable to enable the
use of the VV code when running out of the source tree (as opposed to
running from code installed using 'python setup.py install').

The following assumes that the VV2 CVS tree is unpacked in directory
<base>.

Set the following environment variables. tcsh/csh:

     setenv PYTHONPATH <base>/VV2/vv_core
     setenv AGVV_SERVICE_CORE <base>/VV2/service_core

bash:

     export PYTHONPATH=<base>/VV2/vv_core
     export AGVV_SERVICE_CORE=<base>/VV2/service_core

win32:

     set PYTHONPATH=<base>/VV2/vv_core
     set AGVV_SERVICE_CORE=<base>/VV2/service_core

Starting a Server
-----------------

Go to the directory <base>/VV2/vv_core/AG/services/venue.

You must first bootstrap the persistent venue object database. Run
this:

	python bootstrap.py

Then to start the server run this:

	python VenueServer.py

It will print out the service addresses it is listening on.

Starting the Client
-------------------

Go to the directory <base>/VV2/vv_core/AG/apps/venueclient. Run this:

	python vclient.py <url-to-service>

where <url-to-service> is the address that was printed when the server
started.

------------------

(*) The design of the python packaging is that all the AG code is under a 
python
packaging hierarchy rooted at package AG, with services living under
AG.services, applications under AG.apps, etc. The problem is that the
service_core distribution, containing the base-level service code, is
package AG.services.xmlrpc. The Venue services code is
AG.services.venue. If the PYTHONPATH is set to
<base>/VV2/service_core:<base>/VV2/vv_core, which would seem to make
sense, imports fail. This is because if, for example,
AG.services.xmlrpc.Server is imported, Python will import AG,
AG.services, and AG.services.xmlrpc first. When it imports
AG.services, it pulls in teh version from
<base>/VV2/service_core/AG/services. However, if you try to then
import AG.services.venue.client, for instance, it will see that
AG.services is already imported, won't import it again, but will see
that there isn't a venue subpackage.

The solution to this is to place the vv_core directory in the
PYTHONPATH, and use the __path__ mechanism (see
http://www.python.org/doc/essays/packages.html) to patch in the path
to the services core. The following code  in vv_core/
AG/services/__init__.py does exactly this:

	other = os.getenv("AGVV_SERVICE_CORE")

	if other is not None:
	    print "Appending ", other
	    __path__.append(os.path.join(os.path.normpath(other), 
os.path.normpath("AG/services")))
	    print __path__