HTTP Protocol VIM
--------------------
2009-07-16

CAUTION: The contents of this document and software item (HTTP Protocol VIM) are subject to 
change. 

Description
-----------
The HTTP Protocol VIM is a prototype demonstrating how to VIMs may be "stacked" and providing 
remote access via the HTTP protocol. Stacking VIMs is an architectural feature of the SNIA XAM
API, and is allowable because the VIM API is standardized within the SNIA XAM API specification.

Stacking VIMs allows systems to be configured with functionality which may not be supplied 
a storage vendor's VIM. Examples of added functionality may include; storage federation, 
compression, encryption, etc. The HTTP VIM provides remote access to VIMs, via HTTP, which
may otherwise be unable to do so. Currently the SNIA XAM SDK contains a reference VIM which 
provides correct behavior. but is unable to operate over networks. The HTTP Protocol VIM 
allows an application to use the Reference VIM across a network link.

The HTTP Protocol VIM is contained in two parts. The upper, or client, half is a traditional 
VIM implementation which provides connectivity to the XAM Library. The client VIM portion 
translates all XAM API method calls into HTTP operations, and sends them to the HTTP Protocol 
VIM Server. The HTTP Protocol VIM Server creates a local instance of an arbitrary VIM and 
relays HTTP VIM method calls to the VIM. 

The HTTP Protocol VIM Server is written in the Java (1.5) programming language, and can host any 
VIM which has also been written in the Java language. Currently the HTTP Protocol VIM Server can 
not host VIMs written in other languages.

This release of the HTTP Protocol VIM also supplies a Java CLient HTTP VIM which will work with 
this server. The C XAM Library also supplies functionality for working with the HTTP Protocol
VIM Server. 

Warnings and Cautions
-----------------------
The HTTP Protocol VIM should be considered to be a prototype and technology demonstration. It has
not been engineered for performance, throughput scaling, or security. The HTTP Protocol VIM can 
function as a development tool, but should not be deployed as part of a shipping product.

This protocol and VIM server do not currently support HTTPS. The only security available is the 
authentication provided by the target XSystem, and the configured legal XRI list in startup.properties. 
There is no security provided on XObject handles and it is possible for clients to guess new 
handle values and obtain access to objects which they may not otherwise have access to.

Applications should close unused XObject instances when they are no longer used. Doing so frees up
needed resources in the HTTP Protocol VIM Server. 

Functionality
-------------
All specified SNIA XAM specified methods are supported for these objects:
	* XSystem
	* XSet
	* XStream
	* XIterator
	* XAsync
	
Note that some methods, although specified by the SNIA XAM specification, are not supported by
Reference VIM, and have not been fully tested (e.g. XSystem.openXStream).

Configuration File
--------------------
The HTTP VIM Server configuration files must be located in the run time "base" directory, 
the code looks up the files using the "." directory for the file named "startup.properties".
The configuration file is a standard XAM Configuration format file which allows you to 
adjust the following:

- Server address - identifies the host ip address to use, the port and the 
  server version. The default supplied is 127.0.0.1, which limits connections 
  to those being sent to 127.0.0.1. If you wish to use an external interface,
  this value must change to match the IP address of your external interface.
  
- Configured VIMs - lists the VIM classes and VIM stacks supported for the server.

Here is an example startup.properties file:
     .org.snia.xam.http.server.host=127.0.0.1
     xam_int..org.snia.xam.http.server.port=9923
     .org.snia.xam.http.server.version=1.0
     .org.snia.xam.vim.alias.Remote=dummyVIM|SNIA_Reference_VIM
     .org.snia.xam.vim.alias.SNIA_Reference_VIM=org.snia.xam.vim.reference.ReferenceVIM
      xam_int..xam.log.level=3
      xam_int..xam.log.max.size=1024


Two other configuration files are also present in the directory.
- handlers.properties - a list of handlers identified by name followed by the 
  class that implements them. This file must not be modified. It will be integrated
  into the build in a later release.
  
