
***************************************************************
  XAM SDK JAVA Reference VIM README MayWorkingDraft_2009
***************************************************************

=================
Table of Contents
=================

 1. Deliverables
      - Java Reference VIM
      - Summary of Features
      - API Methods Supported
 
 2. Java_Reference_VIM SDK Directory Structure

 3. Reference VIM Repository (Backing Store)
      - Default Repository Location
      - Directories and Files Created
      - Files created for a persisted XSet
      - Temp files created
      - Specifying a Different Reference VIM Repository Location
      - Maintaining the Repository

 4. Build Instructions
      - Required Dependencies
      - PATH requirements
      - Other requirements
      - Supported Platforms
      - Building with ant

 5. XAM Reference VIM and Library Configuration and Operation Information
 	5.1 Basic configuration
 	5.2 User configuration
 	5.3 Autodelete configuration
 	5.4 Autodelete and Shred policies
 	5.5 Retention Policies
 	5.6 Import Processing
 	5.7 Asynchronous Methods
 	5.8 Reference VIM Logging
 	5.9 Summary of Configuration Properties
 	5.10 Scalability

 6. Building and Running the Client Example
      - Building and running the example using ant
      - Building and running the example from the command line
      - Example output

 7. Reference VIM XUID Helper Programs

 8. Building and Running Tests
      - Building and Running Tests Using Ant

===============
1. Deliverables
===============

  Java Reference VIM:

    This code drop for the Reference VIM consists of the completion of previously 
    missing functionality. It also contains bug fixes and updates for the errata 
    corrections targeted for the 1.0.1 version of the XAM specification. 
    In addition a client example program and simple import/export tools have been
    added. See the release notes for a list of bugs fixed 
    in this release.
  
    Summary of Features:
     - For the reference implementation the XSets are persisted as xml files. 
       By default the directory used as the repository is defined by java.io.tmpdir.
       The xml file is named XSet_<XUID>.xml. Any XStreams persisted for the XSet
       will be in a directory name XSet_<XUID>.

     - Ability to specify a different repository location
       See "Specifying a Different Reference VIM Repository Location" under 
       the section titled "Reference VIM Repository (Backing Store)" for more 
       information.

    - Support for anonymous and plain authentication. However no authorization
      level checking. When used without additional configuration, the username 
      and password are hardcoded to "testuser" and "testpasswd" respectively. 
      The ReferenceVIM may optionally be configured to use an external file 
      containing cleartext usernames and passwords. This provides applications 
      the ability to experience access restrictions, such as may be present in 
      a production system.

    - Support for single user mode. Multi-threaded applications and multiple 
      clients have not been tested and will not work as specified in the spec.

    - Support for the XAM specified retention model. The Reference VIM supports
      a minimal set of retention policies. These policies are intended to 
      give programmers experience in using retention policies. Users should
      not expect that these policies will be available on other XAM storage 
      systems.

    - Support for setting auto delete and shred values and policies. 

    - Basic job support, only support for XAM Query jobs. 
      Can submit and halt jobs. Can commit XSets that define a job before or
      after running the job. Commit of a XSet with a running job is NOT
      supported.
      
    - Complete support for XAM Level 1 as well as XAM Level 2.
      The Reference VIM implements query using two important technologies. The level 1 query is 
      implemented using Java DB, which is present in Java 6. Users of Java 5 may download Derby DB 
      from the Apache project and put the Derby jar file in the classpath. 
   
      Level 2 query is implemented using the Lucene full text search engine. Users wishing to utilize 
      the textual search capabilities of the Reference VIM must download the Lucene core jar file and 
      add it to the class path. If Lucene is not in the classpath, the Reference VIM indicates that 
      level 2 functionality is not supported, by setting the appropriate property in the XSystem instance.
      This functionality has been tested with Lucene 1.9 and Lucene 2.4.1. The Reference VIM only supports
      this functionality on XStreams of type "text/plain". Level 2 functionality is implemented using 
      the Lucene StandardAnalyzer which provides case insensitive searches.
      
      If you are adding support for level 2 queries to an existing XSytem, you may wish to delete the
      ReferenceVimDB directory before starting the Reference VIM. This will cause existing XSets to be
      indexed for level 2 functionality.
      
    - Support for exporting and importing of XSets including those containing streams.
      However importing XSets with retention information is not guaranteed to work 
      when importing XSets from a different VIM implementation. The Reference VIM will
      validate imported XSets, according to the SNIA XAM Specification, and reject those
      XSets which contain retention settings unable to be honored by the Reference VIM.
 
    - Example client program that uses the reference VIM (ReferenceXSetClient.java).
      Program demonstrates how a client would configure and use the Reference
      VIM.

    API methods supported:
    VIM: createXSystem
    XSystem: connect, authenticate, abandon, close, createXSet, openXSet,
             deleteXSet, isXSetRetained, getXSetAccessTime, asyncOpenXSet, asyncCopyXSet
    XSet: abandon, applyAccessPolicy, applyAutodeletePolicy, applyShredPolicy, 
          close, commit, createProperty, deleteField, 
          createXStream, openXStream, getField (most of the field manipulation methods 
          are supported), openExportStream, openImportStream, submitJob,
          haltJob, createRetention, setBaseRetention, setRetentionEnabledFlag,
          setRetentionDuration, setRetentionStarttime, holdXSet, releaseXSet, 
          accessXSet, getXSetAccessTime, getActualAutodelete, getActualShred, 
          asyncCommit, asyncOpenXStream
    XStream: read, write, close, tell, seek, asyncWrite, asyncRead, asyncClose
    XUID: toBytes, toString, equals
          Also XUID creation and encoding/decoding and ability to instantiate
          XUID instance based on a XUID value;
 

