Beginning Java Programming: The Object-Oriented Approach (Programmer to Programmer) (2015)

---

We have stated that objects can be saved and read using ObjectOutputStream and ObjectInputStream as long as they implement the Serializable marker interface. We call this a “marker” interface, as the interface does not actually specify any methods that must be implemented by the class that is to be serialized. Any object can be serialized, as long as it implements this marker interface and all its fields can be serialized, meaning that the fields that should be primitive types are other objects that can be serialized (implementing the Serializable interface).

Note that it is possible to specifiy fields that should not be serialized using the transient keyword, for instance:

private transitent String secretCreditCardNumber;

The reason why you might want to make fields transient is because they are stored in an unencrypted format when they're serialized.

Finally, note that you can override two hidden methods: private void readObject (ObjectInputStream s) and private void writeObject(ObjectOutputStream s) in order to define a custom (de)serialization scheme. In most cases, the default serialization scheme works just fine, though.

Other Streams

Finally, a multitude of various other streams exist. Consider for instance AudioInputStream, which reads in audio-based data (sample frames). Or ZipOutputStream, which implements an output stream for writing ZIP (compressed) files. The latter is a subclass of theFilterOutputStream, which acts as a superclass of other transforming output stream classes as well.

Most of these other streams subclass InputStream and OutputStream, i.e. byte streams, which you have seen before. Browse through the Java API docs in order to get an overview of all the stream types included in the standard Java API.

SCANNERS

Earlier, you saw how you can perform advanced output formatting using the format method of the PrintWriter and PrintStream stream classes. This might have left you wondering: what about input? If a text file is formatted in a known manner, how can you easily read out all the data?

In fact, you’ve already seen a few ways to tackle this problem. If you don’t mind your input data being binary, you can use data or object streams to read in the various data types correctly. If your data is given as text, you have seen how the BufferedReader class can help read the data line by line. But what if a line of text contains different fragments you want to parse out?

Luckily, Java provides a simple means to break down input into various fragments—or tokens, as they are called—and translate them according to their data type. The class that helps you do this is the Scanner, found under java.util.Scanner. The following Try It Out shows how it works.

TRY IT OUT Scanning a Grocery List with Prices

In this Try It Out, you use the Scanner class to read in text fragments and translate them according to their data type.

1. You will continue working in the same project as before. Create a new text file next to groceries.txt called grocerieswithprices.txt with the following content:

2. apples, 5.33

3. bananas, 4.61

4. water, 1.00

5. orange juice, 2.50

6. milk, 3.20

bread, 1.11

7. Create a new class called ShowGroceries. First of all, you will take a look at how you would read out the grocery list and show it without using a Scanner:

8. import java.io.BufferedReader;

9. import java.io.FileReader;

10. import java.io.IOException;

11.

12. public class ShowGroceries {

13. public static void main(String[] args) {

14. try (

15. BufferedReader in = new BufferedReader(new FileReader(

16. "grocerieswithprices.txt"));

17. ) {

18. String line;

19. while ((line = in.readLine()) != null) {

20. String[] splittedLine = line.split(", ");

21. String item = splittedLine[0].trim();

22. double price = Double.parseDouble(splittedLine[1].trim());

23. System.out.format("Price of %s is: %.2f%n", item, price);

24. }

25. } catch (IOException e) {

26. e.printStackTrace();

27. }

28.

29. }

}

30. This approach works fine for simple cases, but depending on the nature and structure of your input text, you might want to resort to a Scanner instead, as follows:

31. import java.io.BufferedReader;

32. import java.io.FileReader;

33. import java.io.IOException;

34. import java.util.Locale;

35. import java.util.Scanner;

36. import java.util.regex.Pattern;

37.

38. public class ShowGroceries {

39. public static void main(String[] args) {

40. try (

41. Scanner sc = new Scanner(

42. new FileReader("grocerieswithprices.txt"));

43. ) {

44. sc.useDelimiter(Pattern.compile("(, )|(\r\n)"));

45. sc.useLocale(Locale.ENGLISH);

46. while (sc.hasNext()) {

47. String item = sc.next();

48. double price = sc.nextDouble();

49. System.out.format("Price of %s is: %.2f%n", item, price);

50. }

51. } catch (IOException e) {

52. e.printStackTrace();

53. }

54.

55. }

}

How It Works

Here’s how it works:

1. The Scanner class wraps around a BufferedReader in this example, but can also be directly applied to a string if so desired.

2. Next, we set the delimiter pattern of the Scanner. A delimiter is a piece of string by which we want to split up text fragments. By default, the delimiter of a Scanner equals all white-space characters (newline, a space, a tab), but in our case, we change it to match either a comma followed by a space (“, “) or a newline (\r\n).

3. We also set the Locale of the Scanner to English to make sure the decimal prices are read in and interpreted correctly. Locale is a Java provided class to represent geographical regions. Instead of instantiating a new object, the class provides a series of static members (themselves Locale objects) that can be accessed and used directly, such as Locale.ENGLISH or Locale.KOREA. Your computer might already use English as a default locale, in which case this line can also be removed.

4. Next, a while loop is iterated over so long as the Scanner is able to feed text fragments. If this is the case, we know we can immediately read in two pieces of fragments at once—the item and the price—using the nextDouble method.

5. Note that we use the Pattern class here to supply a regular expression, a relatively advanced format that specifies text patterns. Normally, you could also supply the delimiter as a single string, in which case you might be tempted to try “, “, but this will not work, as the Scanner will then continue to read text even after the end of a line is encountered, which we do not want in this case. Therefore, as a general recommendation, it is best to either stick to newline delimiters only, or use a delimiter that can be easily expressed as a single string, for instance “, “ and put all the data on the same line.

INPUT AND OUTPUT FROM THE COMMAND-LINE

You’ve seen how to use streams to perform input and output operations, e.g., to read and write data to files. In the following section, we’ll explore file I/O a bit deeper, but we first take a slight detour in order to show off input and output with the command-line.

