Document Contents:

- Introduction

- Requirements

- Overview

- Architecture

- Class Descriptions


  


Extended Filesystem API




Introduction

Demand for distributed file system protocols, such as the WebNFSTM protocol, is coming from several areas. Network computer vendors have realized that network file systems can add a powerful capability to their products. Experienced JavaTM application developers want access to all the files the Internet has to offer in the same way. To meet this demand, several vendors are working on distributed file systems, such as WebNFS, CIFS, and others.

This document describes the Extended Filesystem API. The API provides a common interface for multiple file system types. Also, it allows for dynamic loading of file system implementations. The API includes a set of classes that are similar to those found in the java.io classes, and therefore provides a familiar programmatic means of accessing files, either locally or remotely. The API also provides a means to access file and file system specific information.

Status

The Extended Filesystem API is an evolving specification and is subject to change.

Requirements

The model requires the following:

  • The extensions must be file system neutral.
  • The model must support access to multiple file systems.
  • The model must be extensible to support custom features of new file systems.
  • The model must support file system identification and naming through URLs.
  • The model must provide java.io.File type access to developers to facilitate migration of existing applications.

Overview

The extended file system provides extensibility through the use of:

  • An XFileAccessor interface that provides a common set of access methods that are required for all file systems.
  • An XFileExtensionAccessor abstract class that provides direct access to file system-specific features.
  • The ability for automatic runtime selection of the file access mechanism.
  • Support for multiple file name spaces through URL naming.

The API defines two means of access to network files and file systems:

  • An XFile class that supports naming of files with URLs such as the type proposed in the NFS URL Scheme. Here users would specify URLs like "nfs://oaktree.edu/archie". Developers of other file systems would register their own URL schemes and implement file system accessor classes to support a chosen file system type, such as "smb://www.microsoft.com/index.html". The XFile class also provides a default "native" URL scheme using java.io.* which has a file naming syntax that varies according to the operating system that supports the Java Runtime Interface, such as Win95, UNIX, and VMS.

  • Access to data through the XFileInputStream, XFileOutputStream, XRandomAccessFile, XFileReader and XFileWriter classes that are similar to classes that exists today in the JDK.

The API supports three categories of applications:

  • Web-based applications, specifically browsers that deal with URLs extensively.

  • Traditional file-based applications that must extend their access to the network and still use the style of access provided by java.io.File classes.

  • Mixed mode applications that use both remote and distributed file systems.

Architecture

The following picture shows the extended file system architecture. The XFile (com.sun.xfile.*) layer of the architecture mirrors the standard java.io.File* programmatic interfaces. Under this layer is a set of XFileAccessors. There is one XFileAccessor interface implementation for each file system being supported. Currently only NFS, file URLs, and native file systems are supported. The accessors implement the XFileAccessor interface. They are responsible for all aspects of file access. The API classes are responsible for multiplexing between the different file systems as requests are made from the application.

Support for dynamic loading of file system classes is included in this release. Please refer to WebNFS XFileAccessor Interface Reference.

Extended Filesystem Architecture
Java Application
com.sun.xfile.*
nfs: cifs: file: native:

URL Naming

Every file system type is identified by a URL of general form described in RFC 1738. The extended file system uses the scheme name in the URL to provide for the automatic selection of a file system. For example, the NFS file system has a scheme name "nfs". When presented with a filename string, the extended file system checks for a URL scheme followed by a colon at the beginning of the string. If it finds one it uses the file system accessor class associated with that URL scheme. If it does not find one, it defaults to the "native" scheme for access through java.io.*.

URL Names and Native Names

File names are assumed to be absolute URLs or relative URLs as determined by a context. If a filename string begins with a valid URL scheme name followed by a colon, then the name is associated with the file system type indicated by the URL scheme name. For instance, a filename string of the form "nfs://hostname/path" is associated with the file system that has the scheme name of "nfs". If the filename has no colon-separated prefix, or the scheme is is not recognized then the name is assumed to belong to the default "native" scheme, that is a URL prefix of "native:" is assumed and the name is handled by java.io.*.

The two argument constructor for XFile takes an XFile object and a filename: XFile(XFile dir, String filename). The filename argument is interpreted according to the context set by the dir argument. The dir argument is used as a base URL and the name is evaluated as a relative URL. If the filename is an absolute URL then the dir is ignored. If the filename is a relative URL then it is combined with the base URL to form the name of the new XFile object. The rules that describe the evaluation of relative URLs are described in RFC 1808.

File System Selection

File systems are selected using these rules:

  1. If the XFile(String filename) constructor is used and the filename has a prepended URL scheme, the file system associated with that scheme is used; otherwise, the native file system is used.

  2. If the XFile(XFile dir, String filename) constructor is used, the filename is evaluated as a relative URL to the dir XFile.

File System Registration

The file system registration mechanism is dynamic. The classes will search for a file system factory based on the file system name specified in the URL. This factory produces XFileAccessors. The name of the file system must be a unique URL scheme.

