The JFSclient Class

The JFSclient class provides an easy way for a java program or applet to talk to a JFS server. It has methods for the various JFS requests such as loading and saving files, getting user information and writing to device drivers. The JFSclient class also makes use of the RequestException class (thrown when an error occurs in a request), and the CutBuffer class.


Methods

JFSclient(String host) throws IOException
Connect to the JFS server on the given host, or throw an exception if something goes wrong.

JFSclient newclient() throws RequestException
Returns a new JFSclient object, connected to the same server. If the object this method was called on was already authenticated with the server, then the newly returned client object will be too. The old and new objects will share the same cut buffer, so that you can cut and paste between two JFS clients launched from the file browser (for example).

void close()
Break the connection to the JFS server. Attempting to call any client methods after this will generate an exception.

void auth(String name, String pass) throws RequestException
After a JFS client has connected to a JFS server and before it can perform any operations like loading and saving, the client must authenticate itself. Java programs using the JFSclient class should call this method with a valid username and password before calling get, put, etc..

JFSdirectory getdir(String path) throws RequestException
Returns a JFSdirectory object containing information about the files in the given directory. If the directory is inaccessible for some reason, then an exception is thrown.

JFSfile statfile(String path) throws RequestException
Returns a JFSfile object for the given file on the JFS filesystem. If the directory the file is in cannot be accessed, an exception is thrown.

byte []get(String path, int ver) throws RequestException
The get method allows a JFS client program to load a file from the server. Given a file pathname and version number, this method will return an array of bytes containing the data from the file (or throw an exception if something goes wrong). For single-version files, the version number parameter must be a valid version for the given file, or 0 to load the highest-numbered version.

byte []getsect(String path, int ver, int st, int en) throws RequestException
Returns a sub-section of the given file and version, starting at byte st and ending at en.

Message devget(String file, Message head) throws RequestException
This method allows client program that want to read from server device drivers to pass extra parameters to the device. Calling code should create a Message object and add to it any special headers needed for making requests from the given device. The message returned from the devget call can also be examined to extract special headers returned in the reply from the device driver. For example :
try {
	Message head = new Message();
	head.add("URL", "http://www.foo.com/bar.html");
	Message reply = client.devget("/dev/Web", head);
	String type = reply.find("Content-type");
	byte data[] = reply.getdata();
	}
catch(RequestException e)
	// error handling here

void put(String path, int ver, byte data[], String type) throws RequestException
Writes to the given file the data in the data array. If this file does not already exist, then it is created and it's MIME type set to the given type. If the file already exists and is a multi-version file, then the ver parameter determines which version of the file to save the data in. If the version already exists it is overwritten, otherwise a new version is created. If the file does not exist, then the ver parameter determines if the newly created file is multiversion (if ver is non-zero) or single-version (if ver is 0).

void devput(String file, byte d[], Message head) throws RequestException
Like the devget method, this allows client programs to write to server device drivers with special headers in the request. Calling code should create a Message object and add to it the headers that need to be passed to the device, then call this this method with a device filename, data to send and the Message object. For example :
try {
	Message head = new Message();
	head.add("Printer", "hp1600c");
	byte somedata[] = somefunc();
	client.devput("/dev/Printer", somedata, head);
	}
catch(RequestException e)
	// error handler here
    

String gethandler(String typestr) throws RequestException
A handler is a JFS class capable of loading and displaying files of one or more MIME types. A handler class is always a subclass of JFScomponent and so must define the load, print, and connect methods (among others). The mapping between handlers and MIME types is stored in the file /etc/programs, which this method reads to find the name of the handler class for the given type. Calling code should use the Class.forName method to get the Class object for the returned class string. For example :
try {
	String name = client.gethandler("text/plain");
	Class nameclass = Class.forName(name);
	JFScomponet handler = (JFScomponent)nameclass.newInstance();
	handler.connect(client);
	// more stuff here
	}
catch(Exception e)
	// lots of error handling
    