==============================================
2. Java_Reference_VIM SDK Directory Structure
==============================================

/Java_Reference_VIM

   /build             - build directory tree
      /classes        - Java Reference VIM classes sub-tree
         /examples    - Reference VIM examples classes sub-tree
      /test           - JUnit test classes sub-tree

   /config            - configuration files for executing tests
   /deliverables      - distribution directory for Java Reference VIM jar files
   /examples          - contains example client program

   /src                -  Reference VIM Source code tree
        /org/snia/xam/vim/reference
                        - Java Reference VIM source code (matches the package
                          path)
              /utils    - Java Reference VIM utility routines source code


    /test             -  JUnit tests source tree
        /org/snia/xam/vim/reference/    -  JUnit tests for Java Reference VIM

============================================
3. Reference VIM Repository (Backing Store)
============================================

 The Reference VIM implements the XAM API but also implements a backing store.
 The repository created by the Reference VIM is based on the machine's file
 system. The reference VIM persists XSets and associated XStream objects as files.
 In a vendor specific VIM the backing store would probably be some entity outside the
 VIM implementation.

 Default Repository Location:
   By default the Reference VIM persists XSets and XStreams to the temp directory
   specified by "java.io.tmpdir". This is also where any temp files are created.
   On Solaris this defaults to something like "/var/tmp". On Windows it is
   likely to be "c:\temp". Further on in this section is information on how to
   specify a different location for the repository.

 Directories and Files Created:
   In order to create unique filenames a filename safe varient of the base64 encoded
   XUID value is used. The Reference VIM uses the filename safe Base64 encoded specified
   in RFC-4648 (table 2) for filename. The Reference VIM only supports XUID interchange
   using the originally specified Base64 varient.

   The XSet and its properties are persisted in an XML file. The format of the XML 
   file follows the XAM specification's export format layout. In addition, data for 
   each XStream is stored in a separate file. The XStream data files are located in a 
   sub-directory which is also named using the XUID's filename safe string. The XStream 
   contents are stored in the same format the application used when creating the XStream. 
   No translation is performed on the data.

 Files created for a persisted XSet:
    >XSet_<xuid-string>.xml  - Contains the XML description of the XSet.
                               Conforms to the XAM Export format.
    >XSet_<xuid-string>      - Directory containing any XStream (stream field
                               data for the XSet.
    >XSet_<xuid-string>/XStream_#####.data - Payload/data for a single XStream
                                           (stream field). Note that the field
                                           definition in the XSet XML file will 
                                           contain the name of the associated 
                                           XStream data file.

 Temp files created:
   >XSet_<xuid-string>.tmp
   >XStream_####.tmp
   
Database for query support:
	ReferenceVimDB - This directory is created by the SQL database that the ReferenceVIM uses
	                 to support internal housekeeping and query job support. Generally this 
	                 database is automatically created and maintained by the ReferenceVIM. 
	                 If an error occurs, it is possible to rebuild the database by stopping
	                 the ReferenceVIM (or the application which has the ReferenceVIM embedded),
	                 deleting the database directory, and restarting the ReferenceVIM (or
	                 application). The database is automatically rebuilt when this process
	                 has been executed.
	                 
	                 Embedded within the ReferenceVimDB directory is a subdirectory called 
	                 "contentIndex", where Lucene segment data is stored. If for some reason
	                 the Lucene indexes become corrupted, you should remove the ReferenceVimDB
	                 directory and restart the Reference VIM so the database and content indexes
	                 are rebuilt.
	                 
	                 NOTE: If you cause the database to be rebuilt, the ReferenceVIM startup
	                 time will be longer than usual. It could take a few extra seconds to 
	                 several minutes.
                      

 Specifying a Different Reference VIM Repository Location:
   It is possible to specify the location of the repository by providing a value
   for the "dir" on the XRI information passed to the XSystem connect command.
   The absolute path specified must:
     - Be correctly formatted for the operating system
     - Must exist
     - User must have full privileges for directory

    For example to change the storage location used by the Reference VIM:
    a) First set directory to the Java_Reference_VIM sub-directory in the SDK
       installation.
    b) Edit the xam.test.props file modifying the xam.test.xri
       line specifying a absolute directory path for the "dir" parameter. The
       path specified will obviously vary depending on the operating system.
       See the section titled "XAM Reference VIM and Library Configuration 
       Information" for more information.

      Example xri values:
      Directory location of /home/mytest/xam_storage (Unix)
      xam.test.xri=snia-xam://SNIA_Reference_VIM!localhost?dir=/home/mytest/xam_storage

      Directory location of C:\mytest\xam_storage (Windows)
      xam.text.xri=snia-xam://SNIA_Reference_VIM!localhost?dir=C:\mytest\xam_storage
      
      WARNING: Applications will be able to access the hosts entire disk structure using 
      this XRI parameter. The Reference VIM does not provide any security restrictions 
      on this setting. Users are strongly cautioned. 

  Maintaining the Repository:
    Running the tests or running sample programs over and over again may create
    large numbers of files or directories in the repository. Currently there is
    no automated way to cleanup the repository once the XSet files and directories
    are created. Periodically it may be necessary to clean out the files in the
    repository by manually deleting files and directories like XSet_* and XStream_*.
     A developer may want to specify a private location for the repository to
    isolate their files and make debugging and tracking XSets easier.