Although most programs you run on your computer nowadays offer some sort of Graphical User Interface (GUI), this has not always been the case. In the old days of computing, programs oftentimes only offered text-like communication possibilities, showing their output and taking input from a so-called “console,” or command-line. Even in modern operating systems, this command-line interface is still present under the hood. In Windows, for instance, you can try firing up the cmd.exe program to get the command prompt shown in Figure 8.4.

Figure 8.4

When you execute Java programs in Eclipse, they will also show their output and take their input from a command-line interface, unless you program in some kind of GUI features. We refer here to the Eclipse console. Refer back to Chapter 3 if you want to know how you can run Java programs from the common Windows command-line.

In every console application, three mechanisms exist to communicate with the user. In Java, these are implemented as the “standard streams,” corresponding to the following:

· System.in: A byte InputStream to take user input (you might have expected this to be a character stream, but for historical reasons, this is not the case)

· System.err: A PrintStream to output error messages

· System.out: A PrintStream to output normal messages

You can use these streams just as you would use normal Java streams, with the difference, however, that you don’t need to open or close them. The following Try It Out shows how it works.

TRY IT OUT Input and Output from the Command-Line

This Try It Out illustrates the basic use of System.in, System.err, and System.out by means of a simple greeter application.

1. Create a single class named ReadName with the following content:

2. import java.io.BufferedReader;

3. import java.io.IOException;

4. import java.io.InputStreamReader;

5.

6. public class ReadName {

7. public static void main(String[] args) {

8. try(

9. BufferedReader reader = new BufferedReader(

10. new InputStreamReader(System.in));

11. ) {

12. System.out.println("What is your name, user?");

13. String name = reader.readLine();

14. if (name.trim().equals(""))

15. throw new IllegalArgumentException();

16. System.out.println("Welcome, " + name);

17. } catch (IllegalArgumentException e) {

18. System.err.println("Error: name cannot be blank!");

19. } catch (IOException e) {

20. e.printStackTrace();

21. }

22.

23. }

}

24.Execute the class and watch what happens in Eclipse’s console. Try to enter your name. What happens when you enter a blank name?

How It Works

Here’s how it works:

1. System.in, System.out, and System.err all act as normal streams as you’ve seen before. Note, however, the use of the InputStreamReader class to make a bridge from System.in (a byte stream) to a BufferedReader, which expects a character stream. Why do we use BufferedReader instead of BufferedInputStream here? Because we want to use the readLine method to read in a complete line of user input. This is one of the valid use cases for InputStreamReader. As an alternative, it is also possible to make use of aScanner as seen above, in which case the class would look like follows:

2. import java.util.Scanner;

3.

4. public class ReadName {

5. public static void main(String[] args) {

6. try(

7. Scanner sc = new Scanner(System.in);

8. ) {

9. System.out.println("What is your name, user?");

10. String name = sc.nextLine();

11. if (name.trim().equals(""))

12. throw new IllegalArgumentException();

13. System.out.println("Welcome, " + name);

14. } catch (IllegalArgumentException e) {

15. System.err.println("Error: name cannot be blank!");

16. }

17.

18. }

}

19.Note also that we define two catch blocks: one to catch I/O errors as we’ve done before, and one to catch our own thrown exception in case the user enters a blank name.

The reason why both normal output and error streams are provided is not native to Java, but is due to historical reasons and standardization of command-line I/O in modern operating systems. Both normal output and error streams are provided to allow users to redirect output to a file, while still showing error messages on the command line. This concept is not native to Java, but is included for historical reasons due to the standardization of command-line I/O in modern operating systems.

An example can help to clarify this. Let’s assume that you want to make a class that accepts lines from System.in and then shows the reversed line on System.out. When a palindrome is given, however (a line that reads the same forward or reversed), we’ll also show a toy “warning” on System.err. When a blank line is given, execution is stopped. The final class looks like this:

import java.io.BufferedReader;

import java.io.IOException;

import java.io.InputStreamReader;

public class LineReverser {

public static void main(String[] args) {

try(

BufferedReader reader = new BufferedReader(

new InputStreamReader(System.in));

) {

String line = null;

while (true) {

line = reader.readLine();

if (line == null || "".equals(line))

break;

String reverse = new StringBuilder(line).reverse().toString();

System.out.println(reverse);

if (line.equals(reverse))

System.err.format("The string '%s' is a palindrome!%n", line);

}

} catch (IOException e) {

e.printStackTrace();

}

}

}

Take some time to execute this class and familiarize yourself with the code. Try to enter a palindrome such as “amoreroma” and see what happens.

Now, we will take this a step further. Right-click on the LineReverser class in Eclipse and choose Export. Next, select Runnable JAR File. See Figure 8.5.

Figure 8.5

In the next screen, select LineReverser as the “launch configuration” (this requires that you ran the class in Eclipse at least once). Set the Export Destination to linereverser.jar on your desktop.

Once this is done, open a command-line window (start cmd.exe on Windows) and navigate to your Desktop folder. Usually, typing cd %HOMEPATH%\Desktop does the trick, but if not, navigate to your Desktop folder by using a combination of cd .. and cd foldernamecommands, as shown in Figure 8.6.

Figure 8.6

Next, on the command-line, start your Java program using the command java -jar linereverser.jar. The program will start and you will be able to interact with it just as you did from Eclipse’s console. See Figure 8.7.

Figure 8.7

Note how both the standard output and standard error streams are shown on the command-line by default. However, we can perform a neat little trick now by what is called “stream redirection.” Let’s say we want to save our reversed lines to a text file, but we do not want to save the error messages. In this case, we can execute the following command: java -jar linereverser.jar > output.txt. See Figure 8.8.

Figure 8.8

