52ddd24af933bb7c7aeffa32c2cf702c6181354c
[openafs.git] / src / TechNotes-JavaAPI
1 Java API (Jafs): Technical Notes
2 -----------------------------------------
3
4 Overview
5 --------
6
7 The Java API (Jafs) is a Java package with a shared library
8 written in C.  It is meant for use by programmers who wish to develop
9 tools in Java for OpenAFS administration and use.  This document briefly
10 outlines the architecture of Jafs.
11
12 Shared library
13 --------------
14
15 The source code for the shared library resides in the src/JAVA/libjafs
16 directory.  See the JAFS_README file in that directory for information
17 on how to compile this package.  The code is broken up logically into
18 files by the type of AFS object they relate to (i.e. cell, user, volume, 
19 etc.), which closely mirrors the different classes of the Java package.
20 This library is built on top of the libadmin and libuafs libraries, and
21 mainly serves as a translation layer between the Java package and the
22 OpenAFS code.  It is closely tied to the Java package, in that it often
23 accesses the actual Java objects by calls up through JNI, in order to
24 retrieve or populate member fields of those objects. Also, if an error
25 occurs in this code or in another C library, a Java exception is 
26 constructed with the appropriate error code, and is thrown back to the 
27 Java layer to be dealt with.
28
29 In order to provide user-level functions such as ACL setting and mount
30 point iteration, the shared library needs to be linked with a specialized
31 version of libuafs called libjuafs.a. Please view the README file in the 
32 src/libuafs directory for more information regarding libjuafs and how it 
33 is built. 
34
35 Java package
36 ------------
37
38 The code for the org.openafs.jafs package resides in the 
39 src/JAVA/org/openafs/jafs/ directory.  It is broken into classes
40 in the same way that the OpenAFS file system breaks down into logical 
41 components: Cell, User, Group, Server, Partition, Volume, Process, Key,
42 Token, ACL, and File.  There are also classes for file input and
43 output streams, and specialized exception classes.
44
45 Publicly, the developer only has access to these objects and their
46 instance functions, which provide a solid, object-oriented view of
47 OpenAFS administration and use.  The first thing a programmer would do to
48 use this package in his or her code would be to construct a Token object by
49 giving it a cell name, a user name, and a password for that user.  From 
50 there, the programmer could easily construct a Cell object and then list, 
51 for example, all the servers in a cell, create a new user, move a volume to 
52 a different partition, etc.
53
54 When one of these objects is constructed, it does not actually create
55 the corresponding component in OpenAFS.  The object is supposed to
56 represent the object.  If the programmer wants to actually create a 
57 new user in OpenAFS, for example, he or she would construct a new User
58 object with the name of the user to create, and then explicitly call
59 the object's create method.  
60
61 When an object first accesses information about itself from OpenAFS
62 by calling down through JNI to the shared library, it saves the
63 information and will return it to the application on subsequent 
64 requests.  This minimizes the overhead of expensive JNI calls.  This
65 saved information can be updated to reflect the most current state of
66 OpenAFS by calling the objects refresh method.
67
68 There are usually two ways to list something: getting an array of the
69 names of the elements in the list, or getting an array of the actual
70 objects themselves.  For example, the Cell object can provide the
71 programmer with an array of the names of all users in the cell, or
72 an array of actual User objects, with relevant member fields already set
73 to the correct values. 
74
75 Almost every method in the package declares AFSException in its 
76 throws clause.  This is thrown from the shared library whenever an 
77 error occurs, and contains an OpenAFS error code as a member.  The 
78 programmer is expected to deal with these exceptions however they see fit.
79
80 The native methods that act as the interface between the Java layer and
81 the shared library are declared protected, so they can be used directly
82 by developers who wish to subclass these classes for their applications
83 and possibly implement their own versions of the Java API calls.
84
85 Known Issues
86 ------------
87
88 Some issues not yet dealt with in this API include:
89   - Alternative methods of authentication, other than Kaserver (i.e.
90     Kerberos V).  There has been some discussion about how to abstract
91     the User object to be more general, but so far it has not been 
92     implemented.
93   - Access to VLDB functionality such as listing VLDB entries and
94     zapping volumes.