1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.io; 18 19 import java.io.File; 20 21 /** 22 * Keeps track of files awaiting deletion, and deletes them when an associated 23 * marker object is reclaimed by the garbage collector. 24 * <p> 25 * This utility creates a background thread to handle file deletion. 26 * Each file to be deleted is registered with a handler object. 27 * When the handler object is garbage collected, the file is deleted. 28 * <p> 29 * In an environment with multiple class loaders (a servlet container, for 30 * example), you should consider stopping the background thread if it is no 31 * longer needed. This is done by invoking the method 32 * {@link #exitWhenFinished}, typically in 33 * {@link javax.servlet.ServletContextListener#contextDestroyed} or similar. 34 * 35 * @author Noel Bergman 36 * @author Martin Cooper 37 * @version $Id: FileCleaner.java 551002 2007-06-27 01:33:05Z jochen $ 38 */ 39 public class FileCleaner { 40 /** 41 * The instance to use for the deprecated, static methods. 42 */ 43 static final FileCleaningTracker theInstance = new FileCleaningTracker(); 44 45 //----------------------------------------------------------------------- 46 /** 47 * Track the specified file, using the provided marker, deleting the file 48 * when the marker instance is garbage collected. 49 * The {@link FileDeleteStrategy#NORMAL normal} deletion strategy will be used. 50 * 51 * @param file the file to be tracked, not null 52 * @param marker the marker object used to track the file, not null 53 * @throws NullPointerException if the file is null 54 */ 55 public static void track(File file, Object marker) { 56 theInstance.track(file, marker); 57 } 58 59 /** 60 * Track the specified file, using the provided marker, deleting the file 61 * when the marker instance is garbage collected. 62 * The speified deletion strategy is used. 63 * 64 * @param file the file to be tracked, not null 65 * @param marker the marker object used to track the file, not null 66 * @param deleteStrategy the strategy to delete the file, null means normal 67 * @throws NullPointerException if the file is null 68 */ 69 public static void track(File file, Object marker, FileDeleteStrategy deleteStrategy) { 70 theInstance.track(file, marker, deleteStrategy); 71 } 72 73 /** 74 * Track the specified file, using the provided marker, deleting the file 75 * when the marker instance is garbage collected. 76 * The {@link FileDeleteStrategy#NORMAL normal} deletion strategy will be used. 77 * 78 * @param path the full path to the file to be tracked, not null 79 * @param marker the marker object used to track the file, not null 80 * @throws NullPointerException if the path is null 81 */ 82 public static void track(String path, Object marker) { 83 theInstance.track(path, marker); 84 } 85 86 /** 87 * Track the specified file, using the provided marker, deleting the file 88 * when the marker instance is garbage collected. 89 * The speified deletion strategy is used. 90 * 91 * @param path the full path to the file to be tracked, not null 92 * @param marker the marker object used to track the file, not null 93 * @param deleteStrategy the strategy to delete the file, null means normal 94 * @throws NullPointerException if the path is null 95 */ 96 public static void track(String path, Object marker, FileDeleteStrategy deleteStrategy) { 97 theInstance.track(path, marker, deleteStrategy); 98 } 99 100 //----------------------------------------------------------------------- 101 /** 102 * Retrieve the number of files currently being tracked, and therefore 103 * awaiting deletion. 104 * 105 * @return the number of files being tracked 106 */ 107 public static int getTrackCount() { 108 return theInstance.getTrackCount(); 109 } 110 111 /** 112 * Call this method to cause the file cleaner thread to terminate when 113 * there are no more objects being tracked for deletion. 114 * <p> 115 * In a simple environment, you don't need this method as the file cleaner 116 * thread will simply exit when the JVM exits. In a more complex environment, 117 * with multiple class loaders (such as an application server), you should be 118 * aware that the file cleaner thread will continue running even if the class 119 * loader it was started from terminates. This can consitute a memory leak. 120 * <p> 121 * For example, suppose that you have developed a web application, which 122 * contains the commons-io jar file in your WEB-INF/lib directory. In other 123 * words, the FileCleaner class is loaded through the class loader of your 124 * web application. If the web application is terminated, but the servlet 125 * container is still running, then the file cleaner thread will still exist, 126 * posing a memory leak. 127 * <p> 128 * This method allows the thread to be terminated. Simply call this method 129 * in the resource cleanup code, such as {@link javax.servlet.ServletContextListener#contextDestroyed}. 130 * One called, no new objects can be tracked by the file cleaner. 131 */ 132 public static synchronized void exitWhenFinished() { 133 theInstance.exitWhenFinished(); 134 } 135 136 /** 137 * Returns the singleton instance, which is used by the deprecated, static methods. 138 * This is mainly useful for code, which wants to support the new 139 * {@link FileCleaningTracker} class while maintain compatibility with the 140 * deprecated {@link FileCleaner}. 141 */ 142 public static FileCleaningTracker getInstance() { 143 return theInstance; 144 } 145 }