jafs-library-20020725
[openafs.git] / 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.  If the code doesn't contain the
77 libjuafs version of the libuafs library -- noted by the README file located
78 in the src/libuafs directory (if a README file doesn't exist in this directory
79 then the libjuafs patch (libuafs.diff) has not been applied) -- you must 
80 first apply the libjuafs patch. You can apply the libjuafs patch with the 
81 following command, executed from the root directory of the download code 
82 (i.e. openafs-1.2.4/):
83
84   patch -p1 < libuafs.diff
85
86 Next, if the code doesn't contain the src/JAVA/libjafs directory, you can 
87 apply the jafs patch to it with the following command, executed from the 
88 root directory of the download code (i.e. openafs-1.2.4/):
89
90   patch -p1 < jafs.diff
91
92 Note that the source code you download needs to be newer than 4/22/02,
93 in order for the full functionality of the API to be effective.  Otherwise,
94 you may experience link errors.
95
96 From that same directory, run the configure script as you normally would 
97 to compile OpenAFS, but run it with a java_home argument so the script can
98 find your java distribution.  For example:
99
100   ./configure [other options] --java_home=/usr/local/jdk
101
102 The configure script will ensure that this directory contains bin/ and lib/ 
103 subdirectories, and that there are /bin/javac and/bin/javah executables and 
104 an include/jni.h file.  If you don't supply a command line argument for the 
105 java home, the script will look for it in environment variables: first in
106 $JAVA_HOME and then in $JDK_HOME.  Also, note that if you have installed
107 (or are planning to install) OpenAFS by using the RPMs for Linux, you
108 should provide the --enable-transarc-paths configuration option.  If you
109 get a "** Can't determine local cell name" error message, the most likely
110 reason is that you didn't supply this option.
111
112 Next, do a full build of OpenAFS by executing a make in the current
113 directory.  After it finishes, you are ready to compile Jafs.  Execute
114 'make jafs' from that same directory.  Afterward, there will be 
115 libjafsadm.so and libjafs.so in the lib/ directory, and a jafs.jar in the 
116 jlib/ directory. These can be used according to the instructions in the 
117 'USE' section of this document. 
118
119 If you'd like to edit the source code, you'll find the native C code in
120 the src/libjafs directory, and the Java code in the 
121 src/JAVA/org/openafs/jafs/ directory.  Please reference the 
122 src/TechNotes-JavaAPI document for more information.
123