=====================
4. Build Instructions
=====================

 Required dependencies.
 
 The following packages are required to build or run the Reference VIM:

    Ant      - http://ant.apache.org (tested with 1.7.0)
    Derby    - http://db.apache.org/derby/ (if using JDK/JRE earlier than 1.6)
               Note that Sun distributes this as Java DB with JDK/JRE 1.6.
    JUnit    - http://www.junit.org
               requires junit-3.8.1.jar in <sdk-install-dir>/trunk/lib subdirectory
    Java     - http://java.sun.com (or the platform JVM provider)
               (version 1.5 required; tested with 1.5.0_07)
    JavaCC   - https://javacc.dev.java.net/ (Version 4.2 or later)
               Required to build the Reference VIM, not required at run time.
    JavaMail - http://java.sun.com/products/javamail (version 1.4)
               copy mailapi.jar to the standard extension library directory
               which will vary depending on java version: <jdk-home>/jre/lib/ext.
               Or can download mailapi.jar file to the
               <sdk-install-dir>/trunk/lib subdirectory. The mail.jar file
               works as well.
    JavaBeans Activation Framework (JAF)-
               http://java.sun.com/javase/technologies/desktop/javabeans/jaf/index.jsp
               A standard extension for the Java platform. Must download unless using
               Java SE 6.0. Copy the activation.jar file to the standard extension
               library directory. Or you can copy it to <sdk-install-dir>/trunk/lib.
    Lucene   - http://apache.org/lucene (1.9 through 2.4.1)
               Optional functionality, which if present will enabled level 2 query.
               Only the Lucene-core jar file is needed in the class path. It is 
               recommended to use the latest version.
               Install in the <sdk-install-dir>/trunk/lib subdirectory. 

 Path requirements:

    JAVA_HOME environment variable should be set to point to the root
    java installation directory. The compiler for each platform must exist in the PATH.

    JAVA_HOME and the java directories containing the java compiler (javac) and
    java must be in the path.

 Other requirements:
 

 Supported platforms:

     Currently tested platforms are Solaris 10 (tested on x86 & sparc), Windows (WIN32),
     Fedora 10, Open SUSE 10, Ubuntu 8, Apple OS X
 
 How to build the XAM SDK using ant:

  0. Download and install ant and java. Download the other required jar files
     and place them in the <sdk-install-dir>/trunk/lib subdirectory:
     junit-3-8.1.jar, mailapi.jar, activation.jar.
     Note: Check the sdk guide and readme for more information on the external
     software dependencies for other XAM components.
  1. Build the xamlib.jar (Java_XAM_Library) and snia-xam.jar (Java_Interfaces)
  2. Enter the "Java_Reference_VIM" directory.
  3. Run "ant jar"
     To build the reference VIM jar file.
  4. Deliverables will be generated at the following locations:
        Java_Reference_VIM/deliverables/referenceVIM.jar - reference VIM jar
  5. Additional build targets are available. To build the tests use the "build_test"
     target. To build the tests and the reference VIM jar files use the
     "deliverables" target.

