********************************
*  xCAT-API: Version 0.1       *
********************************

2 January 2009

(C)opyright 2009, by Cluster Resources Inc.

-----------------
1.  INTRODUCTION
-----------------
xCAT-API is an open source xCAT communication library for the Java(tm) platform. 
It runs on the Java Platform (Java 1.3.x or higher). It can be used to communicate
with an instance of the xCAT daemon (xcatd).

This library is licensed under the terms of the Eclipse Public License -v 1.0.
A copy of the license is included in the distribution.

Please note that xCAT-API is distributed WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. Please refer to the license for details.

-----------------
2.  ABOUT xCAT
-----------------
xCAT - eXtreme Cluster Administration Toolkit

xCAT is a toolkit for the deployment and administration of clusters.

For documentation on getting started with xCAT you can download the 
following xCAT 2.0 Cookbooks.

Linux Cookbook:
http://xcat.svn.sourceforge.net/svnroot/xcat/xcat-core/trunk/perl-xCAT-2.0/xCAT2.0.pdf

AIX Cookbook:
http://xcat.svn.sourceforge.net/svnroot/xcat/xcat-core/trunk/perl-xCAT-2.0/xCAT2onAIX.pdf

The Cookbooks are also available on an installed system in the
/opt/xcat/share/doc/ directory.

xCAT is made available as OSS under the EPL license:
http://www.opensource.org/licenses/eclipse-1.0.php

-----------------
3.  DOCUMENTATION
-----------------
Please refer to the quickstartguide.doc for an explanation on how to use
this API and some simple examples. Also, there are some simple examples 
included with the source for this project.

API documentation files in HTML format are available by generating them directly
from the source code. You can do this using the 'javadoc' or 'gjdoc' 
utilities directly, or with the Ant script (build.xml) included in the
distribution. The Ant target is called "javadoc".

-----------------
4.  DEPENDENCIES
-----------------
xCAT-API has the following dependencies:

(a)  a Java JDK (has been tested with JDK 1.5, but should work with all Java 1.3.x or higher). 

(b)  Not-Yet-Commons-SSL - version 0.3.9 or later. The runtime jar file (version 0.3.9) 
is included in the xCAT-API distribution. You can obtain the complete source code for 
Not-Yet-Commons-SSL from:

   http://juliusdavies.ca/commons-ssl/

Not-Yet-Commons-SSL is licensed under the terms of the Apache License Version 2.0.

(c)  Apache Commons Logging - 1.0.1 or later. The runtime jar file (version 1.1.1) 
is included in the xCAT-API distribution. You can obtain the complete source code from

   http://commons.apache.org/logging/
   
Apache Commons Logging is licensed under the terms of the Apache License Version 2.0.

(d)  JUnit - a unit testing framework. JUnit is licensed under the terms
of the IBM Common Public License. You can find out more about JUnit
and/or download the latest version from:

    http://www.junit.org

The JUnit tests included with xCAT-API have been created using JUnit
3.8.

--------------------
5.  ANT BUILD SCRIPT
--------------------
An Ant build script (build.xml) is included in the distribution. This
is the script that is used to create the documentation and distribution
file.

For more information about Ant:

    http://ant.apache.org/

------------------------
5.  INCLUDED EXAMPLES
------------------------
There are a few examples included in the distribution on how this API
may be used to connect to an xCAT server. These examples are intended
to show users how this API can be used, but will not work 'out of the box'.
Before one can run these files, it is necessary that they modify the 
server and port number for their instance of the xCAT daemon, as well
as any certificates that are required to connect to xCAT.

Also please be aware that running these commands on the xCAT server
may have undesired effects. Please pay close attention to the CreateRequest.java
example. This file will run the mknb command, which may have an undesired
effect for your xCAT setup.

---------------
6.  LIMITATIONS
---------------
xCAT-API has some known limitations that will hopefully be addressed in 
the future:

    - There is no way to communicate directly with a plugin without going through
      the xcatd server, even if XCATBYPASS is set.
      
    - There is no way to get xCAT's command vocabulary to the API.
    
If there are other items that you think should be listed here,
please post a bug report.
