The JFS Project

Introduction

JFS is a simple network filesytem protocol for java applets. Because applets cannot access the local storage of the machine they are running on, any applet that wants to load or save files needs some mechanism for accessing files on the web server from which the applet was loaded. JFS provides one way for applets to do this.

The JFS server is a java program that is run on the same host as a web server. JFS clients are java applets that conect back to the server on the host from which they were loaded via a TCP connection. Once the connection has been established and the client has authenticated itself, the client can make requests to do things like loading and saving files, creating directories and getting user information.

Starting the server

Included with this distribution is the source code and compiled .class files for the JFS server, which is written in Java. At the moment the server will only run on Unix systems, as it calls /bin/rmdir and /bin/ln to delete directories and to make symbolic links (which cannot yet be done in any portable way).

The JFS server should ideally be run on a host that is also running a web server, with the .class files from the distribution in some web accessible directory. JFS client applets can then be loaded from the web server, and connect back to the JFS server to load & save files. However you can run the JFS server on a machine without a web server if you like, and access all the client applets through file: URLs.

The JFS server uses a directory in the local filesystem of the machine on which it is run as the root directory for the JFS filesytem. Ownership and access rights for files in this 'virtual filesystem' are stored in a file called .jfs in each directory. The directory root in this distribution contains the basic files needed by the JFS filesystem, such as /etc/users and the /dev directory.

To start the JFS server on your machine, cd to the distribution directory and type:

java JFSserver ./root -

This will start the server on the directory root, with server log information written to the standard output. To have the server write log information to a file, replace the - above with a filename to append to. If no filename is given, logging information is written to the file server_log in the current directory.

Running JFS clients

Once you have a JFS server running, you can use a Java aware web browser such as Netscape 2 or Appletviewer to run the JFS client applets included in this distribution. When run, the applet will connect back to the JFS server on the host from which it was loaded (or the localhost if you are using a file: URL). The client applets included in this distribution are:

Text Editor
A very basic text editor that uses the AWT TextArea component to do the actual editing.
File Browser
A file manager for navigating around the filesystem and copying, renaming and deleting files. Double-clicking on a file for which there is a handler program for its MIME type will start that handler program in a separate window.
Image Editor
A basic painting program with line, circle, floodfill and other tools. Can only read and write PPM format at the moment.
Note - due to bugs in the Windows AWT implementation, this applet doesn't work too well on that platform.
Server Admin
A JFS client to simplify the administration of a JFS server, such as the creation of users and printers or the monitoring of server connections.
Web Loader
A small applet that uses the JFS server to load data from any URL, and save the data to a file on the server.

The applets on the web pages above will automatically log in to the JFS server as the user root (specified by parameters in the <applet> tag).

Technical details

The filesystem
The JFS filesystem is similar to that of most Unix systems, in that it has files, directories, users and groups. However, the JFS filesystem also supports :
- Access control lists
  Each file or directory has an arbitrary list of users and groups associated with it, each with read, write, and/or chmod permissions. A user not in the access control list for a file has no permissions for that file.
- Multiversion files
  A file can be either single-version (like Unix) or multi-version (sort of like VMS). All versions of a file can be copied, renamed or deleted together.
- MIME types
  Each file has a MIME type (like text/plain) to identify its contents. This can be used to run an appropriate handler program to view the contents of a file.