Note how the error messages are still shown on the console, whereas standard output is now saved in the output.txt text file (verify this by opening the file). Is there a way to redirect error messages as well? Indeed there is, by using 2>: java -jar linereverser.jar > output.txt 2> error.txt. Note that > (standard output redirection) can then also be written as 1>. If you want to append to the end of a file instead of creating a new one, you can use >> (two arrows) instead of >. Try this out if you like.

Let us now take this a step further. Create a text file called input.txt on your Desktop containing the following:

· apple

· amoreroma

· test

· aabbaa

No doubt you can see where this is going; we would like to use the contents of this file as input instead of typing the lines ourselves. Again, this is easy, using the < redirection operator, like so: java -jar linereverser.jar < input.txt. See Figure 8.9.

Figure 8.9

Indeed, you can also combine these operators to construct something like this: java -jar linereverser.jar < input.txt > output.txt 2> errors.txt.

So far, you’ve been taking input and sending output from and to files, but it is also possible to redirect the standard streams from one program to another program. To illustrate this, we will use a standard Windows command-line program called type. This program just shows the contents of a file on the standard output. Try it out by typing type input.txt. See Figure 8.10.

Figure 8.10

Now, how can you send the standard output of the type program to the program? Using > will not work here, as you’re not sending the output to a file. Instead, you can use the | operator, called the pipe, as it pipes the output from one program to another, i.e.: type input.txt | java -jar linereverser.jar. See Figure 8.11.

Figure 8.11

Piping and output redirection are two very powerful features of command-line programs. They allow for writing simple, one-task-only programs that can then be combined and chained together in a manner that’s more flexible than what most GUI applications can offer. This aspect forms one of the key reasons why command-line programs remain useful and used in server environments.

Before we end this section, let us return to Eclipse and Java to highlight a more advanced alternative of the standard streams, named the Console. This is a class that lives under java.io.Console and can be accessed through System.console(). This object provides all features the standard streams have, as well as some other features, such as secure input mechanisms (such as for password entry). The Console also provides input and output streams that are character streams. A downside of this technique however is that the Consoleis not available in all operating systems or environments, so the recommended approach remains to use the standard streams, unless you really need a feature Console provides. The following Try It Out shows how to read passwords in a secure manner using theConsole.

TRY IT OUT Advanced Command-Line Interaction Using the Console

In this Try It Out, we will use System.console() to read in a password in a secure manner.

1. You will create a single class named GetPassword with the following content:

2. import java.io.Console;

3. import java.io.IOException;

4.

5. public class GetPassword {

6. public static void main (String args[]) throws IOException {

7. Console c = System.console();

8. if (c == null) {

9. System.err.println("Console object is not available");

10. System.exit(1);

11. }

12.

13. String username = c.readLine("Enter your username: ");

14. char[] password = c.readPassword("Enter your password: ");

15.

16. if (username.equals("admin") && new String(password).equals("swordfish")) {

17. c.writer().println("Access granted");

18. } else {

19. c.writer().println("Oops, didn't recognize you there");

20. }

21. }

22.

}

23.Executing this program in Eclipse’s console will not work, as Eclipse does not provide a so-called “interactive command-line.” You will need to export the class as a Runnable JAR file like you did before. Make sure to select GetPassword as the launch configuration (execute the program in Eclipse if this does not appear in the list).

24.Once you have exported the program, you can test it using a Windows command-line. Note that the characters you type for the password will not appear on the screen. See Figure 8.12.

Figure 8.12

How It Works

This class is fairly straightforward, as most methods of System.console() are self-explanatory. The only thing you need to keep in mind is to first test whether you can access the console in your environment by performing a null check. Next, you use thereadLine and readPassword methods to get user input. Note that the latter does not return a string but an array of characters, which you thus convert to a string to perform the username/password check.

We now turn our attention back to files and continue our discussion on working with file I/O in Java in the following section.

INPUT AND OUTPUT FROM FILES

You’ve already seen some example programs that dealt with files in Java. The file copying programs, for instance, illustrated how you can use byte, character, and buffered streams to get input from and send output to files.

However, there’s more to file I/O than just taking and dropping contents from and into files. Files can be checked for existence, deleted, moved, copied, created, can contain metadata of various sorts, and can be organized into directories, which are also traversable in Java. The following sections teach you how to handle all of these things.

Java NIO2 File Input and Output

Recall from the introduction that Java 7 introduced the “NIO2” API to offer a new file system API. Existing legacy file I/O methods remain supported, so that many code samples, books, tutorials, and real-life code still apply “legacy I/O” API features.

Since newer means better in this case, we will start by applying the NIO2 API toward working with files. The central player in NIO2 is the Path type and its little helper class Paths.

The Path Interface

On your computer, files are stored in a way so that they can be easily retrieved and accessed later. On most file systems, files are stored in a hierarchical structure, meaning as a tree. The top of a tree is called a root node (e.g., C:\) under which a hierarchy of folders can be found. Each folder can contain other folders or files.

This implies that all files on your computer can be identified by a unique path of traversal through the tree. For example, on Windows, the “C:\projects\java book\structure outline.txt” path refers to a text file that lives in the folder named java book, which in turn lives in the folder projects.

NOTE On Linux, Unix, and BSD, paths use a different separator character, namely / instead of \. When programming in Java on Windows, you can also use / instead of \. If you want to retrieve the separator in a programmatic manner, you can call the following method, which returns a string:

FileSystems.getDefault().getSeparator();

The example we provided illustrated a so-called “absolute” path, meaning that the path started from the root element in the file system hierarchy (C:\) and worked its way down from there. A path can also be “relative.” Relative paths need to be combined with other paths to access a file. For example, when the current path is “C:\projects\", the relative path “java book\structure outline.txt” would lead you to the file you had before. The relative path overview.txt would resolve to “C:\projects\overview.txt” and the relative path"..\movies\vacation.avi” would resolve to “C:\movies\vacation.avi”. Note the use of "..", which traverses one level up the directory tree. A single dot (.) in a path refers to the current directory.

