| 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 | Java package |
| 30 | ------------ |
| 31 | |
| 32 | The code for the org.openafs.jafs package resides in the |
| 33 | src/JAVA/org/openafs/jafs/ directory. It is broken into classes |
| 34 | in the same way that the OpenAFS file system breaks down into logical |
| 35 | components: Cell, User, Group, Server, Partition, Volume, Process, Key, |
| 36 | Token, ACL, and File. There are also classes for file input and |
| 37 | output streams, and specialized exception classes. |
| 38 | |
| 39 | Publicly, the developer only has access to these objects and their |
| 40 | instance functions, which provide a solid, object-oriented view of |
| 41 | OpenAFS administration and use. The first thing a programmer would do to |
| 42 | use this package in his or her code would be to construct a Token object by |
| 43 | giving it a cell name, a user name, and a password for that user. From |
| 44 | there, the programmer could easily construct a Cell object and then list, |
| 45 | for example, all the servers in a cell, create a new user, move a volume to |
| 46 | a different partition, etc. |
| 47 | |
| 48 | When one of these objects is constructed, it does not actually create |
| 49 | the corresponding component in OpenAFS. The object is supposed to |
| 50 | represent the object. If the programmer wants to actually create a |
| 51 | new user in OpenAFS, for example, he or she would construct a new User |
| 52 | object with the name of the user to create, and then explicitly call |
| 53 | the object's create method. |
| 54 | |
| 55 | When an object first accesses information about itself from OpenAFS |
| 56 | by calling down through JNI to the shared library, it saves the |
| 57 | information and will return it to the application on subsequent |
| 58 | requests. This minimizes the overhead of expensive JNI calls. This |
| 59 | saved information can be updated to reflect the most current state of |
| 60 | OpenAFS by calling the objects refresh method. |
| 61 | |
| 62 | There are usually two ways to list something: getting an array of the |
| 63 | names of the elements in the list, or getting an array of the actual |
| 64 | objects themselves. For example, the Cell object can provide the |
| 65 | programmer with an array of the names of all users in the cell, or |
| 66 | an array of actual User objects, with relevant member fields already set |
| 67 | to the correct values. |
| 68 | |
| 69 | Almost every method in the package declares AFSException in its |
| 70 | throws clause. This is thrown from the shared library whenever an |
| 71 | error occurs, and contains an OpenAFS error code as a member. The |
| 72 | programmer is expected to deal with these exceptions however they see fit. |
| 73 | |
| 74 | The native methods that act as the interface between the Java layer and |
| 75 | the shared library are declared protected, so they can be used directly |
| 76 | by developers who wish to subclass these classes for their applications |
| 77 | and possibly implement their own versions of the Java API calls. |
| 78 | |
| 79 | Known Issues |
| 80 | ------------ |
| 81 | |
| 82 | Some issues not yet dealt with in this API include: |
| 83 | - Alternative methods of authentication, other than Kaserver (i.e. |
| 84 | Kerberos V). There has been some discussion about how to abstract |
| 85 | the User object to be more general, but so far it has not been |
| 86 | implemented. |
| 87 | - Access to VLDB functionality such as listing VLDB entries and |
| 88 | zapping volumes. |