Commit | Line | Data |
---|---|---|
805e021f CE |
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 |