Java theory and practice: Good housekeeping practices

http://www.ibm.com/developerworks/java/library/j-jtp03216/index.html

 

Java theory and practice: Good housekeeping practices

Are your resources overstaying their welcome?

 

Our parents used to remind us to put our toys away when we were done with them. If you look closely enough, the motivation for such nagging was probably not so much an abstract desire to keep things clean as much as the practical limitation that there is only so much floor space in the house, and if it is covered with toys, it can't be used for other things -- like walking around.

Given enough space, the motivation to clean up one's mess is lessened. The more space you have, the less motivation you have to always keep it clean. Arlo Guthrie's famous ballad Alice's Restaurant Massacre illustrates this point:

Havin' all that room, seein' as how they took out all the pews, they decided that they didn't have to take out their garbage ... for a long time.

For better or worse, garbage collection can make us a little sloppy about cleaning up after ourselves.

Explicitly releasing resources

The vast majority of resources used in Java programs are objects, and garbage collection does a fine job of cleaning them up. Go ahead, use as many String s as you want. The garbage collector eventually figures out when they've outlived their usefulness, with no help from you, and reclaims the memory they used.

On the other hand, nonmemory resources like file handles and socket handles must be explicitly released by the program, using methods with names like close() , destroy() , shutdown() , or release() . Some classes, such as the file handle stream implementations in the platform class library, provide finalizers as a "safety net" so that if the program forgets to release the resource, the finalizer can still do the job when the garbage collector determines that the program is finished with it. But even though file handles provide finalizers to clean up after you if you forget, it is still better to close them explicitly when you are done with them. Doing so closes them much earlier than they otherwise would be, reducing the chance of resource exhaustion.

For some resources, waiting until finalization to release them is not an option. For virtual resources like lock acquisitions and semaphore permits, a Lock or Semaphore is not likely to get garbage collected until it is too late; for resources like database connections, you would surely run out of resources if you waited for finalization. Many database servers only accept a certain number of connections, based on licensed capacity. If a server application were to open a new database connection for each request and then just drop it on the floor when done, the database would likely reach its capacity long before the no-longer-needed connections were closed by the finalizer.

---

Back to top

Resources confined to a method

Most resources are not held for the lifetime of the application; instead, they are acquired for the lifetime of an activity. When an application opens a file handle to read in so it can process a document, it typically reads from the file and then has no further need for the file handle.

In the easiest case, the resource is acquired, used, and hopefully released in the same method call, such as the loadPropertiesBadly() method in Listing 1:

Listing 1. Incorrectly acquiring, using, and releasing a resource in a single method -- don't do this

public static Properties loadPropertiesBadly(String fileName) throws IOException { FileInputStream stream = new FileInputStream(fileName); Properties props = new Properties(); props.load(stream); stream.close(); return props; }

Unfortunately, this example has a potential resource leak. If all goes well, the stream will be closed before the method returns. But if the props.load() method throws an IOException , then the stream will not be closed (until the garbage collector runs its finalizer). The solution is to use the try...finally mechanism to ensure that the stream is closed no matter what goes wrong, as shown in Listing 2:

Listing 2. Correctly acquiring, using, and releasing a resource in a single method

public static Properties loadProperties(String fileName) throws IOException { FileInputStream stream = new FileInputStream(fileName); try { Properties props = new Properties(); props.load(stream); return props; } finally { stream.close(); } }

Note that the resource acquisition (opening the file) is outside the try block; if it were placed inside the try block, then the finally block would run even if resource acquisition threw an exception. Not only would this approach be inappropriate (you can't release a resource you haven't acquired), but the code in the finally block is then likely to throw an exception of its own, such as NullPointerException . An exception thrown from a finally block supersedes the exception that caused the block to exit, which means the original exception is lost and cannot be used to aid in the debugging effort.

Not always as easy as it looks