Finally, on some systems, file systems can also support links, apart from files and folders. A link is a special file that serves as a reference to another file. Operations on these links are automatically redirected to the target location of the link. You don’t need to concern yourself further regarding this aspect, as they are very uncommon on Windows systems and you won’t use them for most purposes.

In Java, the Path type, found under the java.nio.file package, represents a path in the file system. Path objects contain the filename and directory list used to build the path, and can be used to examine and work with files. Creating a path is done by using the getmethod on the Paths class, also under java.nio.file, like so:

Path myPath = Paths.get("C:\\projects\\outline.txt");

NOTE An important thing to note here is that Path is an interface type, whereas Paths is a normal class (albeit a very simple one, without a public constructor). In case you're wondering why the former is an interface, the reason for this is to allow developers of custom file systems to be able to implement (or extend) it.

The usage of the s suffix of Path versus Paths is also in line with other concepts in NIO2, for instance Files (which you'll encounter later on) and FileSystem versus FileSystems. In fact, calling the get method of Paths is a shorthand for:

FileSystems // A static utility class containing methods to create

FileSystem objects

.getDefault() // Get the default file system FileSystem

.getPath("C:\\projects\\outline.txt") // Return a Path

Once you have created a Path object, there are a number of methods you can execute on them to retrieve information about the path. These methods do not require that the file corresponding to the path actually exist:

· String myPath.toString(): Returns the string representation of the Path object. Note that this method will attempt to perform syntactic cleanup.

· Path myPath.getFileName(): Returns the filename or the last element in the Path object.

· Path myPath.getName(int i): Returns the Path element corresponding to the specified index. Note that index 0 does not represent the root, but the element closest to the root.

· int myPath.getNameCount(): Returns the number of elements in the path.

· Path myPath.subpath(int i, int j): Returns the subsequence of the Path (not including a root element) as specified by beginning and ending indices.

· Path myPath.getParent(): Returns the Path of the parent directory of this path.

· Path myPath.getRoot(): Returns the root of the path.

· Path myPath.normalize(): Cleans up redundancies from a path and returns the cleaned-up result. For example, “C:\.\projects\..\movies\vacation.avi” is converted to “C:\movies\vacation.avi”.

· Path myPath.resolve(String partialPath): The partial path (not including a root element) is added to the original path and the new path is returned. If you pass in an absolute path, the absolute Path itself will be returned.

· Path myPath.relativize(Path otherPath): Constructs a new Path object originating from the original path and ending at the location specified by otherPath. This returns a relative Path.

In addition, methods exist to convert a path:

· URI myPath.toUri(): Converts the path to a string that can be opened by web browsers.

· Path myPath.toAbsolutePath(): Converts a relative path to an absolute one.

· Path myPath.toRealPath(LinkOption... options): Returns the real path of an existing file. If true is passed in the options parameters, links will be resolved to their real paths (if the file system supports links). In addition, relative paths will be converted to absolute ones and redundant elements will be removed.

The Files Class

Apart from the Path interface, the Files class is the other most important class contained in the java.nio.file package. This utility class offers a set of static methods for reading, writing, and manipulating files and folders (do not be thrown off by the fact that the class itself is named Files and not FilesAndFolders).

NOTE Similarly to Path with its Paths helper and FileSystem with its FileSystems counterpart, you might expect Files to contain methods that return File objects. However, the File class already existed before the advent of NIO2 (you'll meet it in the legacy file section ahead), so that all methods in the Files class that do return an object representing an entity in a file system will return it as a Path object, not File.

Checking Existence

The first and most basic operation you can execute using the Files class is performing checks on files and folders. Let’s say you have created a Path object representing a file or folder. How do you check whether this path actually exists? Two methods exist (no pun intended) to do so:

· boolean Files.exists(Path pathToCheck, LinkOption... options)

· boolean Files.notExists(Path pathToCheck, LinkOption... options)

Ignore the options parameter for now. As we’ve said, this parameter is there to specify how links should be dealt with. A more interesting question is why two methods are provided. Couldn’t you just use !Files.exists(path) instead of Files.notExists(path)? The reason for this is because—when checking the existence of a path—three results can occur: the file exists, the file does not exist, or your program cannot determine the existence, for instance, when access rules block your program from reaching the path. If both existsand notExists return false, this means the existence of the path cannot be verified. If exists returns true, this means you can safely continue working with this file, as it exists and can be accessed from your program.

There are also a number of other methods to check a file’s status:

· boolean Files.isReadable(Path pathToCheck): Tests whether a path is readable.

· boolean Files.isWritable(Path pathToCheck): Tests whether a path is writable.

· boolean Files.isExecutable(Path pathToCheck): Tests whether a path is executable.

· boolean Files.isDirectory(Path pathToCheck): Tests whether the path represents a directory.

· boolean Files.isSameFile(Path firstPath, Path secondPath): Tests whether two paths resolve to the same location, taking into account redundant syntax and links.

NOTE Note that the result of performing a check on a Path is atomic and might be violated almost immediately after you continue in your code. Meaning that a file might be deleted, for instance, after you perform an existence check and move on with the rest of your code. This aspect can lead to a particular kind of software bug called TOCTTOU (time of check to time of use) and can also lead to security problems in serious cases. Therefore, never assume too strongly that the result of your check will remain absolutely true throughout the execution of your program, and always be ready to handle exceptions thrown by the Files methods in a graceful manner.

Deleting Files and Folders

The next operation you can perform using the Files class is a bit more volatile, i.e. deletion. It is possible to delete both files and folders, but for folders, the folder needs to be empty before it can be deleted, otherwise an exception will be thrown. The following code snippet shows how the delete method works:

try {

Files.delete(path);

} catch (NoSuchFileException x) {

// File does not exist

} catch (DirectoryNotEmptyException x) {

// The directory is not empty

} catch (IOException x) {

// File permission problem, no access

}

Note that there is also a Files.deleteIfExists(Path pathToDelete) method. This method works in a similar manner, but will not throw an exception when the file does not exist. It just does nothing in that case.

Copying and Moving Files and Folders

Next up, you look at two methods for copying and moving files:

· Path copy(Path source, Path target, CopyOptions... options): Copies a source file to a target file. The options specify how the copy is performed. By default, the copy operation will fail if the target file already exists (except when both are the same file), unless you pass REPLACE_EXISTING as an option. If the file to copy is a directory, an empty directory is created in the target location, but the entries in the directory are not copied. You will see later how to easily copy over a complete directory using this method.

· Path move(Path source, Path target, CopyOptions... options): Moves a source file to a target file. The options specify how the move is performed. By default, the move operation will fail if the target file already exists (except when both are the same file), unless you pass REPLACE_EXISTING as an option. If the file to copy is a directory, the move will be successful if the directory is empty. Otherwise, the result of the move depends on the underlying file system and can throw an IOException in some cases. In that case, a copy should be performed first followed by a manual cleanup of the original source directory.

NOTE Note that these methods provide a more straightforward means to copy and move files than the stream-based file copy programs you've seen before. Again, one of the nice improvements of the NIO2 API.

Reading, Writing, and Creating Files

Next, let’s take a look at how to read, write, and create files using the NIO2 API. In this chapter, you’ve already seen how to use stream-based methods to do this, and the NIO2 API will build on the concept of streams, while also making our lives easier with some helpful methods.

First of all, when you just want to get all bytes or lines from a file, you can use the following methods:

· byte[] Files.readAllBytes(Path path): Reads all the bytes from a file to a byte array. This method takes care of opening and closing the file for you.

· List<String> readAllLines(Path path, Charset cs): Reads all lines from a file to a list of strings. This method takes care of opening and closing the file for you. The Charset parameter specifies which character set should be used for decoding the file. UsingCharset.defaultCharset() or Charset.forName("UTF-8") works best in most cases.

Note, however, that these methods will read the complete contents of a file at once, and thus will fail to work when you are dealing with large files. For small files, however, this approach is straightforward and works just fine. As an example, recall the grocery-reading application we showed off in the introduction. Note that you can completely avoid dealing with streams thanks to the Files class:

import java.io.IOException;

import java.nio.charset.Charset;

import java.nio.file.Files;

import java.nio.file.Paths;

import java.util.ArrayList;

import java.util.List;

public class ShowGroceries {

public static void main(String[] args) {

List<String> groceries = new ArrayList<>();

try {

groceries = Files.readAllLines(

Paths.get("groceries.txt"),

Charset.defaultCharset());

} catch (IOException e) {

e.printStackTrace();

}

for (String item : groceries) {

System.out.println("Don't forget to pickup: " + item);

}

}

}

Similarly, two methods exist to write all bytes or lines to a file:

· Path write(Path path, byte[] bytes, OpenOption... options): Writes bytes to a file. By default, this method creates a new file or overwrites an existing file.

· Path write(Path path, Iterable<? extends CharSequence> lines, Charset cs, OpenOption... options): Writes lines of text to a file. By default, this method creates a new file or overwrites an existing file. Don’t be confused by the signature of the lines argument. In practical cases, this will work with a List<String>, for instance. The Charset parameter specifies which character set should be used for encoding the file. Using Charset.defaultCharset() or Charset.forName("UTF-8") works best in most cases.

You might be wondering what the OpenOptions parameters are for in these methods. These options are used in various methods and will tell the NIO2 API how you want to open the file. You can pass in the following StandardOpenOptions values:

· WRITE: Opens a file for write access.

· APPEND: Appends new data to the end of the file (use together with WRITE or CREATE).

· TRUNCATE_EXISTING: Empties the file before writing (use with WRITE).

· CREATE_NEW: Creates a new file or throws an exception if the file exists.

· CREATE: Opens the file or creates it if it does not exist.

· DELETE_ON_CLOSE: Deletes the file when the handling stream is closed.

· SPARSE, SYNC, DSYNC: A set of advanced options that we do not describe in detail here.

If you’ve been paying attention, you’ll notice that these options strongly resemble the file operation modes introduced in the beginning of this chapter. In most cases, there’s no need to provide any options at all, however, as the API will assume sensible defaults when you leave them out (CREATE, TRUNCATE_EXISTING, and WRITE for the write methods, for instance). When you do supply your own options, take care not to supply an infeasible combination or a combination that does not match the operation you’re trying to perform with the method you’re calling.

The methods mentioned so far are fine when you’re dealing with small files, but when you need to work with large files, you cannot store the contents of the file in memory all at the same time. We already know how we would approach this problem using buffered character streams:

Reader fr = new FileReader("groceries.txt");

BufferedReader br = new BufferedReader(fr);

However, the NIO2 API provides a cleaner way to read and write files (note for instance that we hardcoded the filename in the code snippet) using the following two methods:

· BufferedReader Files.newBufferedReader(Path path, Charset cs): Returns a buffered character stream to read a text file in an efficient manner using the given character set to decode.

· BufferedReader Files.newBufferedReader(Path path): Same as above, but using UTF-8 as the character set.

· BufferedWriter Files.newBufferedWriter(Path path, Charset cs, OpenOption... options): Returns a buffered character stream to write a text file in an efficient manner using the given character set to encode. If no options are provided, CREATE, TRUNCATE_EXISTING andWRITE are used.

· BufferedWriter Files.newBufferedWriter(Path path, OpenOption... options): Same as above, but using UTF-8 as the character set.

Note how these neatly work together with the Files and Path types. Once called, you can just use the BufferedReader and BufferedWriter streams as you’ve seen before. The following code fragment shows an example using a try-with-resources block, which remains the recommended approach:

Path file = Paths.get("groceries.txt");

try (BufferedReader reader = Files.newBufferedReader(file)) {

String line = null;

while ((line = reader.readLine()) != null) {

System.out.println(line);

}

} catch (IOException x) {

System.err.println("Something went wrong");

}

Next, if you do not want to use buffered character streams but want to use byte streams instead, you’ll need to use the newInputStream and newOutputStream methods. They work similarly to the previous methods, but return InputStream and OutputStream object respectively, which you can then wrap in BufferedInputStream and BufferedOutputStream objects if you want to obtain a buffered byte stream.

NOTE You might be wondering why the character stream variant of these methods return a buffered stream, whereas the byte stream ones return a non-buffered one. This is mainly due to convention: in cases where you will use a character stream, using a buffered approach almost always make sense. You can still obtain an unbuffered character stream if you really need it by using the InputStreamReader and OutputStreamWriter classes and wrapping them around the InputStream andOutputStream objects you get with the newInputStream and newOutputStream methods.

Note that the Java NIO2 API also provides a different method to read and write files, named channel I/O, as an alternative to stream-based I/O. Whereas streams read one character or byte at a time, channels can read or write buffers at a time (and thus avoid the use of a separate buffering mechanism). In addition, channels exist that allow for more fine-grained seeking within a file through a concept called Random Access Files, which permit non-sequential access to files and which allow you to map the contents of a file directly to computer memory. We mention it here for the sake of completeness, but in most “normal” file I/O environments, stream-based I/O works just fine.

Lastly, we can take a look at the methods to create files. While you might just use one of the earlier writing functions to open a new file and immediately close it, it is much cleaner to use the Files.createFile(Path path) method to create an empty file. Note that this method will—by default—throw a permission if a path exists, contrary to the writing methods shown previously, which will overwrite a file if it exists. It is thus a good idea to use this method as an extra fail-safe in cases where this matters. You can also use another method—Files.createTempFile(Path folder, String prefix, String suffix—to create temporary files in the specified folder, using a given prefix, suffix, and a randomized body as a name. Note that you can leave the folder argument out, in which case the standard temporary-file directory provided by your operating system will be used. These methods are helpful to create quick “throwaway” files.

Reading and Creating Folders

Some path operation methods, such as deletion or copying, can work on files and folders. But directories also require an additional set of methods. For example, how would you list all the contents of a folder?

First of all, though, let’s quickly take a look at creating folders. This can be done using the Files.createDirectory(Path path) method or the createTempDirectory(Path folder, String prefix) method in case you want to create a temporary folder (again, the folderargument can be left out).

You list all the contents of a folder using the Files.newDirectoryStream(Path folder) method. Note that this method returns an object that implements the DirectoryStream and Iterable interfaces, so you can loop over this object to read all of the entries. However, since this object is a stream, don’t forget to close it in your finally block (or use a try-with-resources block as we’ve been recommending so far). The following example class shows how to list the contents of a directory:

import java.io.IOException;

import java.nio.file.DirectoryIteratorException;

import java.nio.file.DirectoryStream;

import java.nio.file.Files;

import java.nio.file.Path;

import java.nio.file.Paths;

public class ShowDirectory {

public static void main(String[] args) {

Path folder = Paths.get("C:\\");

try (DirectoryStream<Path> stream = Files.newDirectoryStream(folder)) {

for (Path entry: stream) {

System.out.println(entry.getFileName());

}

} catch (IOException | DirectoryIteratorException x) {

System.err.println("An error occurred");

}

}

}

Example output:

$Recycle.Bin

BOOTNXT

Documents and Settings

eclipse

hiberfil.sys

MSOCache

pagefile.sys

PerfLogs

Program Files

Program Files (x86)

ProgramData

swapfile.sys

System Volume Information

temp

Users

Windows

Note that this approach returns all the contents of a directory: files, subdirectories, hidden files, and links. If you only need a subset, you can just add checks to the for loop using methods you’ve seen before. Another way to filter a directory listing is by using a concept called globbing, using the Files.newDirectoryStream(Path folder, String glob) method. A glob is a special kind of syntax to specify pattern-matching behavior. An asterisk (*), for instance, matches any number of characters; a question mark (?) matches exactly one character. Braces ({one,two}) specify a collection of subpatterns, whereas square patterns ([qwerty]) convey a set or range ([0-9]) of characters. The following method call, for example, only returns DOC, PDF, and TXT files:

Files.newDirectoryStream(dir, "*.{txt,doc,pdf}"));

If you only want to retrieve directories, you’ll need to write your own filter. To do so, you can create a class implementing the DirectoryStream.Filter<T> interface (and implementing the accept method) and use this to invoke the Files.newDirectoryStream(Path folder, DirectoryStream.Filter filter) method. Just using an if (Files.isDirectory(entry)) continue; line might be easier in this case, however.

Recursing Folders

The last operation we’ll take a closer look at involves recursing over the folder tree. When discussing how to copy, move, or delete paths, we’ve stated that copying folders just creates an empty folder, moving folders can fail in some cases, and deleting folders only works when the folder is empty. In addition, you might be interested in writing a method that looks for a file or directory in a directory as well as subdirectories.

For all these tasks, interfaces have been defined by the NIO2 API to do this. The reality, however, is that implementing all interfaces and setting up everything can be a bit daunting for newcomers. For instance, to walk over a directory tree, you’ll need to implementFileVisitor<Path> with the preVisitDirectory, visitFile, postVisitDirectory, and visitFileFailed methods. Look up the Java API docs if you’re interested to learn more.

Instead, the following Try It Out will present a set of alternative recursive methods you can use to copy, move, delete, and search through directories, which you can use as a starting point in your own code as well.

TRY IT OUT Using Recursive Operations

In this Try It Out, you implement a set of methods to search, delete, copy, and move complete directories at once.

1. In Eclipse, create a class called RecursiveOperations.

2. First, add a method to delete files:

3. public static void delete(Path source) throws IOException {

4. if (Files.isDirectory(source)) {

5. for (Path file : getFiles(source))

6. delete(file);

7. }

8. Files.delete(source);

9. System.out.println("DELETED "+source.toString());

}

10. Next, you need to provide the getFiles method. This helper method returns all files and subdirectories in a given folder. However, since deletion will only work on empty folders, you want this method to first return all directories, followed by all files to ensure that the delete method first goes through all directories as far as possible:

11. public static List<Path> getFiles(Path dir) {

12. // Gets all files, but puts directories first

13. List<Path> files = new ArrayList<>();

14. if (!Files.isDirectory(dir))

15. return files;

16. try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) {

17. for (Path entry : stream)

18. if (Files.isDirectory(entry))

19. files.add(entry);

20. } catch (IOException | DirectoryIteratorException x) {

21. }

22. try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) {

23. for (Path entry : stream)

24. if (!Files.isDirectory(entry))

25. files.add(entry);

26. } catch (IOException | DirectoryIteratorException x) {

27. }

28. return files;

}

