Java API for OpenAFS (JAFS) README
Current as of June 4, 2003

##########################################################################
# Copyright (c) 2001-2002 International Business Machines Corp.          #
# All rights reserved.                                                   #
#                                                                        #
# This software has been released under the terms of the IBM Public      #
# License.  For details, see the LICENSE file in the top-level source    #
# directory or online at http://www.openafs.org/dl/license10.html        #
#                                                                        #
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS    #
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT      #
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR  #
# A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR #
# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,  #
# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,    #
# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR     #
# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF #
# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING   #
# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS     #
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.           #
##########################################################################

---------------------------------------------------------------------------
*
* INTRODUCTION
*
---------------------------------------------------------------------------

JAFS is an open source API designed to allow Java programmers the ability
to create applications for the administration or use of OpenAFS file systems.
It works by accessing libadmin and libuafs (administrative and user-level 
libraries that come with OpenAFS) through JNI.  It consists of a Java package 
called org.openafs.jafs, and two shared libraries libjafsadm.so and libjafs.so.

---------------------------------------------------------------------------
*
* USE
*
---------------------------------------------------------------------------

There is a version of JAFS that has been compiled on Red Hat Linux 7.3, 
and can be directly used without compilation.  It was compiled using
OpenAFS 1.2.10a libraries (with a modified version of libjuafs.a).  It 
consists of a JAR file (jafs-1.2.10a.jar) and two shared libraries 
(libjafsadm.so and libjafs.so).  It was compiled using the 
--enable-transarc-paths on compilation (for use with the OpenAFS RPMs), 
gcc 2.96, and Java Classic VM version 1.4.1_02.

When you write Java code to use this API, import the
org.openafs.jafs package. During compilation of your Java code, 
ensure one of the following conditions are met:
  - Use the "-classpath" option to javac to specify the jafs.jar file.
  - Change your $CLASSPATH environment variable to include the
    jafs.jar file (e.g. export CLASSPATH=$CLASSPATH:jafs.jar

When running an application that uses JAFS, the shared libraries
need to be found by Java's library loader.  The easiest way to
accomplish this is to copy these files into the /usr/local/lib/ directory,
or create symbolic links from that directory to the files.  Alternatively, 
the directory containing the libraries can also be added to the
LD_LIBRARY_PATH environment variable.

You also need to have an OpenAFS client set up on your machine
(preferably version 1.2.10a, but it should work for some past versions as well).
You can obtain the OpenAFS client and view installation documentation at 
http://www.openafs.org (the RPMs are easiest to use for Linux).  Also any 
cells you plan to access through the API must have entries in your
client's CellServDB file (located in the /usr/vice/etc/ directory in most
setups).

This API is most effective when used with a cell that uses the kaserver
for authentication.  It does not currently support alternative methods of
authentication such as Kerberos V.

If you have successfully set up your Linux 7.3 environment as described
above, you will be able to develop and execute applications that use
the JAFS API.

---------------------------------------------------------------------------
*
* BUILD
*
---------------------------------------------------------------------------

 ** DOWNLOAD SOURCE
  The first step in compiling your own versions of the library and jar file
  is to download the OpenAFS source code.  Please follow the directions for
  for the source you download:

 ** APPLY THE APPROPRIATE PATCH
  You can apply the appropriate JAFS patch with the following command, 
  executed from the root directory of the download code 
  (i.e. openafs-1.2.10a/):

      patch -p1 < xxx.diff
      (where xxx.diff is one of the following patch files)

  Use the patch respective to the source you are using:
  * OpenAFS 1.2.6 Source (openafs-1.2.6-src.tar.gz)
    OpenAFS 1.2.7 Source (openafs-1.2.7-src.tar.gz)
    OpenAFS 1.2.8 Source (openafs-1.2.8-src.tar.gz)

      jafs-1.2.6-8.diff 

  * OpenAFS 1.2.9 Source (openafs-1.2.9-src.tar.gz)

      jafs-1.2.9.diff 

  * OpenAFS 1.2.10a Source (openafs-1.2.10a-src.tar.gz)

      jafs-1.2.10a.diff 

  * Daily Snapshot / CVS (example: openafs-snap-2003-05-21.tar.gz)

      jafs.diff


 ** RUN CONFIGURE
  From the same directory, run the configure script as you normally would 
  to compile OpenAFS, but run it with a java-home argument so the script can
  find your java distribution.  For example:

  ./configure [other options] --java-home=/usr/java/jdk

  NOTE: If the configure script is not within the root source directory,
        then you will need to first run ./regen.sh to generate the 
        configure script.  In this case you will need to manually
        modify the JAFS Makefile by setting the JAVA_HOME variable
        to your local system's JAVA_HOME. (i.e. /usr/java/jdk)

  The configure script will ensure that this directory contains bin/ and lib/ 
  subdirectories, and that there are /bin/javac and/bin/javah executables and 
  an include/jni.h file.  If you don't supply a command line argument for the 
  java home, the script will look for it in environment variables: first in
  $JAVA_HOME and then in $JDK_HOME.  Also, note that if you have installed
  (or are planning to install) OpenAFS by using the RPMs for Linux, you
  should provide the --enable-transarc-paths configuration option.  If you
  get a "** Can't determine local cell name" error message, the most likely
  reason is that you didn't supply this option.

 ** RUN MAKE
  Finally, do a full build of OpenAFS by executing 'make' in the current
  directory.  After it finishes, you are ready to compile JAFS.  Execute
  'make jafs' from that same directory.  Afterward, there will be 
  libjafsadm.so and libjafs.so in the lib/ directory, and a jafs.jar in the 
  jlib/ directory. These can be used according to the instructions in the 
  'USE' section of this document. 

  For additional make options, please refer to the next section "MAKE OPTIONS"