========================================================================
5. XAM Reference VIM and Library Configuration and Operation Information
========================================================================
  
  5.1 Basic configuration
  The tests and examples use two basic properties files that provide configuration
  information.
  - xam.test.props
    Is a properties file used by tests and client example programs. It contains
    definitions for the xri connection argument along with the name of the
    XAM configuration file and even the default authentication credentials.
    The xam.test.xri property specifies the VIM connection xri value. 

      Example xri values:
      Default value - no directory location specified:
      xam.test.xri=snia-xam://SNIA_Reference_VIM!localhost

      Directory location of /home/mytest/xam_storage (Unix)
      xam.test.xri=snia-xam://SNIA_Reference_VIM!localhost?dir=/home/mytest/xam_storage

      Directory location of C:\mytest\xam_storage (Windows)
      xam.text.xri=snia-xam://SNIA_Reference_VIM!localhost?dir=C:\mytest\xam_storage

  - ./config/ReferenceVIM.config 
    This is the XAM configuration file that is passed to the XAM Library. It
    contains important property definitions including the name of the VIM and
    its associated Java class name. This file must contain a property of the form
    .xam.config.vim.alias.<VIM-Name>.  The last part of the property name has 
    to match the name of the VIM. The property value must specify the VIM class name. 
    For example:
    .xam.config.vim.alias.SNIA_Reference_VIM=org.snia.xam.vim.reference.ReferenceVIM

    Additionally logging properties can be specified as well. Please see the 
    "Java Library" section in the SDK Developer's Guide or view the README.txt 
    file in the Java_XAM_Library directory for more information.
    
    5.2 User configuration
    The Reference VIM is capable of being configured to use an external file describing
    additional users. Without configuration a hardcoded use ("testuser") and password 
    ("testpasswd") are available. The following example shows a basic username/password 
    text file which may be used to provide additional authenticated users to a running
    instance of the Reference VIM.
        user1 pass1
        user2 pass2
        user3 pass3
        xyzzy plugh
    Note that this is a simple text file, and the passwords are not encrypted or protected.
    The intention is provide users with the opportunity to experience XAM behavior in a
    multiple user authenticated environment, not to provide a secure storage system! 
    If you desire to make this more secure, we suggest protecting the file with appropriate
    file permissions. 
    
    To use the external user file, set the XAM system property to refer to the path 
    of the file. For example, the following line may appear in your XAM Configuration file:
    	org.snia.xam.reference.passwd=/tmp/passwd.txt
    The Reference VIM will not have the built in username and password available if it 
    has been configured to use the external user file. 
    
    5.3 Access Control Policies
    The Reference VIM will create a unique access control policy for each defined user. 
    User policies grant read and write access to the named user, other user have no access.
    Two additional policies are defined. "org.snia.refvim.access.read.all" grants all users 
    read access to the XSet, and "org.snia.refvim.access.read..write.all" grants read and write 
    access to all XSets. Note that once "org.snia.refvim.access.read.all" has been applied 
    and committed, even the original owner of the XSet is unable to modify the XSet.
    
    These access policies are provided for illustrative purposes and users are cautioned 
    not to assume that this behavior will be present in systems supplied by storage vendors.
    
    5.3 Autodelete configuration
    The Reference VIM supports autodelete and aloows you to configure the time period used
    by the autodelete daemon process. The property "org.snia.xam.reference.autodelete.period"
    contains the number of seconds between autodelete sweeps of the store. The default value 
    is 300 seconds (5 minutes). Shorter times are acceptable to provide a more aggressive 
    processing and autodelete schedule, but doing so may result in reduced performance as
    Reference VIM spends more time evaluating XSets for autodeletion criteria.
    
    The value of "org.snia.xam.reference.autodelete.period" to a negative value will disabled
    the autodelete process, although setting the autodelete property on the XSet is still
    supported. 
    
    Because of autodelete functionality, only a single instance of the autodelete daemon, per
    store path, is created. Multiple instances of the ReferenceXSystem using the same store path
    are all sharing the same autodelete daemon. Thus only the first instance of a ReferenceXSystem 
    will create an autodelete daemon with the specified autodelete period.
    
    Be aware that setting autodelete on a simple XSet without any retention being set will
    result in the XSet being deleted the next time the autodelete daemon runs. Depending 
    on where the autodelete daemon is in its timing cycle, the XSet could be deleted as soon 
    as commit has completed. Generally autodelete should not be used on XSets without 
    some retention settings.
    
    5.4 Autodelete and Shred policies
    The Reference VIM provides 3 policies to set autodelete and shred settings on an XSet using
    the XSet.applyAutodeletePolicy() and XSet.applyShredPolicy() settings. The policies provided
    are summarized in the following table:
    
         Policy Name                                      | Description
         -------------------------------------------------+---------------------------------------------
         org.snia.refvim.disposition.autodelete           | autodelete = true,  shred = false
         org.snia.refvim.disposition.autodelete.and.shred | autodelete = true,  shred = true
         org.snia.refvim.disposition.shred                | autodelete = false, shred = true

	The Reference VIM does not support external creation or modification of these policy parameters.

	5.5 Retention Policies
	The Reference VIM provides a set of retention policies allowing the application to set retention
	criteria using policies instead of explicit settings. These policies may be used for base, event, 
	or application defined retentions.
	
         Policy Name                                      | Description
         -------------------------------------------------+---------------------------------------------
         org.snia.refvim.retention.none                   | duration= 0,           enabled = false
         org.snia.refvim.retention.one.second             | duration= 1000 mS,     enabled = true
         org.snia.refvim.retention.one.day                | duration= one day,     enabled = true
         org.snia.refvim.retention.thirty.days            | duration= 30 days,     enabled = true
         org.snia.refvim.retention.one.year               | duration= 365.25 days, enabled = true
	
	The Reference VIM does not support external creation or modification of these policy parameters.
	
	5.6 Import Processing
	In accordance with the SNIA XAM Architecture Specification, the Reference VIM will validate retention and
	disposition policies when the XSet is imported. Any error during policy validation will cause an appropriate
	exception to be thrown when closing the import XStream. Another effect of the import validation failing 
	is to place the XSet in a corrupt state, making it unusable. At this point the application may only abandon
	and close the XSet. 
	
	While it is permissible for an XSystem to make adjustments to its policies, or adjust XSet properties
	in such a way as to avoid violating retention criteria, the ReferenceVIM does neither. Unless the 
	imported XSet's policy parameters match the ReferenceVIM's retention policy parameters, the import 
	process will not successfully complete.
	
	The following is a list of conditions which will cause the import process to fail:
	   * A policy name in the imported XSet is unknown in the ReferenceVIM XSystem.
	   * The importing XSet policy specifies a retention policy duration longer than that supported by
	     the ReferenceVIM's policy of the same name.
	   * The importing XSet policy specifies a retention enabled differing from that supporter by
	     the ReferenceVIM's policy of the same name.
	     
	In all cases of the import process failing (when closing the import XStream), the XSet becomes corrupt.
	
	If the XSet already exists in the Reference storage, additional processing takes place. 
	   * If the binding attribute in the import XSet is different than the binding attributes of the previously
	     stored XSet, a new XUID will be issued when the XSet is committed. The previously stored XSet is not 
	     affected.
	   * If the effective retention of the importing XSet is less than that of the previously stored XSet,
	     the import will fail when closing the importXStream.
	     
	     
	5.7 Asynchronous Methods
	
	The Reference VIM supports all the specified asynchronous operations. The methods are implemented 
	with a single operation queue and worker threads to execute the operations. The default implementation
	provides a single worker thread, but more may be configured. 
	
	The XAM_INT property "org.snia.refvim.async.thread.count" is used to configure the number of 
	worker threads the Reference VIM will use. For example:
	
		xamLibraryInstance.createProperty( "org.snia.refvim.async.thread.count", false, 2 );
		
    configures the ReferenceVIM to use two worker threads to execute the asynchronous operations. 
    Applications should treat this parameter with care, too many threads will result in degraded 
    system performance. At most a few threads will provide the most benefit.
    
    5.8 Reference VIM Logging
    
    The Reference VIM supports the XAM specified logging property settings, and integrates with the Java Logging
    as implemented by the Java XAM Library. The Reference VIM uses and requires the org.snia.xam.util.LogManager
    class. 
    
    The LogManager restricts the use of Java Logging to a single logger per logfile instance. With this 
    pattern, it is possible to integrate log entries from multiple instances of the Reference VIM. When 
    multiple Reference VIM instances are running in the same JVM, and using the same logging parameters, 
    log entries will be integrated into a single log file. 
    
    XAM Levels correspond to Java Logging levels as follows:
    
    		XAM Level  |   Java Level  | Type of information logged
    		-----------+---------------+----------------------------
    		NONE       |   OFF         | Nothing
    		FATAL      |   SEVERE      | Non recoverable errors
    		ERROR      |   SEVERE      | Recoverable errors
    		WARN       |   WARN        | Notification of potential problems
    		INFO       |   INFO        | Configuration, performance, information of interest to app programmers
    		ALL        |   FINEST      | Debugging information
    		

	The ReferenceVIM will detect a change to the property ".xam.log.verbosity". The following setting 
		.xam.log.verbostity xam_int 100
    will turn on method entry/exit trace when the logging level is at XAM_LOG_ALL. Other verbostity values 
    have no effect at other levels of tracing (i.e. less than XAM_LOG_ALL).
    
    Configuration of logging when running the Reference VIM in a separate JVM, or on different hosts is not
    within the scope of this document.    		
	
    5.9 Summary of Configuration Properties
    
         Property Name                        |Type        | Description
         -------------------------------------+------------+--------------------------------------------
         org.snia.reference.passwd            | XAM_STRING |  Path to the username password file.
         org.snia.reference.autodelete.period | XAM_INT    |  Number of seconds between autodelete sweeps
         org.snia.refvim.async.thread.count   | XAM_INT    |  Number of worker threads to execute async operations
         -------------------------------------+------------+--------------------------------------------
         
     The ReferenceVIM also supports the XAM specified logging properties.
     
     5.10 Scalability
     
     The Reference VIM has been implemented with a focus on adhering to the XAM Architectural 
     specification. Because of this, no attempt has been made to make the Reference VIM scale
     in terms of throughput or large numbers of XSets. While the Reference VIM is reasonably 
     robust and stable, it may generate run time errors when large numbers of XSets have been
     stored. Programmers are cautioned to limit the maximum number of XSets in tests to 
     less than 5,000. 

