A finalize method can “resurrect” an object by making it referenced again—for example, by adding it to a static list of objects. Resurrection is discouraged, but there is nothing the system can do to stop you.

However, the virtual machine invokes finalize at most once on any object, even if that object becomes unreachable more than once because a previous finalize resurrected it. If resurrecting objects is important to your design, the object would be resurrected only once—probably not the behavior you wanted.

If you think you need to resurrect objects, you should review your design carefully—you may uncover a flaw. If your design review convinces you that you need something like resurrection, the best solution is to clone the object or create a new object, not to resurrect it. The finalize method can insert a reference to a new object that will continue the state of the dying object rather than a reference to the dying object itself. Being new, the cloned object's finalize method will be invoked in the future (if needed), enabling it to insert yet another copy of itself in yet another list, ensuring the survival, if not of itself, at least of its progeny.

The classes for the reference object types are contained in the package java.lang.ref. The primary class is the generic, abstract class Reference<T>, which is the superclass of all the specific reference classes. It has four methods:

We defer a discussion of reference queues until Section 17.5.3 on page 459.

Subclasses of Reference provide ways to bind the referent object to the reference object—the existing subclasses do this with a constructor argument. Once an object has been wrapped in a reference object you can retrieve the object via get (and thus have a normal strong reference to it) or you can clear the reference, perhaps making the referent unreachable. There is no means to change the object referred to by the reference object and you cannot subclass Reference directly.

In decreasing order of strength, the kinds of reference objects available to you are SoftReference<T>, WeakReference<T>, and PhantomReference<T>. These correspond to the reachability stages an object can pass through:

Once an object becomes weakly reachable (or less), it can be finalized. If after finalization the object is unreachable, it can be reclaimed.

Objects need not actually go through all these stages. For example, an object that is reachable only through strong references becomes unreachable when it is no longer strongly reachable.

The reachability stages of an object trigger behavior in the garbage collector appropriate to the corresponding reference object types:

Both SoftReference and WeakReference declare a constructor that takes a single referent object. All three classes declare a two-argument constructor that takes a referent object and a ReferenceQueue.

Soft references provide you with a kind of caching behavior, clearing older references while trying not to clear new or used ones. Consider our web browser scenario. If you maintain your images in soft references, they will be reclaimed as memory runs low. Images are probably relatively unimportant to keep in memory should memory run low, and clearing the oldest or least used images would be a reasonable approach. In contrast, if you used weak references then all images would be reclaimed as soon as memory got low—this would probably induce a lot of overhead as you reload images that it may not have been necessary to get rid of in the first place.

Weak references are a way of holding a reference to an object but saying “reclaim this object if this is the only type of reference to it.”

Consider the following method that returns data read into memory from a file. The method has been optimized under the assumption that the same file is often named more than once in a row and that reading the data is expensive:

import java.lang.ref.*;
import java.io.File;

class DataHandler {
    private File lastFile;          // last file read
    private WeakReference<byte[]> 
                          lastData; // last data (maybe)

    byte[] readFile(File file) {
        byte[] data;

        // check to see if we remember the data
        if (file.equals(lastFile)) {
            data = lastData.get();
            if (data != null)
                return data;
        }

        // don't remember it, read it in
        data = readBytesFromFile(file);
        lastFile = file;
        lastData = new WeakReference<byte[]>(data);


        return data;
    }
}

When readFile is called it first checks to see if the last file read was the same as the one being requested. If it is, readFile retrieves the reference stored in lastData, which is a weak reference to the last array of bytes returned. If the reference returned by get is null, the data has been garbage collected since it was last returned and so it must be re-read. The data is then wrapped in a new WeakReference. If get returns a non-null reference, the array has not been collected and can be returned.

If lastData were a direct, strong reference to the last data returned, that data would not be collected, even if the invoking program had long since dropped all references to the array. Such a strong reference would keep the object alive as long as the DataHandler object itself was reachable. This could be quite unfortunate. Using a WeakReference allows the space to be reclaimed, at the cost of occasionally re-reading the data from disk.

Notice that invoking get on lastData makes the byte array strongly reachable once again because its value is bound to an active local variable—a strong reference. If get returns a non-null reference there is no possibility of the byte array being reclaimed as long as readFile is executing, or the block of code to which readFile returns the reference is executing. That invoking code can store the reference in a reachable place or return it to another method, thereby ensuring the data's reachability. An object can only be less than strongly reachable when none of its references are strong. Storing a non-null reference fetched from a reference object's get method creates a strong reference that will be treated like any other strong reference.