void getprograms(Vector p, Vector t) throws RequestException
A program is a subclass JFScomponent that has an optional MIME type (or types) associated with it. Programs with associated MIME types are called handlers (see gethandler), such as the TextEditComponent class. This method fills the Vector p with the names of all programs from /etc/programs, and the Vector t with the MIME type supported by each program (such as image/gif or text/*), or null if the program does not support any MIME type.

void getprinters(Vector name, Vector type, Vector desc, Vector cmd) throws RequestException
A JFS server can have connected printers, which JFS client programs can use. The list of connected printers is stored in the file /etc/printers, which this method reads and parses. Each printer has a short name (like hp1600c), a type (text or postscript), a description (like HP 1600CM Inkjet) and a print command (like lpr -Php). This information is placed in the Vectors name, type, desc and cmd respectively.

void delete(String file, int v) throws RequestException
Deletes a file (or a version of a file) from the server. If the v parameter is 0, all versions of the given file are deleted. If v is non-zero (and the file is multiversion) only the version given is removed. If the filename given is actually a directory, then the directory and everything in it is deleted.

void mkdir(String dir) throws RequestException
Creates the given directory in the server filesystem.

void copy(String src, String dst) throws RequestException
The copy method copies all version of the file src to the file dst, overwriting it if it already exists. This function only works on files, not directories.

JFSuser uinfo(String u) throws RequestException
Returns a JFSuser object containing information about the given user. If the u parameter is null, the name of the user this client is connected to the server as is used. If u is non-null, information about the named user is returned. Note that the password field of the returned object will be set to an empty string (for obvious reasons!).

Vector ulist() throws RequestException
Returns a Vector of JFSuser objects, one for each user on the server. The details of users are stored in the file /etc/users, which is readable and writable only by the root user. This method (and uinfo) provide a way for user client programs to get information about users.

Vector ginfo(String g) throws RequestException
Returns a Vector containing the names of all users belonging to the given group. Groups are used to control access to files in the filesystem, as explained below.

void chmod(String f, String u, String p) throws RequestException
Each file stored in the server filesystem has a list of access rights defining which users and groups can access the file, and what they can do to it. For each user or group for whom an access right is defined, there is a permissions string that contains some or all of the characters r, w and p. The user root can do anything to any file, even if root is not in the access rights list for a file. The group all implicity contains all users, even if all is not in the list of groups for a user.

The chmod function allows a JFS client to add, delete or change an access right for a file or directory. The f parameter should contains the name of a file or directory, and the u parameter the name of a user or group. If the p parameter is null, then the access rights for the given user to the given file are removed. If p is non-null, it is taken to be a permissions string like "rwp" or "r", and these permissions are granted to the given user for the given file, overwriting any existing permissions for that user.

ServerProperty getprop(String name, String user)
A property in the JFS system is a name / username pair that maps to some string. What this means is that each property has a name, is owned by some user and contains some text. Properties can be used to store user preferences, server configuration information and other things. For example, the "Client Timeout" property (owned by root) contains the minimum number of seconds the server will wait before disconnecting an inactive client. Properties can only be read and written by their owner, and by the root user.

This method returns the ServerProperty object for the given name and username. If the user parameter is null, the name of the user this client is connected as is used. If an error occurs or the property does not exist, null is returned instead.

void putprop(ServerProperty p)
Writes the given property to the server. If the user field of p is null, the name of the user this client is connected as is used.

void delprop(String name, String user)
Deletes the property stored under the given name and username. If the user parameter is null, then the name of the user this client is connected as is used.

void rename(String src, String dst) throws RequestException
Renames the file src to dst, possibly replacing any existing file called dst. Files can be renamed into different directories, but directories cannot be renamed.

void purge(String file) throws RequestException
Like the VMS purge command, deletes all versions of the given file except for the latest. This can only be performed on multi-version files.

void chtype(String file) throws RequestException
The chtype method changes the MIME type of the given file. It is the client programmers responsibility to make sure that this type is valid for the data in the file.

Message send(String req, Message m) throws RequestException
The send method is for the user of programs that need complete control over the requests and replys between client and server. The req parameter should contain a valid request name, such as "Get" or "Uinfo", and the m parameter the headers (and possibly data) to be sent in the request. If no error occurs, the complete reply from the server will be returned.

boolean canaccess(String file, char p) throws RequestException
A convenience function for checking if the user this client is connected as can access the given file or directory. The p parameter gives the type of access to check for, either r, w or p.

void setcurrent(String full) throws RequestException
Each JFSclient object maintains a current directory, current filename and current MIME type for the last file loaded or saved. These are used by classes like FileReq to keep track of which directory the user is in between opening and closing a file requestor. This method sets the current directory and filename from the path given in the full parameter, and the current MIME type from information about the file obtained from the JFS server. Programs using this class should call this method after successfully loading data from the server.

void setcurrent(String full, String type)
This method is like the one above, but requires that the MIME type for the given pathname be provided as well. This should be called in favour of the above function if the calling code knows the type of the file, such as after the successful saving of a file.

void setbuf(Object o)
Each JFSclient object has an associated cut buffer for storing selections from copy or cut operations. If the newclient method is used to create a new JFSclient from an old one, the cut buffer will be shared between the new client and the old.

This method should be used to store data of some type (such as a String or Image object) into the cut buffer for a client.

Object getbuf()
Returns the object currently in the cut buffer for this client. Calling code should use the instanceof operator to check the type of the returned object, and then if usable cast it to the needed type.


Fields

String serverhost
The hostname of the JFS server this client is connected to.

String authname
The JFS username this client is logged onto the server as, or null if the client is not yet logged on.

String authpass
The JFS password this client used to log onto the server, or null.

currentdir
The full pathname of the last directory a file was loaded or saved from.

currentfile
The name of the last file loaded or saved.

currenttype
The type of the last file loaded or saved.