==========================================
6. Building and Running the Client Example
==========================================
  Currently there is only a single example client program: ReferenceXSetClient.java.
  This program shows how to write a simple XAM client that using the Reference VIM.
  Because the reference VIM is run in the same JVM as the client program, the client
  program also must load and enable the reference VIM using the XAM library. The
  example program can be run using ant or from the command line. The example
  program also depends on the two Reference VIM properties files to provide configuration
  information. For more information please see the "XAM Reference VIM and Library 
  Configuration Information" section.
 
  Building and running the example using ant:
    1.Run "ant examples"
      This will build and run the example program. See the end of this section
      for the expected program output.

  Building and running the example from the command line:
    1. Set default to the Java_Reference_VIM directory.
    2. To build the client program set the classpath to include the two jar files
       specified above or specify the jar files using the javac commands -cp option.
       For example on Solaris:
       > javac -cp  "./deliverables/referenceVIM.jar:../Java_XAM_Library/deliverables/xamlib.jar"  examples/ReferenceXSetClient.java
 
    3. To run the client program you must also include the Java_Reference_VIM directory
       as part of the classpath. So on Solaris:
       >java -cp ".:./deliverables/referenceVIM.jar:../Java_XAM_Library/deliverables/xamlib.jar" examples.ReferenceXSetClient

    Note: If you do not specify an output directory then the java compiler 
          creates the class file in the same directory as the java file. By 
          contrast the ant examples target creates the class file in the 
          ./build/classes/examples directory. Make sure specify the 
          classpath so that you are running the desired ReferenceXSetClient instance. 


  Example output:
