Creating File Objects

You have a choice of four constructors for creating File objects. The simplest accepts a String object as an argument that specifies a path for a file or a directory. For example, you could write the statement:

File myDir = new File("C:/j2sdk1.4.0/src/java/io");

This creates a File object encapsulating the path C:/j2sdk1.4.0/src/java/io. On my system, this happens to be the path to the directory, io, containing the classes in the java.io package. On the various flavors of the Microsoft Windows operating system, you can also use an escaped back slash separator, \\, when you define a path, instead of /, if you wish, but paths do tend to look rather busy if you do. For instance:

File myDir = new File("C:\\jdk1.4\\src\\java\\io");

It also requires more typing.

Note that the File class constructor here does not check the string that you pass as the argument in any way, so there is no guarantee that a File object encapsulates a valid representation of a path on your system at all. For instance, this will compile and execute perfectly well:

File junk = new File("dwe\n:;?cc/.*\naa£%)(");  // Not a valid path! 

The argument to the constructor here does not define a valid file or directory path – at least not under any operating system that I am familiar with – but that statement compiles and executes. We can therefore deduce that you can pass any string as an argument to the File class constructor. It is up to you to ensure that it is valid for your system.

To specify a pathname to a file, you just need to make sure that the string that you pass as an argument to the constructor does refer to a file, and not a directory. For example, the statement:

File myFile = new File("C:/j2sdk1.4.0/src/java/io/File.java");

sets the object, myFile, to correspond to the source file for the definition of the class, File.

An important and easily overlooked characteristic of File objects is that they are immutable. Once you have created a File object you cannot change the path it encapsulates. We will see later that you can change the name of the physical file it references by using the rename() method belonging to the File object, but this will not change the File object itself. The File object will still encapsulate the original path so that once the file name has been changed the path encapsulated by the File object will no longer refer to an existing file. This can be confusing if you don't realize this is the case. Using this File object to test whether the file exists, for instance, will return false.

You can also create a File object that represents a pathname for a file by using a constructor that allows you to specify the directory that contains the file and the file name separately. The directory that contains the file is usually referred to as the parent directory. There are two constructors that allow you to do this, providing you with a choice as to how you specify the parent directory. In one, the first argument is a reference to a File object that encapsulates the path for the directory containing the file. In the other, the first argument specifies the parent directory path as a String object. The second argument in both cases is a String object identifying the file name.

For example, on my system, I can identify the Java source file for the File class with the statements:

File myDir = new File("C:/j2sdk1.4.0/src/java/io");  // Parent directory
File myFile = new File(myDir, "File.java");         // The path to the file

The first statement creates a File object that refers to the directory for the package io, and the second statement creates a File object that corresponds to the file, File.java, in that directory.

We could use the second of the two constructors to achieve the same result as the previous two statements:

File myFile = new File("C:/j2sdk1.4.0/src/java/io", "File.java");

Using a File object to specify the directory is much more useful than using a string directly. For instance, you can verify that the directory does really exist before attempting to access the file or files that you are interested in. You can also create the directory if necessary, as we shall see.

The fourth constructor allows you to define a File object from an object of type URI that encapsulates a Uniform Resource Identifier, commonly known as a URI. As you are undoubtedly aware, a URI is used to reference a resource on the World Wide Web and the most common form of URI is a URL – a Uniform Resource Locator. A URL usually consists of a protocol specification such as HTTP, a host machine identification such as p2p.wrox.com, plus a name that refers to a particular resource on that machine such as java, so for instance, http://p2p.wrox.com/java is a URL that references a page on a Wrox Press server that contains a list of forums related to Java books that are published by Wrox Press.

The URI class provides several constructors for creating URI objects but getting into the detail of these is too much of a diversion from our present topic – dealing with local files. However, the simplest constructor just accepts a reference to a String object and we could use this to create a File object like this:

