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.