Weak references typically store information about an object that might be time consuming to compute but that need not outlive the object itself. For example, if you had some complicated information built up from using reflection on an object, you might use the java.util.WeakHashMap class, which is a hashtable for mapping a weakly-held object to your information. If the object becomes unreachable the WeakHashMap will clean up the associated information, which presumably is no longer useful (since the object will not be used in any future computation because of its weak reachability). You will learn about WeakHashMap with the rest of the collection classes in Chapter 21, specifically in Section 21.9 on page 594.

Exercise 17.2: Modify DataHandler so that lastFile is also stored weakly.

When an object changes reachability state, references to the object may be placed on a reference queue. These queues are used by the garbage collector to communicate with your code about reachability changes. They are usually the best way to detect such changes, although you can sometimes poll for changes as well, by seeing if get returns null.

Reference objects can be associated with a particular queue when they are constructed. Each of the Reference subclasses provide a constructor of the form

Both weak and soft references are enqueued at some point after the garbage collector determines that their referent has entered that particular reachability state, and in both cases they are cleared before being enqueued. Phantom references are also enqueued at some point after the garbage collector determines the referent is phantom reachable, but they are not cleared. Once a reference object has been queued by the garbage collector, it is guaranteed that get will return null, and so the object cannot be resurrected.

Registering a reference object with a reference queue does not create a reference between the queue and the reference object. If your reference object itself becomes unreachable, then it will never be enqueued. So your application needs to keep a strong reference to all reference objects.

The ReferenceQueue class provides three methods for removing references from the queue:

The poll method allows a thread to query the existence of a reference in a queue, taking action only if one is present, as in the example. The remove methods are intended for more complex (and rare) situations in which a dedicated thread is responsible for removing references from the queue and taking the appropriate action—the blocking behavior of these methods is the same as that defined by Object.wait (as discussed from page 354). You can ask whether a particular reference is in a queue via its isEnqueued method. You can force a reference into its queue by calling its enqueue method, but usually this is done by the garbage collector.

Reference queues are used with phantom references to determine when an object is about to be reclaimed. A phantom reference never lets you reach the object, even when it is otherwise reachable: Its get method always returns null. In effect it is the safest way to find out about a collected object—a weak or soft reference will be enqueued after an object is finalizable; a phantom reference is enqueued after the referent has been finalized and, therefore only after the last possible time that the object can do something. If you can, you should generally use a phantom reference because the other references still allow the possibility that a finalize method will use the object.

Consider a resource manager that controls access to some set of external resources. Objects can request access to a resource and use it until they are done, after which they should return the resource back to the resource manager. If the resource is shared, and use of it is passed from object to object, perhaps even across multiple threads, then it can be difficult to determine which use of the resource is the last use. That makes it difficult to determine which piece of code is responsible for returning the resource. To deal with this situation, the resource manager can automate the recovery of the resource by associating with it a special object called the key. As long as the key object is reachable, the resource is considered in use. As soon as the key object can be reclaimed, the resource is automatically released. Here's an abstract representation of such a resource:

interface Resource {
    void use(Object key, Object... args);
    void release();
}

When a resource is obtained, a key must be presented to the resource manager. The Resource instance that is given back will only allow use of the resource when presented with that key. This ensures that the resource cannot be used after the key has been reclaimed, even though the Resource object itself may still be reachable. Note that it is important that the Resource object not store a strong reference to the key object, since that would prevent the key from ever becoming unreachable, and so the resource could never be recovered. A Resource implementation class might be nested in the resource manager:

private static class ResourceImpl implements Resource {
    int keyHash;
    boolean needsRelease = false;

    ResourceImpl(Object key) {
        keyHash = System.identityHashCode(key);

        // .. set up the external resource

        needsRelease = true;
    }

    public void use(Object key, Object... args) {
        if (System.identityHashCode(key) != keyHash)
            throw new IllegalArgumentException("wrong key");

        // ... use the resource ...
    }

    public synchronized void release() {
        if (needsRelease) {
            needsRelease = false;

            // .. release the resource ...
        }
    }
}

When the resource is created it stores the identity hash code of the key, and whenever use is called, it checks that the same key was provided. Actually using the resource may require additional synchronization, but for simplicity this is elided. The release method is responsible for releasing the resource. It can either be called directly by the users of the resource when they have finished, or it will be called through the resource manager when the key object is no longer referenced. Because we will be using a separate thread to watch the reference queue, release has to be synchronized and it has to be tolerant to being called more than once.

The actual resource manager looks like this:

public final class ResourceManager {

    final ReferenceQueue<Object> queue;
    final Map<Reference<?>, Resource> refs;
    final Thread reaper;
    boolean shutdown = false;

