--- /dev/null
+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.
+
git://git.openafs.org / openafs-wiki.git / blobdiff