A list of available file systems can be generated by calling the static method "String[] getFileSystemName()", which returns an array of strings, with each string containing a name of an available file system.

Examples of File Name Usage and File System Selection

    XFile f1 = new XFile("nfs://hostname/directory1");
    // NFS file based on an absolute URL

    XFile f2 = new XFile("file.txt");
    // not a URL, so defaults to the current directory of the "native" file system

    XFile f4 = new XFile(f1,"text.html");
    // evaluated relative to the base URL of f1 - which is "nfs".

One point to be made from these examples is that the validity of a constructed XFile is made when the XFile is used, not when it is constructed. This is consistent with the java.io.File class.

Direct Access to File System-Specific Features

A reference to the object implementing a file system's specific features can be determined through the class interface. The interface allows developers to directly call these methods. By doing this, you are increasing the risk of writing code that works only for one file system type so its use is discouraged. To obtain access to these features directly, use the public method "XFileExtensionAccessor XFile.getExtensionAccessor()". Once you have obtained this handle, you can access its methods directly. Refer to the file system implementors documentation for class description details.

The following example shows how a method in the NFS ExtensionAccessor is used to set the user's authentication credentials using the NFS PCNFSD protocol:
import java.io.*;
import com.sun.xfile.*;
import com.sun.nfs.*;

public class nfslogin {
    
   public static void main(String av[])
   {
      try {
         XFile xf = new XFile(av[0]);

         nfsXFileExtensionAccessor nfsx = 
	    (nfsXFileExtensionAccessor) xf.getExtensionAccessor();

	 if (! nfsx.loginPCNFSD("pcnfsdsrv", "bob", "-passwd-")) {
	    System.out.println("login failed");
	    return;
	 }
    
         if (xf.canRead())
	    System.out.println("Read permission OK");
	 else
	    System.out.println("No Read permission");

      } catch (Exception e) {
         System.out.println(e.toString());
         e.printStackTrace(System.out);
      }
   }
}

Class Descriptions

This section describes the additional methods that are not currently part of the java.io classes. For example, the first entry, called Xfile, describes the methods that are in the com.sun.xfile.XFile class but not in the java.io.File class. All com.sun.xfile classes that have a counterpart in the java.io classes are generally a superset of the java.io classes in the methods provided, not including constructors. File descriptors are not supported and constructors that use a java.io.File* class now use a com.sun.xfile.XFile* class. Also shown are the few new interfaces and classes defined by the extended file system. A complete description of the API can be found in the javadoc files included in the release.

XFile - Counterpart Is java.io.File

  • public XFile(String url) - class constructor
  • public XFile(XFile dir, String relurl) - class constructor

XFileOutputStream - Counterpart Is FileOutputStream

  • public XFileOutputStream(XFile file) - class constructor

XFileInputStream - Counterpart Is FileInputStream

  • public XFileOutputStream(XFile file) - class constructor

XRandomAccessFile - Counterpart Is RandomAccessFile

  • public XRandomAccessFile(XFile file, String mode) - class constructor

XFilenameFilter - Counterpart Is FilenameFilter

  • public abstract boolean accept(XFile dir, String name) - filter based on file spec

XFileReader - Counterpart Is FileReader

  • XFileReader(XFile file)

XFileWriter- Counterpart Is FileWriter

  • XFileWriter(XFile file, String access)

File Interface Examples

Extending existing programs to network file systems should be straight forward using the extensions provided. You simply replace declarations of type java.io.FileXYZ with the counterpart java.io.XFileXYZ. The following are a few simple examples of applications that use the APIs.

Example #1 - Using Streams Interface

import java.io.*;
import java.net.*;
import com.sun.xfile.*;

XFile xf = new XFile("file.txt");
if (xf.isFile()) {
    System.out.println("file is file");
}

if (xf.isDirectory()) {
    System.out.println("file is directory");
}

XFileInputStream nfis = null;
nfis = new XFileInputStream(xf);

for (int count = 0; ; count++) {
    int val = (byte) nfis.read();
    if (val == -1)
        break;
    System.out.write(val);
}

System.out.println("read " + count + " bytes ");

Example #2 - Using XRandomAccessFile Interface

import java.io.*;
import java.net.*;
import com.sun.xfile.*;

// create connection to host

XFile xf = new XFile("nfs://ian/simple.html");

XRandomAccessFile xraf = new XRandomAccessFile(xf,"r");

int count = 10;

xraf.seek(count);
System.out.println("Value at position " + count
    + " is " + (byte)xraf.read());
System.out.println("Current file position is "
    + xraf.getFilePointer());

xraf.seek(0);
for (count = 0 ; count < 100 ; count++) {
    int val = xraf.read();
    if (val == -1)
        break;
    System.out.print(val);
}

Last modified: July 29, 1998

Copyright 1994-1999 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, CA 94303 USA. All Rights Reserved.