> ant example
XAM XSet Client Example Program - Uses Reference VIM by default

Initializing VIM
Loading test properties from file: xam.test.props
Loading the VIM using the Java XAM Library.
VIM Configuration contained in file: ./config/ReferenceVIM.config

=============================================
Client application example program testing:
Client application connecting to the VIM
Connection arguments: snia-xam://SNIA_Reference_VIM!localhost

Client application authenticating user credentials

Client application creating & persisting XSet with properties.
XSet created - XUID: AAA6AwAeQQsxMjI4NDAxNzM0NTI3AXcWl90AupNA
XSet updated (binding change) - XUID: AAA6AwAekJsxMjI4NDAxNzM0NTU0AngnwDsAPonD
Close & reopen XSet and test getting some property values
test.boolean=true
test.double=1234.5
test.string=testing string....
Closing XSet and XSystem
=============================================

======================================
7. Reference VIM Example Programs
======================================
  The directory "examples" contains three simple programs to exercise basic features of
  Reference VIM. 
  	* ReferenceXSetClient - Connects to a ReferenceVIM instance and creates an XSet.
  	* ExportXSetClient    - Connects to a ReferenceVIM instance and exports and XSet
  	* ImportXSetClient    - Connects to a ReferenceVIM instance and import an XSet.
  	
  	All three programs extend a simple class, ExampleBase, which contains enough structure
  	to hold instance variables for a XAM Library, and an XSystem instance. 
  	
  	The ExportXSetClient takes exactly one argument, a base 64 encoded XUID. This program will 
  	create a file with the name <XUID>.dat and put the cannonical XSet data in it. 
  	
  	The ImportXSetClient takes exactly one argument, a filename. The program expects
  	that the file will contain cannonical XSet data. This data is read in and imported
  	into the XSystem.

