Import Upstream version 1.8.5

[hcoop/debian/openafs.git] / src / TechNotes-JavaAPI

Java API (Jafs): Technical Notes
-----------------------------------------

Overview
--------

The Java API (Jafs) is a Java package with a shared library
written in C.  It is meant for use by programmers who wish to develop
tools in Java for OpenAFS administration and use.  This document briefly
outlines the architecture of Jafs.

Shared library
--------------

The source code for the shared library resides in the src/JAVA/libjafs
directory.  See the JAFS_README file in that directory for information
on how to compile this package.  The code is broken up logically into
files by the type of AFS object they relate to (i.e. cell, user, volume, 
etc.), which closely mirrors the different classes of the Java package.
This library is built on top of the libadmin and libuafs libraries, and
mainly serves as a translation layer between the Java package and the
OpenAFS code.  It is closely tied to the Java package, in that it often
accesses the actual Java objects by calls up through JNI, in order to
retrieve or populate member fields of those objects. Also, if an error
occurs in this code or in another C library, a Java exception is 
constructed with the appropriate error code, and is thrown back to the 
Java layer to be dealt with.

Java package
------------

The code for the org.openafs.jafs package resides in the 
src/JAVA/org/openafs/jafs/ directory.  It is broken into classes
in the same way that the OpenAFS file system breaks down into logical 
components: Cell, User, Group, Server, Partition, Volume, Process, Key,
Token, ACL, and File.  There are also classes for file input and
output streams, and specialized exception classes.

Publicly, the developer only has access to these objects and their
instance functions, which provide a solid, object-oriented view of
OpenAFS administration and use.  The first thing a programmer would do to
use this package in his or her code would be to construct a Token object by
giving it a cell name, a user name, and a password for that user.  From 
there, the programmer could easily construct a Cell object and then list, 
for example, all the servers in a cell, create a new user, move a volume to 
a different partition, etc.

When one of these objects is constructed, it does not actually create
the corresponding component in OpenAFS.  The object is supposed to
represent the object.  If the programmer wants to actually create a 
new user in OpenAFS, for example, he or she would construct a new User
object with the name of the user to create, and then explicitly call
the object's create method.  

When an object first accesses information about itself from OpenAFS
by calling down through JNI to the shared library, it saves the
information and will return it to the application on subsequent 
requests.  This minimizes the overhead of expensive JNI calls.  This
saved information can be updated to reflect the most current state of
OpenAFS by calling the objects refresh method.

There are usually two ways to list something: getting an array of the
names of the elements in the list, or getting an array of the actual
objects themselves.  For example, the Cell object can provide the
programmer with an array of the names of all users in the cell, or
an array of actual User objects, with relevant member fields already set
to the correct values. 

Almost every method in the package declares AFSException in its 
throws clause.  This is thrown from the shared library whenever an 
error occurs, and contains an OpenAFS error code as a member.  The 
programmer is expected to deal with these exceptions however they see fit.

The native methods that act as the interface between the Java layer and
the shared library are declared protected, so they can be used directly
by developers who wish to subclass these classes for their applications
and possibly implement their own versions of the Java API calls.

Known Issues
------------

Some issues not yet dealt with in this API include:
  - Alternative methods of authentication, other than Kaserver (i.e.
    Kerberos V).  There has been some discussion about how to abstract
    the User object to be more general, but so far it has not been 
    implemented.
  - Access to VLDB functionality such as listing VLDB entries and
    zapping volumes.