29. Next up, you can define a copy method in a similar fashion:

30. public static void copy(Path source, Path target) throws IOException {

31. if (Files.exists(target) && Files.isSameFile(source, target))

32. return;

33. if (Files.isDirectory(source)) {

34. Files.createDirectory(target);

35. System.out.println("CREATED "+target.toString());

36. for (Path file : getFiles(source))

37. copy(file, target.resolve(file.getFileName()));

38. } else {

39. Files.copy(source, target);

40. System.out.println(

41. "COPIED "+source.toString()+" -> "+target.toString());

42. }

}

43. The move method just reuses the copy and delete methods:

44. public static void move(Path source, Path target) throws IOException {

45. if (Files.exists(target) && Files.isSameFile(source, target))

46. return;

47. copy(source, target);

48. delete(source);

}

49. The search method is added as follows, and uses a PathMatcher object to match a filename to a provided glob:

50. public static Set<Path> search(Path start, String glob,

51. boolean includeDirectories, boolean includeFiles) {

52.

53. PathMatcher matcher = FileSystems.getDefault().getPathMatcher

54. ("glob:" + glob);

55. Set<Path> results = new HashSet<>();

56. search(start, matcher, includeDirectories, includeFiles, results);

57. return results;

58. }

59.

60. private static void search(Path path, PathMatcher matcher,

61. boolean includeDirectories, boolean includeFiles, Set<Path> results) {

62.

63. if (matcher.matches(path.getFileName())

64. && ((includeDirectories && Files.isDirectory(path))

65. || (includeFiles && !Files.isDirectory(path)))) {

66. results.add(path);

67. }

68.

69. for (Path next : getFiles(path))

70. search(next, matcher, includeDirectories, includeFiles, results);

}

