Update #0 - First Release

sources/main/java/com/google/common/base/FinalizableReferenceQueue.java

@@ -0,0 +1,371 @@
+/*
+ * Copyright (C) 2007 The Guava Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.common.base;
+
+import java.io.Closeable;
+import java.io.FileNotFoundException;
+import java.io.IOException;
+import java.lang.ref.PhantomReference;
+import java.lang.ref.Reference;
+import java.lang.ref.ReferenceQueue;
+import java.lang.reflect.Method;
+import java.net.URL;
+import java.net.URLClassLoader;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+import com.google.common.annotations.VisibleForTesting;
+
+/**
+ * A reference queue with an associated background thread that dequeues
+ * references and invokes {@link FinalizableReference#finalizeReferent()} on
+ * them.
+ *
+ * <p>
+ * Keep a strong reference to this object until all of the associated referents
+ * have been finalized. If this object is garbage collected earlier, the backing
+ * thread will not invoke {@code
+ * finalizeReferent()} on the remaining references.
+ *
+ * <p>
+ * As an example of how this is used, imagine you have a class {@code MyServer}
+ * that creates a a {@link java.net.ServerSocket ServerSocket}, and you would
+ * like to ensure that the {@code ServerSocket} is closed even if the
+ * {@code MyServer} object is garbage-collected without calling its
+ * {@code close} method. You <em>could</em> use a finalizer to accomplish this,
+ * but that has a number of well-known problems. Here is how you might use this
+ * class instead:
+ *
+ * <pre>
+ * public class MyServer implements Closeable {
+ *   private static final FinalizableReferenceQueue frq = new FinalizableReferenceQueue();
+ *   // You might also share this between several objects.
+ *
+ *   private static final Set&lt;Reference&lt;?>> references = Sets.newConcurrentHashSet();
+ *   // This ensures that the FinalizablePhantomReference itself is not garbage-collected.
+ *
+ *   private final ServerSocket serverSocket;
+ *
+ *   private MyServer(...) {
+ *     ...
+ *     this.serverSocket = new ServerSocket(...);
+ *     ...
+ *   }
+ *
+ *   public static MyServer create(...) {
+ *     MyServer myServer = new MyServer(...);
+ *     final ServerSocket serverSocket = myServer.serverSocket;
+ *     Reference&lt;?> reference = new FinalizablePhantomReference&lt;MyServer>(myServer, frq) {
+ *       &#64;Override public void finalizeReferent() {
+ *         references.remove(this):
+ *         if (!serverSocket.isClosed()) {
+ *           ...log a message about how nobody called close()...
+ *           try {
+ *             serverSocket.close();
+ *           } catch (IOException e) {
+ *             ...
+ *           }
+ *         }
+ *       }
+ *     };
+ *     references.add(reference);
+ *     return myServer;
+ *   }
+ *
+ *   &#64;Override public void close() {
+ *     serverSocket.close();
+ *   }
+ * }
+ * </pre>
+ *
+ * @author Bob Lee
+ * @since 2.0 (imported from Google Collections Library)
+ */
+public class FinalizableReferenceQueue implements Closeable {
+	/*
+	 * The Finalizer thread keeps a phantom reference to this object. When the
+	 * client (for example, a map built by MapMaker) no longer has a strong
+	 * reference to this object, the garbage collector will reclaim it and enqueue
+	 * the phantom reference. The enqueued reference will trigger the Finalizer to
+	 * stop.
+	 *
+	 * If this library is loaded in the system class loader,
+	 * FinalizableReferenceQueue can load Finalizer directly with no problems.
+	 *
+	 * If this library is loaded in an application class loader, it's important that
+	 * Finalizer not have a strong reference back to the class loader. Otherwise,
+	 * you could have a graph like this:
+	 *
+	 * Finalizer Thread runs instance of -> Finalizer.class loaded by -> Application
+	 * class loader which loaded -> ReferenceMap.class which has a static ->
+	 * FinalizableReferenceQueue instance
+	 *
+	 * Even if no other references to classes from the application class loader
+	 * remain, the Finalizer thread keeps an indirect strong reference to the queue
+	 * in ReferenceMap, which keeps the Finalizer running, and as a result, the
+	 * application class loader can never be reclaimed.
+	 *
+	 * This means that dynamically loaded web applications and OSGi bundles can't be
+	 * unloaded.
+	 *
+	 * If the library is loaded in an application class loader, we try to break the
+	 * cycle by loading Finalizer in its own independent class loader:
+	 *
+	 * System class loader -> Application class loader -> ReferenceMap ->
+	 * FinalizableReferenceQueue -> etc. -> Decoupled class loader -> Finalizer
+	 *
+	 * Now, Finalizer no longer keeps an indirect strong reference to the static
+	 * FinalizableReferenceQueue field in ReferenceMap. The application class loader
+	 * can be reclaimed at which point the Finalizer thread will stop and its
+	 * decoupled class loader can also be reclaimed.
+	 *
+	 * If any of this fails along the way, we fall back to loading Finalizer
+	 * directly in the application class loader.
+	 */
+
+	private static final Logger logger = Logger.getLogger(FinalizableReferenceQueue.class.getName());
+
+	private static final String FINALIZER_CLASS_NAME = "com.google.common.base.internal.Finalizer";
+
+	/** Reference to Finalizer.startFinalizer(). */
+	private static final Method startFinalizer;
+	static {
+		Class<?> finalizer = loadFinalizer(new SystemLoader(), new DecoupledLoader(), new DirectLoader());
+		startFinalizer = getStartFinalizer(finalizer);
+	}
+
+	/**
+	 * The actual reference queue that our background thread will poll.
+	 */
+	final ReferenceQueue<Object> queue;
+
+	final PhantomReference<Object> frqRef;
+
+	/**
+	 * Whether or not the background thread started successfully.
+	 */
+	final boolean threadStarted;
+
+	/**
+	 * Constructs a new queue.
+	 */
+	public FinalizableReferenceQueue() {
+		// We could start the finalizer lazily, but I'd rather it blow up early.
+		queue = new ReferenceQueue<Object>();
+		frqRef = new PhantomReference<Object>(this, queue);
+		boolean threadStarted = false;
+		try {
+			startFinalizer.invoke(null, FinalizableReference.class, queue, frqRef);
+			threadStarted = true;
+		} catch (IllegalAccessException impossible) {
+			throw new AssertionError(impossible); // startFinalizer() is public
+		} catch (Throwable t) {
+			logger.log(Level.INFO, "Failed to start reference finalizer thread."
+					+ " Reference cleanup will only occur when new references are created.", t);
+		}
+
+		this.threadStarted = threadStarted;
+	}
+
+	@Override
+	public void close() {
+		frqRef.enqueue();
+		cleanUp();
+	}
+
+	/**
+	 * Repeatedly dequeues references from the queue and invokes
+	 * {@link FinalizableReference#finalizeReferent()} on them until the queue is
+	 * empty. This method is a no-op if the background thread was created
+	 * successfully.
+	 */
+	void cleanUp() {
+		if (threadStarted) {
+			return;
+		}
+
+		Reference<?> reference;
+		while ((reference = queue.poll()) != null) {
+			/*
+			 * This is for the benefit of phantom references. Weak and soft references will
+			 * have already been cleared by this point.
+			 */
+			reference.clear();
+			try {
+				((FinalizableReference) reference).finalizeReferent();
+			} catch (Throwable t) {
+				logger.log(Level.SEVERE, "Error cleaning up after reference.", t);
+			}
+		}
+	}
+
+	/**
+	 * Iterates through the given loaders until it finds one that can load
+	 * Finalizer.
+	 *
+	 * @return Finalizer.class
+	 */
+	private static Class<?> loadFinalizer(FinalizerLoader... loaders) {
+		for (FinalizerLoader loader : loaders) {
+			Class<?> finalizer = loader.loadFinalizer();
+			if (finalizer != null) {
+				return finalizer;
+			}
+		}
+
+		throw new AssertionError();
+	}
+
+	/**
+	 * Loads Finalizer.class.
+	 */
+	interface FinalizerLoader {
+
+		/**
+		 * Returns Finalizer.class or null if this loader shouldn't or can't load it.
+		 *
+		 * @throws SecurityException if we don't have the appropriate privileges
+		 */
+		Class<?> loadFinalizer();
+	}
+
+	/**
+	 * Tries to load Finalizer from the system class loader. If Finalizer is in the
+	 * system class path, we needn't create a separate loader.
+	 */
+	static class SystemLoader implements FinalizerLoader {
+		// This is used by the ClassLoader-leak test in FinalizableReferenceQueueTest to
+		// disable
+		// finding Finalizer on the system class path even if it is there.
+		@VisibleForTesting
+		static boolean disabled;
+
+		@Override
+		public Class<?> loadFinalizer() {
+			if (disabled) {
+				return null;
+			}
+			ClassLoader systemLoader;
+			try {
+				systemLoader = ClassLoader.getSystemClassLoader();
+			} catch (SecurityException e) {
+				logger.info("Not allowed to access system class loader.");
+				return null;
+			}
+			if (systemLoader != null) {
+				try {
+					return systemLoader.loadClass(FINALIZER_CLASS_NAME);
+				} catch (ClassNotFoundException e) {
+					// Ignore. Finalizer is simply in a child class loader.
+					return null;
+				}
+			} else {
+				return null;
+			}
+		}
+	}
+
+	/**
+	 * Try to load Finalizer in its own class loader. If Finalizer's thread had a
+	 * direct reference to our class loader (which could be that of a dynamically
+	 * loaded web application or OSGi bundle), it would prevent our class loader
+	 * from getting garbage collected.
+	 */
+	static class DecoupledLoader implements FinalizerLoader {
+		private static final String LOADING_ERROR = "Could not load Finalizer in its own class loader."
+				+ "Loading Finalizer in the current class loader instead. As a result, you will not be able"
+				+ "to garbage collect this class loader. To support reclaiming this class loader, either"
+				+ "resolve the underlying issue, or move Google Collections to your system class path.";
+
+		@Override
+		public Class<?> loadFinalizer() {
+			try {
+				/*
+				 * We use URLClassLoader because it's the only concrete class loader
+				 * implementation in the JDK. If we used our own ClassLoader subclass, Finalizer
+				 * would indirectly reference this class loader:
+				 *
+				 * Finalizer.class -> CustomClassLoader -> CustomClassLoader.class -> This class
+				 * loader
+				 *
+				 * System class loader will (and must) be the parent.
+				 */
+				ClassLoader finalizerLoader = newLoader(getBaseUrl());
+				return finalizerLoader.loadClass(FINALIZER_CLASS_NAME);
+			} catch (Exception e) {
+				logger.log(Level.WARNING, LOADING_ERROR, e);
+				return null;
+			}
+		}
+
+		/**
+		 * Gets URL for base of path containing Finalizer.class.
+		 */
+		URL getBaseUrl() throws IOException {
+			// Find URL pointing to Finalizer.class file.
+			String finalizerPath = FINALIZER_CLASS_NAME.replace('.', '/') + ".class";
+			URL finalizerUrl = getClass().getClassLoader().getResource(finalizerPath);
+			if (finalizerUrl == null) {
+				throw new FileNotFoundException(finalizerPath);
+			}
+
+			// Find URL pointing to base of class path.
+			String urlString = finalizerUrl.toString();
+			if (!urlString.endsWith(finalizerPath)) {
+				throw new IOException("Unsupported path style: " + urlString);
+			}
+			urlString = urlString.substring(0, urlString.length() - finalizerPath.length());
+			return new URL(finalizerUrl, urlString);
+		}
+
+		/** Creates a class loader with the given base URL as its classpath. */
+		URLClassLoader newLoader(URL base) {
+			// We use the bootstrap class loader as the parent because Finalizer by design
+			// uses
+			// only standard Java classes. That also means that
+			// FinalizableReferenceQueueTest
+			// doesn't pick up the wrong version of the Finalizer class.
+			return new URLClassLoader(new URL[] { base }, null);
+		}
+	}
+
+	/**
+	 * Loads Finalizer directly using the current class loader. We won't be able to
+	 * garbage collect this class loader, but at least the world doesn't end.
+	 */
+	static class DirectLoader implements FinalizerLoader {
+		@Override
+		public Class<?> loadFinalizer() {
+			try {
+				return Class.forName(FINALIZER_CLASS_NAME);
+			} catch (ClassNotFoundException e) {
+				throw new AssertionError(e);
+			}
+		}
+	}
+
+	/**
+	 * Looks up Finalizer.startFinalizer().
+	 */
+	static Method getStartFinalizer(Class<?> finalizer) {
+		try {
+			return finalizer.getMethod("startFinalizer", Class.class, ReferenceQueue.class, PhantomReference.class);
+		} catch (NoSuchMethodException e) {
+			throw new AssertionError(e);
+		}
+	}
+}