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 * {@code javax.servlet.ServletContextListener.contextDestroyed(javax.servlet.ServletContextEvent)} or similar. 34 * 35 * @deprecated Use {@link FileCleaningTracker} 36 */ 37 @Deprecated 38 public class FileCleaner { 39 40 /** 41 * The instance to use for the deprecated, static methods. 42 */ 43 private static final FileCleaningTracker INSTANCE = new FileCleaningTracker(); 44 45 /** 46 * Call this method to cause the file cleaner thread to terminate when 47 * there are no more objects being tracked for deletion. 48 * <p> 49 * In a simple environment, you don't need this method as the file cleaner 50 * thread will simply exit when the JVM exits. In a more complex environment, 51 * with multiple class loaders (such as an application server), you should be 52 * aware that the file cleaner thread will continue running even if the class 53 * loader it was started from terminates. This can constitute a memory leak. 54 * <p> 55 * For example, suppose that you have developed a web application, which 56 * contains the commons-io jar file in your WEB-INF/lib directory. In other 57 * words, the FileCleaner class is loaded through the class loader of your 58 * web application. If the web application is terminated, but the servlet 59 * container is still running, then the file cleaner thread will still exist, 60 * posing a memory leak. 61 * <p> 62 * This method allows the thread to be terminated. Simply call this method 63 * in the resource cleanup code, such as 64 * {@code javax.servlet.ServletContextListener.contextDestroyed(javax.servlet.ServletContextEvent)}. 65 * One called, no new objects can be tracked by the file cleaner. 66 * @deprecated Use {@link FileCleaningTracker#exitWhenFinished()}. 67 */ 68 @Deprecated exitWhenFinished()69 public static synchronized void exitWhenFinished() { 70 INSTANCE.exitWhenFinished(); 71 } 72 73 /** 74 * Returns the singleton instance, which is used by the deprecated, static methods. 75 * This is mainly useful for code, which wants to support the new 76 * {@link FileCleaningTracker} class while maintain compatibility with the 77 * deprecated {@link FileCleaner}. 78 * 79 * @return the singleton instance 80 */ getInstance()81 public static FileCleaningTracker getInstance() { 82 return INSTANCE; 83 } 84 85 /** 86 * Retrieve the number of files currently being tracked, and therefore 87 * awaiting deletion. 88 * 89 * @return the number of files being tracked 90 * @deprecated Use {@link FileCleaningTracker#getTrackCount()}. 91 */ 92 @Deprecated getTrackCount()93 public static int getTrackCount() { 94 return INSTANCE.getTrackCount(); 95 } 96 97 /** 98 * Track the specified file, using the provided marker, deleting the file 99 * when the marker instance is garbage collected. 100 * The {@link FileDeleteStrategy#NORMAL normal} deletion strategy will be used. 101 * 102 * @param file the file to be tracked, not null 103 * @param marker the marker object used to track the file, not null 104 * @throws NullPointerException if the file is null 105 * @deprecated Use {@link FileCleaningTracker#track(File, Object)}. 106 */ 107 @Deprecated track(final File file, final Object marker)108 public static void track(final File file, final Object marker) { 109 INSTANCE.track(file, marker); 110 } 111 112 /** 113 * Track the specified file, using the provided marker, deleting the file 114 * when the marker instance is garbage collected. 115 * The specified deletion strategy is used. 116 * 117 * @param file the file to be tracked, not null 118 * @param marker the marker object used to track the file, not null 119 * @param deleteStrategy the strategy to delete the file, null means normal 120 * @throws NullPointerException if the file is null 121 * @deprecated Use {@link FileCleaningTracker#track(File, Object, FileDeleteStrategy)}. 122 */ 123 @Deprecated track(final File file, final Object marker, final FileDeleteStrategy deleteStrategy)124 public static void track(final File file, final Object marker, final FileDeleteStrategy deleteStrategy) { 125 INSTANCE.track(file, marker, deleteStrategy); 126 } 127 128 /** 129 * Track the specified file, using the provided marker, deleting the file 130 * when the marker instance is garbage collected. 131 * The {@link FileDeleteStrategy#NORMAL normal} deletion strategy will be used. 132 * 133 * @param path the full path to the file to be tracked, not null 134 * @param marker the marker object used to track the file, not null 135 * @throws NullPointerException if the path is null 136 * @deprecated Use {@link FileCleaningTracker#track(String, Object)}. 137 */ 138 @Deprecated track(final String path, final Object marker)139 public static void track(final String path, final Object marker) { 140 INSTANCE.track(path, marker); 141 } 142 143 /** 144 * Track the specified file, using the provided marker, deleting the file 145 * when the marker instance is garbage collected. 146 * The specified deletion strategy is used. 147 * 148 * @param path the full path to the file to be tracked, not null 149 * @param marker the marker object used to track the file, not null 150 * @param deleteStrategy the strategy to delete the file, null means normal 151 * @throws NullPointerException if the path is null 152 * @deprecated Use {@link FileCleaningTracker#track(String, Object, FileDeleteStrategy)}. 153 */ 154 @Deprecated track(final String path, final Object marker, final FileDeleteStrategy deleteStrategy)155 public static void track(final String path, final Object marker, final FileDeleteStrategy deleteStrategy) { 156 INSTANCE.track(path, marker, deleteStrategy); 157 } 158 } 159