*********************************************
  XAM SDK - JAVA XAM Library - README v1.0 
*********************************************

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

 1. Deliverables
      - Java XAM Library
 2. Directory Structure
 3. Build Instructions
      - Required Dependencies
      - PATH requirements
      - Supported Platforms
      - Building with ant
 4. Building and Running Tests
 5. Creating an instance of the XAM Library
      - XAM Library Configuration File
      - Supported Configuration Namespaces
      - Configuration File Syntax

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

  Java XAM Library

    Version 1.0 (in progress) of the the Java XAM Library (JXL). The JXL is 
    a pure Java implementation of the SNIA XAM Architecture.

    Summary: 
    - Provides an implementation of the XAMLibrary interface.
    - Includes the Java XAM Interfaces as part of the distribution.
    - XAM Library and Interface implementations are distributed in "xamlib.jar".
    - Required Java Toolkit functions (org.snia.xam.util) are distributed 
      in "xamtoolkit.jar".
    - Provides an internal implementation of an AbstractFieldContainer which 
      may be used by Java based VIM authors. 
      NOTE: This is neither standardized nor required at this time.
    - No support for using C (.dll/.so) VIMs.
    - Support for the SNIA XAM SDK Configuration standard.
    - Default logging using the standardized logging control properties.
      The current implementation uses Java 5 logging.
    - Unit tests provided will test the XAM Library implementation. These tests do 
      not provide system testing and do not run against any VIM.


======================
2. Directory structure
======================

/Java_XAM_Library 

   /bin               - Intermediate directory to contain build files
      /org            - Java library class files

   /deliverables      - distribution directory for Java XAM Library jar file
   		                and Java Docs
   /docs              - Output of the Java doc process

   /lib               - required external jar files (contains JUnit jars)

   /src               -  Source code tree
       /org/snia/xam/base
	                  - The base classes required to implement the XAMLibrary
 
       /org/snia/xam/util
                      - Utility classes which may be used by applications 
			            and VIM authors.

    /test             - JUnit tests source tree
       /org/snia/xam/ - JUnit tests for Java XAM Library

       /org/snia/xam/base 
       		          - JUnit tests for Base classes

       /org/snia/xam/util
                      - JUnit tests for Util classes.


=====================
3. Build Instructions
=====================

 Required dependencies: 

    Ant     - http://ant.apache.org (tested with 1.7.0)               
    Java    - http://java.sun.com (or the platform JVM provider)
              (version 1.5 required; tested with 1.5.0_07)
    JUnit   - http://junit.org (developed with JUnit version 3.8.1)

 Path requirements:

    JAVA_HOME environment variable should be set to point to the root
    java installation directory of 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.

 Supported platforms:

     This library has been tested with Sun Java 5 and Java 6 on the following 
     platforms:
     - Windows XP and Vista (32 bit)
     - Linux (32 bit, Fedora 10, Open Suse 10, Ubuntu 9) 
     - Open Solaris (x86)
     - Apple Macintosh OS X (10.5)

     The SNIA XAM SDK Technical Working Group would like to hear about 
     incompatibilities or success stories on platforms other than those listed
     here.
 
 How to build the XAM Library using ant:

  1. Enter the "Java_Interfaces" directory
  2. Run "ant deliver"
  3. Enter the "Java_XAM_Library" directory.
  4. Run "ant deliver"
  5. Deliverables will be generated at the following locations:
        Java_XAM_Library/deliverables/xamlib.jar
        Java_XAM_Library/deliverables/xamtoolkit.jar
        Java_XAM_Library/deliverables/testvim.jar
        Java_XAM_Library/deliverables/api/   (JavaDocs)
  6. NOTE: You do not need to include the Java Interfaces jar file in your 
     classpath, they are merged into the XAM Library jar (xamlib.jar).

=============================
4. Running Tests
=============================

  1. Enter the "Java_XAM_Library" directory.
  2. Run "ant test"
  3. All the unit tests will run, there should be no errors

=============================
5. Using the Java Library
=============================

5.1 Obtaining an instance of the XAMLibrary

  In order to use this Java library, the application must locate and include
  the xamlib.jar and xamtoolkit.jar files in the application's classpath. 

  There are two acceptable ways to obtain an instance of the Java XAM Library.
  The recommended way is to utilize the XAMLibraryFactory class, which is included
  in the jar files. This factory will instantiate the library and isolating your application
  from a XAM Library implementation. This will let you reconfigure your application
  to use the C XAM Library (via JNI) with out needing to recompile. 
  
  The XAMLibraryFactory can be used to obtain a XAMLibrary instance with the following:
  
  	XAMLibrary lib = XAMLibraryFactory.newXAMLibrary();
  	
  If the application chooses not to use the XAMLibraryFactory, an instance may be obtained 
  using the following:
  
     XAMLibrary xam = new XAMImplementation( "XAM.config" );
     
  If the library is created without a configuration argument (no argument constructor,
  or the XAMLibraryFactory.getLibrary() method), the Java XAM Library will read the 
  value of the the environment variable XAM_CONFIG_PATH. If this points to a file, this
  will be used as the XAM Config. If there is no argument, and the XAM_CONFIG_PATH 
  environment variable does not exist, the default value "xam.properties" will be used. 