Using finally to release resources acquired in a method is reliable but can easily get unwieldy when multiple resources are involved. Consider a method that uses a JDBC Connection to execute a query and iterate the ResultSet . It acquires a Connection , uses it to create a Statement , and executes the Statement to yield a ResultSet . But the intermediate JDBC objects Statement and ResultSet have close() methods of their own, and they should be released when you are done with them. However, the "obvious" way to clean up, shown in Listing 3, doesn't work:

Listing 3. Unsuccessful attempt to release multiple resources -- don't do this

public void enumerateFoo() throws SQLException { Statement statement = null; ResultSet resultSet = null; Connection connection = getConnection(); try { statement = connection.createStatement(); resultSet = statement.executeQuery("SELECT * FROM Foo"); // Use resultSet } finally { if (resultSet != null) resultSet.close(); if (statement != null) statement.close(); connection.close(); } }

The reason this "solution" doesn't work is that the close() methods of ResultSet and Statement can themselves throw SQLException , which could cause the later close() statements in the finally block not to execute. That leaves you with several choices, all of which are annoying: wrap each close() with a try..catch block, nest the try...finally blocks as shown in Listing 4, or write some sort of mini-framework for managing the resource acquisition and release.

Listing 4. Reliable (if unwieldy) means of releasing multiple resources

public void enumerateBar() throws SQLException { Statement statement = null; ResultSet resultSet = null; Connection connection = getConnection(); try { statement = connection.createStatement(); resultSet = statement.executeQuery("SELECT * FROM Bar"); // Use resultSet } finally { try { if (resultSet != null) resultSet.close(); } finally { try { if (statement != null) statement.close(); } finally { connection.close(); } } } } private Connection getConnection() { return null; }

Nearly everything can throw an exception

We all know that we should use finally to release heavyweight objects like database connections, but we're not always so careful about using it to close streams (after all, the finalizer will get that for us, right?). It's also easy to forget to use finally when the code that uses the resource doesn't throw checked exceptions. Listing 5 shows the implementation of the add() method for a bounded collection that uses Semaphore to enforce the bound and efficiently allow clients to wait for space to become available:

Listing 5. Vulnerable implementation of a bounded collection -- don't do this

public class LeakyBoundedSet<T> { private final Set<T> set = ... private final Semaphore sem; public LeakyBoundedSet(int bound) { sem = new Semaphore(bound); } public boolean add(T o) throws InterruptedException { sem.acquire(); boolean wasAdded = set.add(o); if (!wasAdded) sem.release(); return wasAdded; } }

LeakyBoundedSet first waits for a permit to be available (indicating that there is space in the collection), then tries to add the element to the collection. If the add operation fails because the element was already in the collection, it releases the permit (because it did not actually use the space it had reserved).

The problem with LeakyBoundedSet doesn't necessarily jump out immediately: What if Set.add() throws an exception? This scenario could happen because of a flaw in the Set implementation, or a flaw in the equals() or hashCode() implementation (or the compareTo() implementation, in the case of a SortedSet ) for the element being added, or an element already in the Set . The solution, of course, is to use finally to release the semaphore permit; an easy enough -- but all-too-often-forgotten -- approach. These types of mistakes are rarely disclosed during testing, making them time bombs waiting to go off. Listing 6 shows a more reliable implementation of BoundedSet :

Listing 6. Using a Semaphore to reliably bound a Set

public class BoundedSet<T> { private final Set<T> set = ... private final Semaphore sem; public BoundedHashSet(int bound) { sem = new Semaphore(bound); } public boolean add(T o) throws InterruptedException { sem.acquire(); boolean wasAdded = false; try { wasAdded = set.add(o); return wasAdded; } finally { if (!wasAdded) sem.release(); } } }

Code auditing tools like FindBugs (see Resources ) can detect some instances of improper resource release, such as opening a stream in a method and not closing it.

---

Back to top

Resources with arbitrary lifecycles

For resources with arbitrary lifecycles, we're back to where we were with C -- managing resource lifecycles manually. In a server application where clients make a persistent network connection to the server for the duration of a session (like a multiplayer game server), any resources acquired on a per-user basis (including the socket connection) must be released when the user logs out. Good organization can help; if the sole reference to per-user resources is held in an ActiveUser object, they can be released when the ActiveUser is released (whether explicitly or through garbage collection).

Resources with arbitrary lifecycles are almost certainly going to be stored in (or reachable from) a global collection somewhere. To avoid resource leaks, it is therefore critical to identify when the resource is no longer needed and remove it from this global collection. (A previous article, "Plugging memory leaks with weak references ," offers some helpful techniques.) At this point, because you know the resource is about to be released, any nonmemory resources associated with the resource can also be released at this time.

Resource ownership

A key technique for ensuring timely resource release is to maintain a strict hierarchy of ownership; with ownership comes the responsibility to release the resource. If an application creates a thread pool and the thread pool creates threads, the threads are resources that must be released (allowed to terminate) before the program can exit. But the application doesn't own the threads; the thread pool does, and therefore the thread pool must take responsibility for releasing them. Of course, it can't release them until the thread pool itself is released by the application.

Maintaining an ownership hierarchy, where each resource owns the resources it acquires and is responsible for releasing them, helps keep the mess from getting out of control. A consequence of this rule is that each resource that cannot be released solely by garbage collection, which includes any resource that directly or indirectly owns a resource that cannot be released solely by garbage collection, must provide some sort of lifecycle support, such as a close() method.

Finalizers

If the platform libraries provide finalizers for cleaning up open file handlers, which greatly reduces the risk of forgetting to close them explicitly, why aren't finalizers used more often? There are a number of reasons, foremost of which is that finalizers are very tricky to write correctly (and very easy to write incorrectly). Not only is it difficult to code them correctly, but the timing of finalization is not deterministic, and there is no guarantee that finalizers will ever even run. And finalization adds overhead to instantiation and garbage collection of finalizable objects. Don't rely on finalizers as the primary means of releasing resources.

---

Back to top

Summary

Garbage collection does an awful lot of the cleanup for us, but some resources still require explicit release, such as file handles, socket handles, threads, database connections, and semaphore permits. We can often get away with using finally blocks to release a resource if its lifetime is tied to that of a specific call frame, but longer-lived resources require a strategy for ensuring their eventual release. For any object that may directly or indirectly own an object that requires explicit release, you must provide lifecycle methods -- close() , release() , destroy() , and the like -- to ensure reliable cleanup.

Resources

Learn

• Concurrent Programming in Java (Doug Lea, Addison-Wesley, 1999): Section 3.4.1.3 of Doug Lea's comprehensive work examines the process of using semaphores to bound collections.
  
• "Plugging memory leaks with weak references " (Brian Goetz, developerWorks, November 2005): Brian discusses how weak references make it easy to express object lifecycle relationships.
  
• "Finalization, Threads, and the Java Memory Model " (Sun Developer Network, Hans Boehm): Learn just how ugly finalizers can be.
  
• The Java technology zone : Hundreds of articles about every aspect of Java programming.
  

Get products and technologies

• Alice's Restaurant (Warner Brothers, 1969): Learn all the words to Arlo Guthrie's classic folk anthem "Alice's Restaurant Massacre" from the movie soundtrack.
  
• FindBugs : This free code auditing tool can find unreleased resources and other bugs in your programs.
  

Discuss

• developerWorks blogs : Get involved in the developerWorks community.
  

About the author

Brian Goetz has been a professional software developer for over 18 years. He is a Principal Consultant at Quiotix, a software development and consulting firm located in Los Altos, California, and he serves on several JCP Expert Groups. Brian's book, Java Concurrency In Practice , will be published in early 2006 by Addison-Wesley. See Brian's published and upcoming articles in popular industry publications.