---------------------------------------------------------------------------
*
* MAKE OPTIONS
*
---------------------------------------------------------------------------

Additional make options are available by running 'make' from the 
src/JAVA/libjafs directory; they are as follows:

make            - Perform a full make of all Java classes, jar archive, and JNI
                  libraries
make acltest    - Builds the ACL test program.  Program usage is available by
                  simply invoking './acltest'
make clean      - Delete all Java classes, Java API docs, test programs, and C
                  object files
make cleanc     - Only delete test programs and C object files.
make clean_jar  - Delete the Java archive library (jlib/jafs.jar)
make clean_libs - Delete both JNI shared libraries (lib/libjafs.so and
                  lib/libjafsadm.so)
make install    - Performs a full make of all components and then installs all
                  necessary components to your local system.  This option 
                  prepares the required '/usr/afswsp/' directory for use by 
                  the native library.
make javadocs   - Generate Java API documents (in javadoc format).  Docs are
                  saved to src/JAVA/javadocs
make jar        - Builds the Java archive library (containing all Java classes)
make libjafs    - Builds the user-space library (used for ACL and file access)
make libjafsadm - Builds the administrative library (used for all admin related 
                  functions)

---------------------------------------------------------------------------
*
* DIRECTORIES, FILES, AND TEST PROGRAMS
*
---------------------------------------------------------------------------

src/JAVA/libjafs:

  Within the src/JAVA/libjafs directory you will find a few items in addition
  to the C source code and Makefiles.  In particular, you will find 'acltest.c',
  'buildinfo.pl', and a subdirectory 'etc'.

  acltest.c     - A test program that allows testing of the native libraries
                  ACL calls without going through Java.  

                  *Usage information for this program is available by simply 
                  invoking './acltest' without any parameters.

  buildinfo.pl  - A perl script that automatically updates the build information
                  every time the native libraries are compiled.  Additionally,
                  it automatically increments the build number associate with
                  the native libraries (found in VersionInfo.h).  It may also
                  be used to programatically query for build information.

                  *Usage information for this program is available by simply 
                  invoking 'perl buildinfo.pl' without any parameters.

  etc/          - A directory containing user-space configuration files. These 
                  files are used for user-space initialization and cache 
                  configuration and are copied to '/usr/afswsp/etc' if a
                  'make install' is issued.

src/JAVA/classes:

  Within the src/JAVA/classes directory you will find the root of the Java 
  package, the error message catalog file, and a test program:

  *.java        - Java classes that comprise the test program.

  adminTest     - A script that invokes the Java console-based test program.
                  This program can be used to exercise all major API calls 
                  from Java, thus testing JNI libraries as well as Java code.

                  *Usage information for this program is available via its
                  help menu: './adminTest help'

  adminTest.properties
                - Configuration file for the Admin test program (only contains
                  default cell name for administrator)

  ErrorMessages.properties
                - Error message catalog file used by the ErrorTable class. Note
                  that an additional message file can be generated that represents
                  a language other than english (refer to the ErrorTable API docs
                  for more information)

  org/          - Root of the Java class package (package: org.openafs.jafs)


src/JAVA/javadocs:

  This directory is dynamically generated when you issue a 'make javadocs' from
  the src/JAVA/libjafs directory. It contains all Java API documentation
  generated from the Java classes.

---------------------------------------------------------------------------
*
* MISC
*
---------------------------------------------------------------------------

If you'd like to edit the source code, you'll find the native C code in
the src/JAVA/libjafs directory, and the Java code in the 
src/JAVA/classes/org/openafs/jafs/ directory.  Please reference the 
src/TechNotes-JavaAPI document for more information.