71. Finally, you can add a main class to test these methods:

72. public static void main(String args[]) throws IOException {

73. // WARNING: TAKE CARE WHEN TESTING THESE FUNCTIONS ON

74. // EXISTING FOLDERS ON YOUR SYSTEM

75.

76. // Set up test directory

77. try {

78. delete(Paths.get("C:\\javatest\\"));

79. delete(Paths.get("C:\\javatest2\\"));

80. } catch(NoSuchFileException e) {}

81. Files.createDirectory(Paths.get("C:\\javatest\\"));

82. Files.createDirectory(Paths.get("C:\\javatest\\subdir\\"));

83. Files.createFile(Paths.get("C:\\javatest\\text1.txt"));

84. Files.createFile(Paths.get("C:\\javatest\\text2.txt"));

85. Files.createFile(Paths.get("C:\\javatest\\other.txt"));

86. Files.createFile(Paths.get("C:\\javatest\\subdir\\text3.txt"));

87. Files.createFile(Paths.get("C:\\javatest\\subdir\\other.txt"));

88.

89. // Test our methods

90. copy(Paths.get("C:\\javatest\\subdir\\"),

91. Paths.get("C:\\javatest\\subdircopy\\"));

92. System.out.println(search(Paths.get("C:\\javatest"),

93. "text*.txt", true, true));

94. move(Paths.get("C:\\javatest\\subdircopy\\"),

95. Paths.get("C:\\javatest\\subdircopy2\\"));

96. System.out.println(search(Paths.get("C:\\javatest\\"),

97. "text*.txt", true, true));

98. copy(Paths.get("C:\\javatest\\"), Paths.get("C:\\javatest2\\"));

99.

}

