JavaAdminAPI/README

   1 Java API for OpenAFS (JAFS) README
   2 Current as of June 4, 2003
   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 ---------------------------------------------------------------------------
  26 *
  27 * INTRODUCTION
  28 *
  29 ---------------------------------------------------------------------------
  30
  31 JAFS is an open source API designed to allow Java programmers the ability
  32 to create applications for the administration or use of OpenAFS file systems.
  33 It works by accessing libadmin and libuafs (administrative and user-level
  34 libraries that come with OpenAFS) through JNI.  It consists of a Java package
  35 called org.openafs.jafs, and two shared libraries libjafsadm.so and libjafs.so.
  36
  37 ---------------------------------------------------------------------------
  38 *
  39 * USE
  40 *
  41 ---------------------------------------------------------------------------
  42
  43 There is a version of JAFS that has been compiled on Red Hat Linux 7.3,
  44 and can be directly used without compilation.  It was compiled using
  45 OpenAFS 1.2.10a libraries (with a modified version of libjuafs.a).  It
  46 consists of a JAR file (jafs-1.2.10a.jar) and two shared libraries
  47 (libjafsadm.so and libjafs.so).  It was compiled using the
  48 --enable-transarc-paths on compilation (for use with the OpenAFS RPMs),
  49 gcc 2.96, and Java Classic VM version 1.4.1_02.
  50
  51 When you write Java code to use this API, import the
  52 org.openafs.jafs package. During compilation of your Java code,
  53 ensure one of the following conditions are met:
  54   - Use the "-classpath" option to javac to specify the jafs.jar file.
  55   - Change your $CLASSPATH environment variable to include the
  56     jafs.jar file (e.g. export CLASSPATH=$CLASSPATH:jafs.jar
  57
  58 When running an application that uses JAFS, the shared libraries
  59 need to be found by Java's library loader.  The easiest way to
  60 accomplish this is to copy these files into the /usr/local/lib/ directory,
  61 or create symbolic links from that directory to the files.  Alternatively,
  62 the directory containing the libraries can also be added to the
  63 LD_LIBRARY_PATH environment variable.
  64
  65 You also need to have an OpenAFS client set up on your machine
  66 (preferably version 1.2.10a, but it should work for some past versions as well).
  67 You can obtain the OpenAFS client and view installation documentation at
  68 http://www.openafs.org (the RPMs are easiest to use for Linux).  Also any
  69 cells you plan to access through the API must have entries in your
  70 client's CellServDB file (located in the /usr/vice/etc/ directory in most
  71 setups).
  72
  73 This API is most effective when used with a cell that uses the kaserver
  74 for authentication.  It does not currently support alternative methods of
  75 authentication such as Kerberos V.
  76
  77 If you have successfully set up your Linux 7.3 environment as described
  78 above, you will be able to develop and execute applications that use
  79 the JAFS API.
  80
  81 ---------------------------------------------------------------------------
  82 *
  83 * BUILD
  84 *
  85 ---------------------------------------------------------------------------
  86
  87  ** DOWNLOAD SOURCE
  88   The first step in compiling your own versions of the library and jar file
  89   is to download the OpenAFS source code.  Please follow the directions for
  90   for the source you download:
  91
  92  ** APPLY THE APPROPRIATE PATCH
  93   You can apply the appropriate JAFS patch with the following command,
  94   executed from the root directory of the download code
  95   (i.e. openafs-1.2.10a/):
  96
  97       patch -p1 < xxx.diff
  98       (where xxx.diff is one of the following patch files)
  99
 100   Use the patch respective to the source you are using:
 101   * OpenAFS 1.2.6 Source (openafs-1.2.6-src.tar.gz)
 102     OpenAFS 1.2.7 Source (openafs-1.2.7-src.tar.gz)
 103     OpenAFS 1.2.8 Source (openafs-1.2.8-src.tar.gz)
 104
 105       jafs-1.2.6-8.diff
 106
 107   * OpenAFS 1.2.9 Source (openafs-1.2.9-src.tar.gz)
 108
 109       jafs-1.2.9.diff
 110
 111   * OpenAFS 1.2.10a Source (openafs-1.2.10a-src.tar.gz)
 112
 113       jafs-1.2.10a.diff
 114
 115   * Daily Snapshot / CVS (example: openafs-snap-2003-05-21.tar.gz)
 116
 117       jafs.diff
 118
 119
 120  ** RUN CONFIGURE
 121   From the same directory, run the configure script as you normally would
 122   to compile OpenAFS, but run it with a java-home argument so the script can
 123   find your java distribution.  For example:
 124
 125   ./configure [other options] --java-home=/usr/java/jdk
 126
 127   NOTE: If the configure script is not within the root source directory,
 128         then you will need to first run ./regen.sh to generate the
 129         configure script.  In this case you will need to manually
 130         modify the JAFS Makefile by setting the JAVA_HOME variable
 131         to your local system's JAVA_HOME. (i.e. /usr/java/jdk)
 132
 133   The configure script will ensure that this directory contains bin/ and lib/
 134   subdirectories, and that there are /bin/javac and/bin/javah executables and
 135   an include/jni.h file.  If you don't supply a command line argument for the
 136   java home, the script will look for it in environment variables: first in
 137   $JAVA_HOME and then in $JDK_HOME.  Also, note that if you have installed
 138   (or are planning to install) OpenAFS by using the RPMs for Linux, you
 139   should provide the --enable-transarc-paths configuration option.  If you
 140   get a "** Can't determine local cell name" error message, the most likely
 141   reason is that you didn't supply this option.
 142
 143  ** RUN MAKE
 144   Finally, do a full build of OpenAFS by executing 'make' in the current
 145   directory.  After it finishes, you are ready to compile JAFS.  Execute
 146   'make jafs' from that same directory.  Afterward, there will be
 147   libjafsadm.so and libjafs.so in the lib/ directory, and a jafs.jar in the
 148   jlib/ directory. These can be used according to the instructions in the
 149   'USE' section of this document.
 150
 151   For additional make options, please refer to the next section "MAKE OPTIONS"
 152
 153
 154 ---------------------------------------------------------------------------
 155 *
 156 * MAKE OPTIONS
 157 *
 158 ---------------------------------------------------------------------------
 159
 160 Additional make options are available by running 'make' from the
 161 src/JAVA/libjafs directory; they are as follows:
 162
 163 make            - Perform a full make of all Java classes, jar archive, and JNI
 164                   libraries
 165 make acltest    - Builds the ACL test program.  Program usage is available by
 166                   simply invoking './acltest'
 167 make clean      - Delete all Java classes, Java API docs, test programs, and C
 168                   object files
 169 make cleanc     - Only delete test programs and C object files.
 170 make clean_jar  - Delete the Java archive library (jlib/jafs.jar)
 171 make clean_libs - Delete both JNI shared libraries (lib/libjafs.so and
 172                   lib/libjafsadm.so)
 173 make install    - Performs a full make of all components and then installs all
 174                   necessary components to your local system.  This option
 175                   prepares the required '/usr/afswsp/' directory for use by
 176                   the native library.
 177 make javadocs   - Generate Java API documents (in javadoc format).  Docs are
 178                   saved to src/JAVA/javadocs
 179 make jar        - Builds the Java archive library (containing all Java classes)
 180 make libjafs    - Builds the user-space library (used for ACL and file access)
 181 make libjafsadm - Builds the administrative library (used for all admin related
 182                   functions)
 183
 184 ---------------------------------------------------------------------------
 185 *
 186 * DIRECTORIES, FILES, AND TEST PROGRAMS
 187 *
 188 ---------------------------------------------------------------------------
 189
 190 src/JAVA/libjafs:
 191
 192   Within the src/JAVA/libjafs directory you will find a few items in addition
 193   to the C source code and Makefiles.  In particular, you will find 'acltest.c',
 194   'buildinfo.pl', and a subdirectory 'etc'.
 195
 196   acltest.c     - A test program that allows testing of the native libraries
 197                   ACL calls without going through Java.
 198
 199                   *Usage information for this program is available by simply
 200                   invoking './acltest' without any parameters.
 201
 202   buildinfo.pl  - A perl script that automatically updates the build information
 203                   every time the native libraries are compiled.  Additionally,
 204                   it automatically increments the build number associate with
 205                   the native libraries (found in VersionInfo.h).  It may also
 206                   be used to programatically query for build information.
 207
 208                   *Usage information for this program is available by simply
 209                   invoking 'perl buildinfo.pl' without any parameters.
 210
 211   etc/          - A directory containing user-space configuration files. These
 212                   files are used for user-space initialization and cache
 213                   configuration and are copied to '/usr/afswsp/etc' if a
 214                   'make install' is issued.
 215
 216 src/JAVA/classes:
 217
 218   Within the src/JAVA/classes directory you will find the root of the Java
 219   package, the error message catalog file, and a test program:
 220
 221   *.java        - Java classes that comprise the test program.
 222
 223   adminTest     - A script that invokes the Java console-based test program.
 224                   This program can be used to exercise all major API calls
 225                   from Java, thus testing JNI libraries as well as Java code.
 226
 227                   *Usage information for this program is available via its
 228                   help menu: './adminTest help'
 229
 230   adminTest.properties
 231                 - Configuration file for the Admin test program (only contains
 232                   default cell name for administrator)
 233
 234   ErrorMessages.properties
 235                 - Error message catalog file used by the ErrorTable class. Note
 236                   that an additional message file can be generated that represents
 237                   a language other than english (refer to the ErrorTable API docs
 238                   for more information)
 239
 240   org/          - Root of the Java class package (package: org.openafs.jafs)
 241
 242
 243 src/JAVA/javadocs:
 244
 245   This directory is dynamically generated when you issue a 'make javadocs' from
 246   the src/JAVA/libjafs directory. It contains all Java API documentation
 247   generated from the Java classes.
 248
 249 ---------------------------------------------------------------------------
 250 *
 251 * MISC
 252 *
 253 ---------------------------------------------------------------------------
 254
 255 If you'd like to edit the source code, you'll find the native C code in
 256 the src/JAVA/libjafs directory, and the Java code in the
 257 src/JAVA/classes/org/openafs/jafs/ directory.  Please reference the
 258 src/TechNotes-JavaAPI document for more information.
 259