=============================
8. Building and Running Tests
=============================
  The tests and examples use two basic properties files that provide configuration
  information: xam.test.props and ReferenceVIM.config. Please see the "XAM Reference 
  VIM and Library Configuration Information" section for more information on
  configuring the Reference VIM.

  Building and running tests using ant:

  1. Specify directories used for tmp files and persisted XSets
     By default XSets are persisted to the java.io.tmpdir. This directory also
     contains any tmp files created.
     On Solaris this defaults to something like: /var/tmp

     To specify a different storage location for persisted XSets modify the
     xam.test.xri parameter specified in xam.test.props file and add a "dir"
     parameter value. A xri value specifying a storage location (when running
     on Solaris) would look like:
     xam.test.xri=snia-xam://SNIA_Reference_VIM!localhost?dir=/home/mytest/xam_storage

     See the Reference VIM Repository (Backing Store) section for more 
     information on specifying a storage location.

     The value of java.io.tmpdir can also be set to specify the storage location
     for tmp files. It will also be used as the XSet persistence directory if
     no "dir" parameter value is specified in the xri connect information.

  2. Run "ant test"
      To build (if necessary) and run all the JUnit tests EXCEPT retention.
      Other targets include:
      a) test_retention - runs the retention tests
      b) clean_test - cleans all test .class files
      c) build_test - builds test files
      d) also targets to run groups of tests separately: test_xsystem, test_xset,
          test_xstream, test_auth, test_retention
   
  3. You will need to manually delete the XSet xml files and directories
     when you no longer want them (e.g. XSet_*). May also have to delete temp copies
     of XStreams (e.g. XStream_#####.tmp).
