syntax fix
[openafs-wiki.git] / 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