    public ResourceManager() {
        queue = new ReferenceQueue<Object>();
        refs = new HashMap<Reference<?>, Resource>();
        reaper = new ReaperThread();
        reaper.start();

        // ... initialize resources ...
    }

    public synchronized void shutdown() {
        if (!shutdown) {
            shutdown = true;
            reaper.interrupt();
        }
    }

    public synchronized Resource getResource(Object key) {
        if (shutdown)
            throw new IllegalStateException();
        Resource res = new ResourceImpl(key);
        Reference<?> ref =
            new PhantomReference<Object>(key, queue);
        refs.put(ref, res);
        return res;
    }
}

The key object can be an arbitrary object—this gives great flexibility to the users of the resource, compared to having the resource manager assign a key. When getResource is invoked, a new ResourceImpl object is created, passing in the supplied key. A phantom reference is then created, with the key as the referent, and using the resource manager's reference queue. The phantom reference and the resource object are then stored into a map. This map serves two purposes: First, it keeps all the phantom reference objects reachable; second it provides an easy way to find the actual resource object associated with each phantom reference. (The alternative would be to subclass PhantomReference and store the Resource object in a field.)

The resource manager uses a separate “reaper” thread to process resources when the key has become unreachable. The shutdown method “turns off” the resource manager by allowing the reaper to terminate (in response to the interruption) and causing getResource calls to throw IllegalStateException. In this simple design, any references enqueued after shutdown will not be processed. The actual reaper thread looks like this:

class ReaperThread extends Thread {
    public void run() {
        // run until interrupted
        while (true) {
            try {
                Reference<?> ref =  queue.remove();
                Resource res = null;
                synchronized(ResourceManager.this) {
                    res = refs.get(ref);
                    refs.remove(ref);
                }
                res.release();
                ref.clear();
            }
            catch (InterruptedException ex) {
                break; // all done
            }
        }
    }
}

ReaperThread is an inner class, and a given reaper thread runs until its associated resource manager is shut down. It blocks on remove until a phantom reference associated with a particular key has been enqueued. The phantom reference is used to get a reference to the Resource object from the map, and then that entry is removed from the map. The Resource object then has release invoked on it to release the resource. Finally, the phantom reference is cleared so that the key can actually be reclaimed.

As an alternative to using a separate thread, the getResource method could instead poll the queue whenever it is called and release any resources whose key has become unreachable. The shutdown method could then do a final poll, too. The semantics for the resource manager necessarily depend on the actual kind of resource and its usage patterns.

A design that uses reference queues can be more reliable than direct use of finalization—particularly with phantom references—but remember that there are no guarantees as to exactly when or in what order a reference object will be enqueued. There are also no guarantees that by the time an application terminates, all enqueuable reference objects will have been enqueued. If you need to guarantee that all resources are released before the application terminates, you must install the necessary shutdown hooks (see “Shutdown” on page 672) or other application-defined protocols to ensure this happens.

Exercise 17.3: Rework the resource implementation class so that it uses a reference object to keep track of the key instead of using the hash code.

Exercise 17.4: Modify the reaper thread so that it stays alive after shutdown until all the allocated resources can be released.

Exercise 17.5: Redesign the resource manager to not use a reaper thread. Be clear on what semantics the resource manager has and on when resources will be released.

An object becomes finalizable when it becomes weakly reachable (or less). It would seem that to determine reachability you need simply examine the source code for your applications. Unfortunately, such an examination would often be wrong. Reachability is not determined by the statements in your source code, but by the actual state of the virtual machine at runtime. The virtual machine can perform certain optimizations that make an object unreachable much sooner than a simple examination of the source code would indicate.

For example, suppose a method creates an object that controls an external resource and that the only reference is through a local variable. The method then uses the external resource and finally nulls the local reference or simply returns, allowing the object to be finalized and release the external resource. The programmer might assume that the object is reachable until that reference is set to null or the method returns. But the virtual machine can detect that the object is not referenced within the method and may deem it unreachable and finalizable the instant after it was constructed, causing immediate finalization and release of the resource, which was not something the programmer intended. Even the reference queue designs that we have discussed depend on the referent remaining reachable as long as the programmer expects it to be reachable.

The optimizations under consideration only apply to references held on the stack—that is, references stored in local variables or parameters. If a reference is stored in a field, then the object remains reachable at least until the field no longer refers to it. This approach also covers the case of inner class objects—an inner class instance is reachable whenever its enclosing instance is reachable.

There are further subtle interactions between finalization, synchronization, and the memory model, but these are advanced topics unneeded by most programmers and are beyond the scope of this book.