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 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.