java.io.File

The java.io.File class encapsulates access to information about a file or directory entry in the filesystem. It gets attribute information about a file, lists the entries in a directory, and performs basic filesystem operations like removing a file or making a directory. While the File object handles these tasks, it doesn't provide direct access for reading and writing file data; there are specialized streams for that purpose.

File fooFile = new File( "/tmp/foo.txt" ); 
File barDir = new File( "/tmp/bar" ); 

File f = new File( "foo" ); 

File fooFile = new File( "/tmp", "foo.txt" ); 

File tmpDir = new File( "/tmp" ); 
File fooFile = new File ( tmpDir, "foo.txt" ); 

// We'll use forward slash as our standard 
String path = "mail/1995/june/merle"; 
path = path.replace('/', File.separatorChar); 
File mailbox = new File( path ); 

String [] path = { "mail", "1995", "june", "merle" }; 
  
StringBuffer sb = new StringBuffer(path[0]); 
for (int i=1; i< path.length; i++) 
    sb.append( File.separator + path[i] ); 
  File mailbox = new File( sb.toString() ); 

File fooFile = new File( "/tmp/boofa" ); 
 
String type = fooFile.isFile() ? "File " : "Directory "; 
String name = fooFile.getName(); 
long len = fooFile.length(); 
System.out.println(type + name + ", " + len + " bytes " ); 

String [] files = fooFile.list(); 

File Streams

Java provides two specialized streams for reading and writing files in the filesystem: FileInputStream and FileOutputStream. These streams provide the basic InputStream and OutputStream functionality applied to reading and writing the contents of files. They can be combined with the filtered streams described earlier to work with files in the same way we do other stream communications.

Because FileInputStream is a subclass of InputStream, it inherits all standard InputStream functionality for reading the contents of a file. FileInputStream provides only a low-level interface to reading data, however, so you'll typically wrap another stream like a DataInputStream around the FileInputStream.

You can create a FileInputStream from a String pathname or a File object:

FileInputStream foois = new FileInputStream( fooFile ); 
FileInputStream passwdis = new FileInputStream( "/etc/passwd" ); 

When you create a FileInputStream, Java attempts to open the specified file. Thus, the FileInputStream constructors can throw a FileNotFoundException if the specified file doesn't exist, or an IOException if some other I/O error occurs. You should be sure to catch and handle these exceptions in your code. When the stream is first created, its available() method and the File object's length() method should return the same value. Be sure to call the close() method when you are done with the file.

To read characters from a file, you can wrap an InputStreamReader around a FileInputStream. If you want to use the default character encoding scheme, you can use the FileReader class instead, which is provided as a convenience. FileReader works just like FileInputStream, except that it reads characters instead of bytes and wraps a Reader instead of an InputStream.

The following class, ListIt, is a small utility that displays the contents of a file or directory to standard output:

import java.io.*; 
 
class ListIt { 
    public static void main ( String args[] ) throws Exception { 
        File file =  new File( args[0] ); 
 
        if ( !file.exists() || !file.canRead() ) { 
            System.out.println( "Can't read " + file ); 
            return; 
        } 
 
        if ( file.isDirectory() ) { 
            String [] files = file.list(); 
            for (int i=0; i< files.length; i++) 
                System.out.println( files[i] ); 
        } 
        else 
            try { 
                FileReader fr = new FileReader ( file );
                BufferedReader in = new BufferedReader( fr );
                String line;
                while ((line = in.readLine()) != null)
                    System.out.println(line);
            } 
            catch ( FileNotFoundException e ) {
                System.out.println( "File Disappeared" ); 
            }
    } } 

ListIt constructs a File object from its first command-line argument and tests the File to see if it exists and is readable. If the File is a directory, ListIt prints the names of the files in the directory. Otherwise, ListIt reads and prints the file.

FileOutputStream is a subclass of OutputStream, so it inherits all the standard OutputStream functionality for writing to a file. Just like FileInputStream though, FileOutputStream provides only a low-level interface to writing data. You'll typically wrap another stream like a DataOutputStream or a PrintStream around the FileOutputStream to provide higher-level functionality. You can create a FileOutputStream from a String pathname or a File object. Unlike FileInputStream however, the FileOutputStream constructors don't throw a FileNotFoundException. If the specified file doesn't exist, the FileOutputStream creates the file. The FileOutputStream constructors can throw an IOException if some other I/O error occurs, so you still need to handle this exception.