100. Executing this code yields the following output:

101. CREATED C:\javatest\subdircopy

102. COPIED C:\javatest\subdir\other.txt -> C:\javatest\subdircopy\other.txt

103. COPIED C:\javatest\subdir\text3.txt -> C:\javatest\subdircopy\text3.txt

104. [C:\javatest\subdir\text3.txt, C:\javatest\text2.txt,

105. C:\javatest\subdircopy\text3.txt, C:\javatest\text1.txt]

106. CREATED C:\javatest\subdircopy2

107. COPIED C:\javatest\subdircopy\other.txt -> C:\javatest\subdircopy2\other.txt

108. COPIED C:\javatest\subdircopy\text3.txt -> C:\javatest\subdircopy2\text3.txt

109. DELETED C:\javatest\subdircopy\other.txt

110. DELETED C:\javatest\subdircopy\text3.txt

111. DELETED C:\javatest\subdircopy

112. [C:\javatest\subdir\text3.txt, C:\javatest\subdircopy2\text3.txt,

113. C:\javatest\text2.txt, C:\javatest\text1.txt]

114. CREATED C:\javatest2

115. CREATED C:\javatest2\subdir

116. COPIED C:\javatest\subdir\other.txt -> C:\javatest2\subdir\other.txt

117. COPIED C:\javatest\subdir\text3.txt -> C:\javatest2\subdir\text3.txt

118. CREATED C:\javatest2\subdircopy2

119. COPIED C:\javatest\subdircopy2\other.txt -> C:\javatest2\subdircopy2\other.txt