The access rights, version details and MIME types of the files in each JFS directory are stored in a file called .jfs in each directory in the local filesystem.
Local storage
The JFS server does not use the actual usernames or file permissions on the Unix host on which it is run. All the files and directories beneath the JFS server root can be owned by one local user, and should be readable and writable by the user the server is run as.
The organisation of the local files and directories under the JFS server root closely follows the layout of files and directories in the JFS filesystem. Each directory in the JFS filesystem has a corresponding local directory of the same name, and each single-version JFS file is stored in one local file of the same name. Multi-version files, however, use one local file for each version of the JFS file, named the same as the file but with a comma and the version number at the end. So version 2 of the file foobar would be stored as foobar,2. A soft-link always points from local file with the same name as the JFS file to the local file for the highest-numbered version.
The JFS protocol
The JFS server listens for TCP connections from clients on port 9888. Once a connection is made, the connection is kept active for the lifetime of the client, and all data transfer is done over that one connection (unlike HTTP). All communication over the connection is in the form of Messages, which are similar in format to HTTP requests. Each message consists of 1 or more headers, followed by a blank line and possibly some data.
Messages from client to server are called Requests, and messages from server to client Replys. Whenever a client program wants to load a file, authenticate itself or anything else a request is sent to the server, which responds with a reply indicating the success or failure of the request (and possibly containing some data). For example, to load a file a client might send :
Request: Get File: /tmp/foo
To which the server would reply :
Reply: Data Content-length: 12
hello world
The first request a client must send after connecting to a server is the Auth request, which contains a username and password. This authorises the client, so the server knows which files and directories it has access to.
The JFScomponent class
All the JFS client programs included in this distribution are classes derived from the JFScomponent class. A JFScomponent is subclass of the AWT canvas class, with additional methods that allow a user of the class to connect it to a JFS server, request loading of a file, and so on.
This means that any JFScomponent-derived object can be instantiated in an applet (as in the applets linked to above), or in a new top-level window (as the File Browser applet does when a filename is double-clicked on). Because Java allows loading of classes by name at runtime, a JFS client like the File Browser can use a mapping between MIME types and JFScomponent-derived classes to load a handler class to display a file.
Device drivers
Like the Unix filesystem, the JFS filesystem supports special files called devices. Device files are usually found in the /dev/ directory, and have the MIME type jfs/special. When a JFS client requests to read or write to a device file, the server loads by name a device driver class (which must be a subclass of DeviceDriver) and calls its read or write method. The name of the driver class is the same as the device file, but with "Device" appended.
Devices provide a (relatively) nice way for JFS clients to do things like printing or sending email through the server. The following device drivers are included in this distribution:
- /dev/Printer
  Data written to this device is printed on the server printer specified in the request headers. This printer must be defined in /etc/printers.
- /dev/Web
  When a Get request is sent to this device, the URL header is used to retrieve data from an arbitrary URL to return the the client.
- /dev/TCP
  When this device receives a Get request from a client, it connects to an arbitrary host and port given in the request headers and then opens a port to listen on. The client then connects to that port, and the device transparently passes through all data between the client and the remote host.
- /dev/Server
  This device provides a way for a client to get and set various server state information and options. Currently it is used only by the Server Admin client.
Properties
The JFS server stored a list of properties, each uniquely identified by a name and owner. Properties can be used to store server configuration options, user preferences or server status information. Properties can be either persistant (such as server configuration), or transient (such as the number of bytes sent by the server). Persistant properties are stored in the JFS file /etc/properties.
A property may only be read or written by its owner (or root). Any client program can create, retreive or delete properties belonging to the user the client is connected as, using the Setprop, Getprop and Delprop requests.

For more details on writing JFS clients, see the JFS web page, the JFSclient docs, and the JFScomponent docs.

Practical uses

Any applet that needs to write state information back to the server from which it was loaded can make use of JFS. Also, applets wanting to get data from arbitarary URLs or make connections to arbitrary hosts can use the JFS devices /dev/Web and /dev/TCP.

One quite useful application of JFS is the creation of web pages entirely through the web. If the server root directory is somewhere web-accessible, JFS users can create HTML and text files using the text editor applet without having to leave their web browser. See http://www.focus-asia.com/ for an example of this.

To do...

Write classes for loading and saving GIF format images, so the Image Editor component can support something other than PPM.
Add support for symbolic links to the server. A file could be a link either to another file, or possibly to an arbitrary URL.
Add requests for locking of files on the server.
Possibly create some kind of support for remote mounting of one JFS server by another, like NFS.

Bugs and problems

Speed. Loading JFS client applets over even a fast modem is still rather slow. Apart from reducing the size of the .class files, there isn't much I can do about this.
The Windows 95/NT implementations of the java AWT have a bug that causes custom components to sometimes be drawn in the wrong place. This is particularly noticable when an applet contains many such components, such as the JFS image editor.
The JFS server, although written in Java, only works on Unix systems at the moment. This is because there is no support in Java for removing directories or creating symbolic links, which the server needs to do. Instead, it calls /bin/rmdir and /bin/ln to do these operations.
For reasons unknown to me, if a JFS client running under Netscape requests a large file from the server (around 10k), then it hangs part way though reading the reply. This doesn't happen if the client applet is run under Appletviewer, and doesn't seem to affect the transfer of large files from client to server. However, I have worked around this bug by making clients request files in 8k chunks instead of getting the whole file with one request.