- HTTPTestClient.config - This XAM configuration file is used by the unit test 
  program and its instance of the XAM Library. You application will use a different one.

Required Runtime Libraries
--------------------------
The following external jar file libraries must be retrieved and placed in the HTTP_Protocol_VIM/lib directory:

- concurrent.jar   - public thread library often used for thread pools and such. 
                     http://g.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html
                     
- jetty04.2.27.jar - Jetty Web Server  
                     http://jetty.mortbay.org/jetty/
                     
- servelet.jar     - Java Servelet framework
                     http://java.sun.com

Building
--------------

This project requires Java 5 (or later) and the "ant" build tool (http://ant.apache.org/). 

After retrieving the required library files, and ensuring that Java and ant are installed
you may begin building the HTTP Protocol VIM Server.

1) Build the Java XAM Java Interfaces by executing "ant deliverables" in
   the Java XAM Interfaces directory.
   
2) Build the Java XAM Library by executing "ant deliverables" in the
   Java XAM Library directory.
   
3) Build the Reference VIM by executing "ant deliverables" in the
   Java Reference VIM directory.
   
4) Build the HTTP server by executing "ant" in the 
   HTTP Protocol VIM directory.
   
Ant Tasks:

ant        - Will build the Isolation VIM jar and place the resulting jar file
             in ./deliverables
ant clean  - Will clean up and remove all generated files
ant docs   - Will build the associated Java docs 
ant server - executes a default configuration with the Reference VIM (using /tmp for storage).
ant test   - executes unit tests against a currently running server.

Running Unit Tests
------------------
After building you may run the unit tests to verify the HTTP VIM Server. To do so, 
you will need two command line shells. In the first, start the default server:

	ant server

This will produce a listing of log output at the server registers handlers for each
VIM method. Successful start up of the server will conclude with the lines similar to:

     [java] 11:39:00.942 EVENT  Started SocketListener on 127.0.0.1:9923
     [java] 11:39:00.942 EVENT  Started org.mortbay.http.HttpServer@6d75

In the second command shell, execute the unit tests with the command:

	ant test
	
Successful completion of the unit tests will produce output similar to:

     [java] .computer.name.local File System
     [java] ................................
     [java] Time: 46.491
     [java] 
     [java] OK (33 tests)
     [java] 


Startup
-------
- Ensure all of the runtime libraries are in your classpath
- Ensure all of the properties files are set up properly and in the "current"
  directory
- A default configuration is available and will allow you to run the server, 
  configured for the Reference VIM by executing "ant server" within the
  HTTP Protocol VIM directory.
  
Using the Protocol VIM from your application
--------------------------------------------
Add the protocol VIM jar file (Isolation_VIM_Java.jar) to your classpath.

Use an XRI pointing to the HTTP Protocol VIM machine, such as:
	snia-xam://Remote!localhost?targetServer.ipAddress=127.0.0.1&targetServer.port=9923
	
NOTE: The host and VIM portion of the XRI are not interpreted by the HTTP Protocol VIM. In order to 
      connect to the HTTP Protocol VIM, you match add the targetServer.host and port arguments to 
      your XRI. 
      
You must include a VIM alias to cause "Remote" to map to the HTTP Protocol VIM Client name. 
For example, the unit test client uses the following configuration item in its config file:
    .xam.config.vim.alias.Remote=org.snia.xam.vim.http.client.VIM
    
The server should alias "Remote" to point to the actual VIM to be instantiated. The vimname supplied in the XRI
argument will be translated using the alias mechanism in the server.properties file.

If you wish, you can change the VIM name mapping contained in the file startup.properties. This 
allows your application to use any appropriate VIM or system names. 

Java VIM Requirements for Use by HTTP VIM Server
-----------------------------------------------------
- public, no parameter constructor
- implements the SNIA Java Bindings XAM Library as top level object
- no "proprietary" method implementations
- implements XAM operations appropriately (these will pass through the
  http vim)

References
----------
A complete description of the HTTP Protocol used is included in the XAM SDK User's Guide. 