src/JAVA/libjafs/JAFS_README

   1 Java API for OpenAFS (Jafs) README
   2 Current as of 6/5/02
   3
   4  ##########################################################################
   5  # Copyright (c) 2001-2002 International Business Machines Corp.          #
   6  # All rights reserved.                                                   #
   7  #                                                                        #
   8  # This software has been released under the terms of the IBM Public      #
   9  # License.  For details, see the LICENSE file in the top-level source    #
  10  # directory or online at http://www.openafs.org/dl/license10.html        #
  11  #                                                                        #
  12  # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS    #
  13  # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT      #
  14  # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR  #
  15  # A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR #
  16  # CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,  #
  17  # EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,    #
  18  # PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR     #
  19  # PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF #
  20  # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING   #
  21  # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS     #
  22  # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.           #
  23  ##########################################################################
  24
  25 *** INTRODUCTION ***
  26
  27 Jafs is an open source API designed to allow Java programmers the ability
  28 to create applications for the administration or use of OpenAFS file systems.
  29 It works by accessing libadmin and libuafs (administrative and user-level
  30 libraries that come with OpenAFS) through JNI.  It consists of a Java package
  31 called org.openafs.jafs, and a shared libraries libjafsadm.so and libjafs.so.
  32
  33 *** USE ***
  34
  35 There is a version of Jafs that has been compiled on Red Hat Linux 7.1,
  36 and can be directly used without compilation.  It was compiled using
  37 OpenAFS 1.2.4 libraries (with a modified version of libjuafs.a).  It
  38 consists of a JAR file (jafs.jar) and two shared libraries
  39 (libjafsadm.so and libjafs.so).  It was compiled using the
  40 --enable-transarc-paths on compilation (for use with the OpenAFS RPMs),
  41 gcc 2.96, and Java Classic VM version 1.4.0.
  42
  43 When you write Java code to use this API, import the
  44 org.openafs.jafs package. During compilation of your Java code,
  45 ensure one of the following conditions are met:
  46   - Use the "-classpath" option to javac to specify the jafs.jar file.
  47   - Change your $CLASSPATH environment variable to include the
  48     jafs.jar file (e.g. export CLASSPATH=$CLASSPATH:jafs.jar
  49
  50 When running an application that uses Jafs, the shared libraries
  51 need to be found by Java's library loader.  The easiest way to
  52 accomplish this is to copy these files into the /usr/lib/ directory,
  53 or create symbolic links from that directory to the files.  Alternatively,
  54 the directory containing the libraries can also be added to the
  55 LD_LIBRARY_PATH environment variable, instead.
  56
  57 You also need to have an OpenAFS client set up on your machine
  58 (preferably version 1.2.4, but it should work for some past versions as well).
  59 You can obtain the OpenAFS client and view installation documentation at
  60 http://www.openafs.org (the RPMs are easiest to use for Linux).  Also any
  61 cells you plan to access through the API must have entries in your
  62 client's CellServDB file (located in the /usr/vice/etc/ directory in most
  63 setups).
  64
  65 This API is most effective when used with a cell that uses the kaserver
  66 for authentication.  It does not currently support alternative methods of
  67 authentication such as Kerberos V.
  68
  69 If you have successfully set up your Linux 7.1 environment as described
  70 above, you will be able to develop and execute applications that use
  71 the Jafs API.
  72
  73 *** BUILD ***
  74
  75 The first step in compiling your own versions of the library and jar file
  76 is to download the OpenAFS source code.
  77
  78 From that same directory, run the configure script as you normally would
  79 to compile OpenAFS, but run it with a java_home argument so the script can
  80 find your java distribution.  For example:
  81
  82   ./configure [other options] --java_home=/usr/local/jdk
  83
  84 The configure script will ensure that this directory contains bin/ and lib/
  85 subdirectories, and that there are /bin/javac and/bin/javah executables and
  86 an include/jni.h file.  If you don't supply a command line argument for the
  87 java home, the script will look for it in environment variables: first in
  88 $JAVA_HOME and then in $JDK_HOME.  Also, note that if you have installed
  89 (or are planning to install) OpenAFS by using the RPMs for Linux, you
  90 should provide the --enable-transarc-paths configuration option.  If you
  91 get a "** Can't determine local cell name" error message, the most likely
  92 reason is that you didn't supply this option.
  93
  94 Next, do a full build of OpenAFS by executing a make in the current
  95 directory.  After it finishes, you are ready to compile Jafs.  Execute
  96 'make jafs' from that same directory.  Afterward, there will be
  97 libjafsadm.so and libjafs.so in the lib/ directory, and a jafs.jar in the
  98 jlib/ directory. These can be used according to the instructions in the
  99 'USE' section of this document.
 100
 101 If you'd like to edit the source code, you'll find the native C code in
 102 the src/libjafs directory, and the Java code in the
 103 src/JAVA/org/openafs/jafs/ directory.  Please reference the
 104 src/TechNotes-JavaAPI document for more information.
 105