File remoteFile = new File(new URL(http://p2p.wrox.com/java));

References to physical files inevitably tend to be system-dependent since each operating system will have its own conventions for specifying a path to a file. If you refer to a particular file in the directory C:\My Java Stuff under Windows, this path will not be recognized under Unix. However, Java provides capabilities that enable you to avoid system dependencies when you specify file paths, at least to some extent, so let's look at those in more detail.

File myFile = new File("C:" + File.separator + "jdk1.4" + File.separator +
                       "src" + File.separator + "java" + File.separator +
                       "io", "File.java");

File myFile = new File("output.txt");

File myFile = new File("dir" + separator + "output.txt");

File myFile = new File("\\\\myPC\\shared\\jdk1.4\\src\\java\\io",
                         "File.java");

File myFile = new File(File.separator + File.separator + "myPC" +
                       File.separator + "shared" + File.separator +
                       "jdk1.4" + File.separator + "src" + File.separator + 
                       "java" + File.separator + "io", "File.java");

String currentDir = System.getProperty("user.dir");

File dataFile = new File(currentDir, "output.txt");

File dataFile = new File(System.getProperty("user.home"), "output.txt");

File dataFile = new File(System.getProperty("user.home"),
                         "dir" + File.separator + "output.txt");

System.out.println(dataFile.getAbsolutePath());

Testing and Checking File Objects

The File class provides more than 30 methods that you can apply to File objects, so we will look at the ones that will be most useful, grouped by the sorts of things that they do.

First of all, you can get information about a File object itself by using the following methods:

All of the above involve just the information encapsulated by the File object. The file or directory itself is not queried and may or may not exist. The methods in the File class that enable you to check out a file or directory are much more interesting and useful, so let's go directly to those next.

Querying Files and Directories

The following basic set of methods are provided for examining the file or directory that is identified by a File object:

When you are working with a File object, you may not know whether it contains an absolute or a relative path. However, you may well want to get hold of its parent directory – to create another file for instance. For a File object created from a relative path, the getParent() method will return null. In this case you can use the getAbsolutePath()method to obtain the absolute path, or the getAbsoluteFile() method to ensure that you have a File object for which the getParent() method will return a string representing the complete path for the parent directory. For instance:

File dataFile = new File("output.txt");

Calling getParent() for dataFile here will return null. However, we can create a new File object encapsulating the absolute path:

dataFile = dataFile.getAbsoluteFile();

Now dataFile refers to a new object that encapsulates the absolute path to "output.txt", so calling getParent() will return the path to the parent directory – which will correspond to the value of the user.dir system property in this case.

To see how some of these methods go together, we can try a simple example.

Try It Out – Testing for a File

Try the following source code. Don't forget the import statement for the java.io package, since the example won't compile without it. The source code is in a zip called src.jar, and can be found in the home directory for the JDK. If you haven't installed the Java source code on your system, you could try the example with the file that contains the source code for the example itself – TryFile.java:

import java.io.File;

public class TryFile {
  public static void main(String[] args) {

    // Create an object that is a directory
    File myDir = new File("C:/j2sdk1.4.0/src/java/io");
    System.out.println(myDir + (myDir.isDirectory() ? " is" : " is not")
                       + " a directory.");

    // Create an object that is a file
    File myFile = new File(myDir, "File.java");
    System.out.println(myFile + (myFile.exists() ? " does" : " does not")
                       + " exist");
    System.out.println(myFile + (myFile.isFile() ? " is" : " is not")
                       + " a file.");
    System.out.println(myFile + (myFile.isHidden() ? " is" : " is not")
                       + " hidden");
    System.out.println("You can" + (myFile.canRead() ? " " : "not ")
                       + "read " + myFile);
    System.out.println("You can" + (myFile.canWrite() ? " " : "not ")
                       + "write " + myFile);
    return;
  }
}

On my machine, the above example produces the output:

C:\j2sdk1.4.0\src\java\io is a directory.
C:\j2sdk1.4.0\src\java\io\File.java does exist
C:\j2sdk1.4.0\src\java\io\File.java is a file.
C:\j2sdk1.4.0\src\java\io\File.java is not hidden
You can read C:\j2sdk1.4.0\src\java\io\File.java
You can write C:\j2sdk1.4.0\src\java\io\File.java

How It Works

This program first creates an object corresponding to the directory containing the java.io package. You will need to check the path to this directory on your own system and insert that as the argument to the constructor of the File object. The output statement then uses the conditional operator ?: in conjunction with the isDirectory() method to display a message. If isDirectory()returns true, then " is" is selected. Otherwise, " is not" is selected. The program then creates another File object corresponding to the file File.java and displays further information about the file using the same sort of mechanism. Finally, the program uses the canRead() and canWrite() methods to determine whether read and write access to the file is permitted.

If you are using MS Windows, you might like to try out the separator \\ with this example and see if it makes a difference.

The following methods provide further information about the file or directory, if it exists:

There is also a static method defined in the File class, listRoots(), which returns an array of File objects. Each element in the array that is returned corresponds to a root directory in the current file system. The path to every file in the system will begin with one or other of these roots. In the case of a Unix system for instance, the array returned will contain just one element corresponding to the single root on a Unix system, /. Under MS Windows, the array will contain an element for each logical drive that you have, including floppy drives, CD drives, and DVD drives. The following statements will list all the root directories on your system:

File[] roots = File.listRoots();
for(int i = 0 ; i<roots.length ; i++)
  System.out.println("Root directory " + i + ": " + roots[i]);

The for loop lists the elements of the array returned by the listRoots() method.

With a variation on the last example, we can try out some of these methods.

Try It Out – Getting More Information

We can arrange to list all the files in a directory and record when they were last modified with the following program:

import java.io.File;
import java.util.Date;   // For the Date class

public class TryFile2 {
  public static void main(String[] args) {

    // Create an object that is a directory
    File myDir = new File("C:/j2sdk1.4.0/src/java/io");
    System.out.println(myDir.getAbsolutePath() 
                       + (myDir.isDirectory() ? " is " : " is not ")
                       + "a directory");
    System.out.println("The parent of " + myDir.getName() + " is "
                       + myDir.getParent());

    // Get the contents of the directory
    File[] contents = myDir.listFiles();

    // List the contents of the directory
    if (contents != null) {
      System.out.println("\nThe " + contents.length
                         + " items in the directory " + myDir.getName()
                         + " are:");
      for (int i = 0; i < contents.length; i++) {
        System.out
          .println(contents[i] + " is a " 
                   + (contents[i].isDirectory() ? "directory" : "file")
                   + " last modified " 
                   + new Date(contents[i].lastModified()));
      }
    } else {
      System.out.println(myDir.getName() + " is not a directory");
    }

    System.exit(0);
  }
}

Again, you need to use a path that is appropriate for your system. You should not have any difficulty seeing how this works. The first part of the program creates a File object representing the same directory as in the previous example. The second part itemizes all the files and subdirectories in the directory. The output will look something like this,

C:\j2sdk1.4.0\src\java\io is a directory
The parent of io is C:\j2sdk1.4.0\src\java

The 78 items in the directory io are:
C:\j2sdk1.4.0\src\java\io\Bits.java is a file last modified Sat Oct 20 01:13:38 BST 2001
C:\j2sdk1.4.0\src\java\io\BufferedInputStream.java is a file last modified Sat Oct 20 01:13:38 BST 2001
C:\j2sdk1.4.0\src\java\io\BufferedOutputStream.java is a file last modified Sat Oct 20 01:13:38 BST 2001
   .
   .
   .

and so on.

How It Works

You can see that the getName()method just returns the file name or the directory name, depending on what the File object represents.

The listFiles()method returns a File array, with each element of the array representing a member of the directory, which could be a subdirectory or a file. We store the reference to the array returned by the method in our array variable contents. After outputting a heading, we check that the array is not null. We then list the contents of the directory in the for loop. We use the isDirectory() method to determine whether each item is a file or a directory, and create the output accordingly. We could just as easily have used the isFile()method here. The lastModified() method returns a long value that represents the time when the file was last modified in milliseconds since midnight on January 1st 1970. To get this to a more readable form, we use the value to create a Date object, and the toString() method for the class returns what you see in the output. The Date class is defined in the java.util package. (See Chapter 13.) We have imported this into the program file but we could just as well use the fully qualified class name, java.util.Date, instead. If the contents array is null, we just output a message. You could easily add code to output the length of each file here, if you want.

Note that there is a standard system property with the name java.home that identifies the directory that is the root directory of the Java runtime environment. If you have installed the SDK (rather than just a JRE), this will be the jre subdirectory to the SDK subdirectory, which on my system is C:/SDK1.4. In this case the value of java.home will be "C:/sdk1.4/jre". You could therefore use this to refer to the file in the previous example in a system-independent way. If you create a File object from the value of the java.home property, calling its getParent() method will return the parent directory as a String object. This will be the SDK home directory so you could use this as the base directory to access the source files for the class libraries, like this:

    File myDir = new File(new File(System.getProperty("java.home")).getParent(),
                          "src" + File.separator+"java" + File.separator+"io");

As long as the JRE in effect is the one installed as part of the SDK, we have a system-independent way of accessing the source files for the library classes.

Filtering a File List

The list()and listFiles()methods are overloaded with versions that accept an argument used to filter a file list. This enables you to get a list of those files with a given extension, or with names that start with a particular sequence of characters. For example, you could ask for all files starting with the letter 'T', which might return the two files we created above: "TryFile.java" and "TryFile2.java". The argument that you pass to the list() method must be a variable of type FilenameFilter whereas the listFiles() method is overloaded with versions to accept arguments of type FilenameFilter or FileFilter. Both FilenameFilter and FileFilter are interfaces that contain the abstract method accept(). The FilenameFilter interface is defined in the java.io package as:

public interface FilenameFilter {
  public abstract boolean accept(File directory, String filename);
}

The FileFilter interface, also defined in java.io, is very similar:

public interface FileFilter {
  public abstract boolean accept(File pathname);
}

The only distinction between these two is the parameter list for the method in the interfaces. The accept() method in the FilenameFilter class has two parameters for you to specify the directory plus the file name to identify a particular file, so this is clearly aimed at testing whether a given file should be included in a list of files. The accept() method for the FileFilter interface has just a single parameter of type File, this is used to filter files and directories.

The filtering of the list is achieved by the list() or listFiles() method by calling the method accept() for every item in the raw list. If the method returns true, the item stays in the list, and if it returns false, the item is not included. Obviously, these interfaces act as a vehicle to allow the mechanism to work, so you need to define your own class that implements the appropriate interface. If you are using the list() method, your class must implement the FilenameFilter interface. If you are using the listFiles() method, you can implement either interface. How you actually filter the filenames is entirely up to you. You can arrange to do whatever you like within the class that you define. We can see how this works by extending the previous example a little further.

Try It Out – Using the FilenameFilter Interface

We can define a class to specify a file filter as:

import java.io.File;
import java.io.FilenameFilter;
import java.util.Date;        // For the Date class

public class FileListFilter implements FilenameFilter {
  private String name;        // File name filter
  private String extension;   // File extension filter

  // Constructor
  public FileListFilter(String name, String extension) {
    this.name = name;
    this.extension = extension;
  }

  public boolean accept(File directory, String filename) {
    boolean fileOK = true;

    // If there is a name filter specified, check the file name
    if (name != null)
      fileOK &= filename.startsWith(name);

    // If there is an extension filter, check the file extension
    if (extension != null)
      fileOK &= filename.endsWith('.' + extension);

    return fileOK;
  }
}

This uses the methods startsWith() and endsWith(), which are defined in the String class that we discussed in Chapter 4. Save this source in the same directory as the previous example, as FileListFilter.java.

Now we need to modify our TryFile2.java code as follows:

import java.io.File;
import java.io.FilenameFilter;
import java.util.Date;   // For the Date class

public class TryFile3 {
  public static void main(String[] args) {

    // Create an object that is a directory
    File myDir = new File("C:/j2sdk1.4.0/src/java/io");
    System.out.println(myDir.getAbsolutePath() 
                       + (myDir.isDirectory() ? " is " : " is not ")
                       + "a directory");
    System.out.println("The parent of " + myDir.getName() + " is "
                       + myDir.getParent());

    // Define a filter for java source files beginning with F
    FilenameFilter select = new FileListFilter("F", "java");

    // Get the contents of the directory
    File[] contents = myDir.listFiles(select);

    // List the contents
    if (contents != null) {
      System.out.println("\nThe " + contents.length
                         + " matching items in the directory, "
                         + myDir.getName() + ", are:");
      for (int i = 0; i < contents.length; i++) {
        System.out
          .println(contents[i] + " is a "
                   + (contents[i].isDirectory() ? "directory" : "file")
                   + " last modified " 
                   + new Date(contents[i].lastModified()));
      } 
    } else {
      System.out.println(myDir.getName() + " is not a directory");
    } 

    return;
  }
}

It is best to continue with our numbering convention and call the above script TryFile3.java. When you run this code, you should get something like the following:

C:\j2sdk1.4.0\src\java\io is a directory
The parent of io is C:\j2sdk1.4.0\src\java

The 15 matching items in the directory, io, are:
C:\j2sdk1.4.0\src\java\io\File.java is a file last modified Sat Oct 20 01:13:38 BST 2001
C:\j2sdk1.4.0\src\java\io\FileDescriptor.java is a file last modified Sat Oct 20 01:13:38 BST 2001
C:\j2sdk1.4.0\src\java\io\FileFilter.java is a file last modified Sat Oct 20 01:13:38 BST 2001
C:\j2sdk1.4.0\src\java\io\FileInputStream.java is a file last modified Sat Oct 20 01:13:38 BST 2001
   .
   .
   .

and so on.

How It Works

Our FileListFilter class has two instance variables – name and extension. The name variable stores the file name prefix, and extension selects file types to be included in a list. The constructor sets these variables, and the value of either can be omitted when the constructor is called, by specifying the appropriate argument as null. If you want a really fancy filter, you can have just one argument to the constructor and specify the filter as *.java, or A*.java, or even A*.j*. You would just need a bit more code in the constructor or possibly the accept() method to analyze the argument. Our implementation of the accept() method here only returns true if the file name that is passed to it by the list()method has initial characters that are identical to name and the file extension is the same as that stored in extension.

In the modified example, we construct an object of our filter class using the string "F" as the file name prefix and the string ".java" as the extension. This version of the example will now only list files with names beginning with F and with the extension .java.

Creating and Modifying Files and Directories

There are methods defined in the File class that you can use to change the physical file by making it read-only or renaming it. There are also methods that enable you to create files and directories, and to delete them. The methods that provide these capabilities are:

Note that, in spite of the name, the files that you create by using the createTempFile() method are not necessarily temporary, as they will not be deleted automatically. You must use delete() or deleteOnExit() to ensure that files you no longer require are removed.

You can arrange for a temporary file to be deleted automatically at the end of the program by calling the deleteOnExit() method for the File object. For example, you might write:

File tempFile = File.createTempFile("list", null);
tempFile.deleteOnExit();

The first statement will create a temporary file with a name of the form listxxxxx.tmp in the default temporary directory. The xxxxx part of the name is generated automatically. Since we did not supply a suffix, the file extension will be .tmp by default. The second statement calls the deleteOnExit() method for tempFile, so we are assured that this file won't be left lying around after the program finishes. You can apply the deleteOnExit() method to any File object, not just those corresponding to temporary files, but do so with caution. As noted above, the delete is irrevocable once you have called the method!

We will be trying out some of these methods in examples later in this chapter. Now we understand how to define objects encapsulating a path in a Java program, we can move on to creating file stream objects. We will look at file output streams first.