120. COPIED C:\javatest\subdircopy2\text3.txt -> C:\javatest2\subdircopy2\text3.txt

121. COPIED C:\javatest\other.txt -> C:\javatest2\other.txt

122. COPIED C:\javatest\text1.txt -> C:\javatest2\text1.txt

COPIED C:\javatest\text2.txt -> C:\javatest2\text2.txt

How It Works

Here’s how it works:

1. Although the class is relatively large, most of the operations we’ve included follow the same general reasoning: loop over subdirectories until you cannot go any further, then perform operations on the included files.

2. Two important notes to keep in mind are that the getFiles method first returns a list of directories, followed by normal files, so that deletion can first clean up the deepest directory before working its way up. Another interesting aspect is how we use the PathMatcher class to match a filename to a glob. The following code snippet can come in handy in other scenarios as well:

3. Path path = ...;

4. PathMatcher matcher = FileSystems.getDefault().getPathMatcher("glob:" + glob);

5. if (matcher.matches(path.getFileName())

// do something

6. The “glob:" prefix in the getPathMatcher method should be provided by convention to indicate your pattern is a glob type.

7. We’ve added a check to prevent copying and moving a source to the same target. What would happen if you tried to move a directory under one of its subdirectories? Can you imagine ways to prevent this (or deal with this case)?

8. If you’re interested in knowing how to copy directories using the visitor pattern offered by the NIO2 API, you can take a look at this example online: http://docs.oracle.com/javase/tutorial/essential/io/examples/Copy.java.

Other Methods

Finally, there are a number of additional methods in the Files class that can come in handy. First, metadata methods such as Files.size(Path p)(returns the size of the file in bytes), Files.getOwner(Path p, LinkOption... options), and Files.getLastModifiedTime(Path p, LinkOption... options) can be used to retrieve (and set) metadata. Secondly, functionality exists to watch a file for changes. Look up NIO’s WatchService if you ever need this feature. Lastly, we briefly touched on the concept of link. The NIO2 API also provides functionality to create and modify such links in the file system, but we skipped an in-depth discussion and refer interested intermediate readers to other sources, such as the Java API docs.

Legacy File Input and Output

Prior to the Java 7 release, the java.io.File class was the default mechanism used for file I/O. This class is still present for reasons of backward-compatibility, but has several drawbacks:

· Some methods don’t throw exceptions when an error occurs, or do not provide enough information to know the root cause behind a failure.

· Well-defined support for links is lacking.

· Accessing file metadata can be difficult and slow.

· Fetching information over a network introduces scalability issues.

· Some methods do not work consistently on various operating systems and platforms.

That being said, a great deal of real-life code still uses the legacy file input and output, so we discuss it here in brief. Creating a file object is simple:

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

Whenever you can, a good way to deal with methods returning legacy File objects is to immediately convert them to a Path using the myFile.toPath() method. Similarly, the Path interface defines a toFile() method you can use to get a legacy File object from a Pathobject.

Operations you wish to execute on a File object (such as checking for existence) are not done through a helper class like Files did on Path objects, but directly on the File object itself, for example by calling one of its methods. The following list shows the corresponding File methods for most of the Files equivalents we’ve discussed:

· Path.getFileName(...) was File.getName()

· Files.isDirectory(...) was File.isDirectory(...)

· Files.isRegularFile(...) was File.isFile(...)

· Files.size(...) was File.length(...)

· Files.move(...) was File.renameTo(...)

· Files.delete(...) was File.delete(...)

· Files.createFile(...) was File.createNewFile(...)

· Files.createTempFile(...) was File.createTempFile(...)

· File.deleteOnExit(...) is now handled by passing DELETE_ON_CLOSE as an option to Files.createFile(...)

· Files.exists(...) and Files.notExists(...) was File.exists(...)

· Path.newDirectoryStream(...) was File.list(...) and File.listFiles(...)

· Path.createDirectory(...) was File.mkdir(...)

As an example, the following code fragment shows how to loop over the contents of a directory using the legacy API:

import java.io.File;

public class ShowDirectory {

public static void main(String[] args) {

File folder = new File("C:\\");

for (File entry : folder.listFiles()) {

System.out.println(entry.getName());

}

}

}

This particular example might appear simple compared to the corresponding NIO2 implementation (fewer imports are used), but keep in mind the other advantages of NIO2 (reading and writing, for instance). The NIO2 approach remains the recommended one.

A Word on FileUtils

Java’s file input/output classes—and the legacy ones in particular—miss some widely used features that are both somewhat annoying and time consuming to implement yourself, or require a great amount of exception juggling to implement gracefully. You’ve already seen an example of this in the form of the implementation of copy, move, and delete operations for whole directories.

When you’re looking for an implementation to properly copy, clean, and move directories or perform many other common file operations, the FileUtils utility class by the Apache Commons project is worth looking at. In fact, many programmers consider this class so helpful and so essential that they will include it as a library in any new Java project they set up. Take a look at the following website if you’re interested in knowing more or want to download and use the library (add it to Eclipse’s build path in order to use it):http://commons.apache.org/proper/commons-io/.

One downside of the FileUtils library, however, is that it is built with Java 6 compatibility in mind, meaning that the legacy File class is used in its method arguments, without Path and Files being present. If you use the FileUtils library, consider using the previously discussed Path.toFile() method to keep the rest of your code base NIO-ready.

CONCLUSION

This concludes this chapter on basic input/output with Java and file input/output. You’ve seen what is meant by stream-based input/output, learned how to interact with users over the command-line, and learned how to write and read content to and from files, using both the NIO2 and legacy API. As always, don’t be afraid to peruse the Java docs or explore the methods offered by Path and Files and other classes using Eclipse’s autosuggest functionality. It is a great way to experiment and learn.

This chapter was largely about saving and reading data to and from files. The next chapter introduces databases, a more advanced and powerful method to store and retrieve information.