If the specified file does exist, the FileOutputStream opens it for writing. When you actually call a write() method, the new data overwrites the current contents of the file. If you need to append data to an existing file, you should use a different constructor that accepts an append flag, as shown here:

FileInputStream foois = new FileInputStream( fooFile ); 
FileInputStream passwdis = new FileInputStream( "/etc/passwd" ); 

Antoher alternative for appending files is to use a RandomAccessFile, as I'll discuss shortly.

To write characters (instead of bytes) to a file, you can wrap an OutputStreamWriter around a FileOutputStream. If you want to use the default character encoding scheme, you can use the FileWriter class instead, which is provided as a convenience. FileWriter works just like FileOutputStream, except that it writes characters instead of bytes and wraps a Writer instead of an OutputStream.

The following example reads a line of data from standard input and writes it to the file /tmp/foo.txt:

String s = new BufferedReader( new InputStreamReader( System.in ) ).readLine(); 
 
File out = new File( "/tmp/foo.txt" ); 
FileWriter fw = new FileWriter ( out ); 
PrintWriter pw = new PrintWriter( fw, true ) 
pw.println( s ); 

Notice how we have wrapped a PrintWriter around the FileWriter to facilitate writing the data. To be a good filesystem citizen, you need to call the close() method when you are done with the FileWriter.

java.io.RandomAccessFile

The java.io.RandomAccessFile class provides the ability to read and write data from or to any specified location in a file. RandomAccessFile implements both the DataInput and DataOutput interfaces, so you can use it to read and write strings and Java primitive types. In other words, RandomAccessFile defines the same methods for reading and writing data as DataInputStream and DataOutputStream. However, because the class provides random, rather than sequential, access to file data, it's not a subclass of either InputStream or OutputStream.

You can create a RandomAccessFile from a String pathname or a File object. The constructor also takes a second String argument that specifies the mode of the file. Use "r" for a read-only file or "rw" for a read-write file. Here's how to create a simple database to keep track of user information:

try { 
    RandomAccessFile users = new RandomAccessFile( "Users", "rw" ); 
    ... 
} 
catch (IOException e) {  
} 

When you create a RandomAccessFile in read-only mode, Java tries to open the specified file. If the file doesn't exist, RandomAccessFile throws an IOException. If, however, you are creating a RandomAccessFile in read-write mode, the object creates the file if it doesn't exist. The constructor can still throw an IOException if some other I/O error occurs, so you still need to handle this exception.

After you have created a RandomAccessFile, call any of the normal reading and writing methods, just as you would with a DataInputStream or DataOutputStream. If you try to write to a read-only file, the write method throws an IOException.

What makes a RandomAccessFile special is the seek() method. This method takes a long value and uses it to set the location for reading and writing in the file. You can use the getFilePointer() method to get the current location. If you need to append data on the end of the file, use length() to determine that location. You can write or seek beyond the end of a file, but you can't read beyond the end of a file. The read methods throws a EOFException if you try to do this.

Here's an example of writing some data to our user database:

users.seek( userNum * RECORDSIZE ); 
users.writeUTF( userName ); 
users.writeInt( userID ); 

One caveat to notice with this example is that we need to be sure that the String length for userName, along with any data that comes after it, fits within the boundaries of the record size.

Applets and Files

For security reasons, applets are not permitted to read and write to arbitrary places in the filesystem. The ability of an applet to read and write files, as with any kind of system resource, is under the control of a SecurityManager object. A SecurityManager is installed by the application that is running the applet, such as an applet viewer or Java-enabled Web browser. All filesystem access must first pass the scrutiny of the SecurityManager. With that in mind, applet-viewer applications are free to implement their own schemes for what, if any, access an applet may have.

For example, Sun's HotJava Web browser allows applets to have access to specific files designated by the user in an access-control list. Netscape Navigator, on the other hand, currently doesn't allow applets any access to the filesystem.

It isn't unusual to want an applet to maintain some kind of state information on the system where it's running. But for a Java applet that is restricted from access to the local filesystem, the only option is to store data over the network on its server. Although, at the moment, the Web is a relatively static, read-only environment, applets have at their disposal powerful, general means for communicating data over networks, as you'll see in Chapter 9, Network Programming. The only limitation is that, by convention, an applet's network communication is restricted to the server that launched it. This limits the options for where the data will reside.

The only means of writing data to a server in Java is through a network socket. In Chapter 9, Network Programming we'll look at building networked applications with sockets in detail. With the tools of that chapter it's possible to build powerful client/server applications.