5.2 Configuring the library initializing

  Each XAM Library instance will load configuration parameters from a configuration 
  file. The file must contain information to allow the library to find the referenced 
  VIM. Additionally, the file may contain parameters to control logging.  
 
  The configuration file must contain a line similar to:

     .xam.config.vim.alias.TestVIM=org.snia.xam.testvim.TestVim

  This line tells the library that a VIM named "TestVIM" is available by
  creating an instance of the class "org.snia.xam.testvim.TestVim". The 
  class for the VIM must be in the application's classpath. 
  
  The following prarameters control the logging:
  
     .xam.log.path
     	The file path indicating where the log file is to be placed. The application must 
     	have write permission to this path location.
     	
     .xam.log.verbosity
     	An integer value 0-5 indicating the loggin verbosity. These values are specified
     	in the XAM Architecture specification.
     	 
     .xam.log.debug 
     	An integer value 0 to MAX_LONG (2**32-1) indicating the amount of debug logging
     	to be used. Debug logging in the Java XAM Library is minimal, and this value is 
     	most useful with a particular VIM.
     
     .xam.log.max.size
        The maximum size of a log file, before it is rolled over to a new file.
        
     .xam.log.max.rollovers
     	The maximum number of log files to keep after they rolled over.
     	
     .xam.log.append
     	A value, if "true" will append to the latest log file, otherwise the library will
     	create a new file when the library is created.

   Java Logging Use
   The following information is provided for application and VIM authors wishing to integrate with 
   Java XAM Library use of Java Logging.
   
   The Java XAM Library uses Java native logging (java.util.logging). Java logging is very versatile,
   but doesn't completely match the functionality of XAM logging. The Java XAM Library simplifies
   its use of Java logging by creating a single instance of a logger for each log file specified via
   the logging properties. To accomplish this, a toolkit class (org.snia.xam.util.LogManager) is provided
   to encapsulate all the functionality:
   
	   public static Logger GetLogger( String  path,
                                       int     logSize,
                                       int     rolloverCount,
                                       boolean append )
            throws XAMException
            
   The LogManager will create a logger and FileHandler to service the logfile. Whenever log settings have
   changed (via a XAMLibrary.setProperty() or XSystem.setProperty() method call), the GetLogger method is 
   called to update the FileHandler on the logger. It is important to realize that because a specific log
   file is global, all settings are shared by the logger. If a VIM is running in the same JVM as the Java 
   XAM Library, the VIM is encouraged to use the org.snia.xam.util.LogManager class. 
   
   The LogManager uses Java logging in the following ways:
   	  - One logger per uniquely named log file (based on the path property). This is different 
   	    than using the classname to identify loggers.
   	  - A single FileHandler attached to the logger. 
   	  - Loggers do NOT inherit handlers from the parent logger (in this case, the root logger).
   	  
   If the application or VIM is running in another JVM instance, or on different hosts, the logfiles may 
   not be integrated. It is beyond the scope of this note to describe logfile unification across multiple 
   processes or hosts.
   
   5.3 Using classes from XAMLib.jar and XAMToolkit.jar
   
   The two jar files contain the entirety of the Java XAM Library. The jar file XAMLib.jar contains
   all the classes required to implement the Java XAM Library, while the jar file XAMToolkit.jar 
   contains the required tool kit functions specified by the XAM Java API specification. The toolkit
   functions include:
      * ExtendedFieldContainer (XAM required)
      * ISO8601Date
      * LogManager
      * QueryFactory (XAM required)
      * SASLUtils
      * XAMIOException (needed for the streams)
      * XAMLibraryFactory (XAM SDK Required)
      * XStreamInputStream (XAM required)
      * XStreamOutputStream (XAM required)
      * XUIDIterator (XAM required)
      
   The toolkit functions are programmed using only the publicly defined XAM interfaces. Thus the 
   toolkit is usable with either the Java XAM Library or the C XAM Library (using the JNI bindings).
   
   The core of the Java XAM Library (XAMLib.jar, containing packages org.snia.xam.base) has all the 
   classes required to implement the Java XAM Library. Applications should not use classes from this 
   package. VIM authors may find implemention class from org.snia.xam.base to be of use when impementing
   a Java base VIM, but be aware that you are tying your implemention to Java XAM Library codebase.
   This in it self is not a problem, but VIM authors are strongly encouraged to consider the long term
   consequences of this dependency. 
   
   
   	        	