Author: jochen Date: Wed Dec 6 01:42:01 2006 New Revision: 482993 URL: http://svn.apache.org/viewvc?view=rev&rev=482993 Log: Added the FileCleanerCleanup and docs on how to use it. Submitted-By: Henry Yandell, [EMAIL PROTECTED] PR: FILEUPLOAD-120
Added: jakarta/commons/proper/fileupload/trunk/src/java/org/apache/commons/fileupload/servlet/FileCleanerCleanup.java Modified: jakarta/commons/proper/fileupload/trunk/pom.xml jakarta/commons/proper/fileupload/trunk/src/changes/changes.xml jakarta/commons/proper/fileupload/trunk/src/java/org/apache/commons/fileupload/disk/DiskFileItem.java jakarta/commons/proper/fileupload/trunk/src/java/org/apache/commons/fileupload/disk/DiskFileItemFactory.java jakarta/commons/proper/fileupload/trunk/xdocs/using.xml Modified: jakarta/commons/proper/fileupload/trunk/pom.xml URL: http://svn.apache.org/viewvc/jakarta/commons/proper/fileupload/trunk/pom.xml?view=diff&rev=482993&r1=482992&r2=482993 ============================================================================== --- jakarta/commons/proper/fileupload/trunk/pom.xml (original) +++ jakarta/commons/proper/fileupload/trunk/pom.xml Wed Dec 6 01:42:01 2006 @@ -100,6 +100,10 @@ <name>Amichai Rothman</name> <email>[EMAIL PROTECTED]</email> </contributor> + <contributor> + <name>Henry Yandell</name> + <email>[EMAIL PROTECTED]</email> + </contributor> </contributors> <scm> @@ -175,9 +179,9 @@ <scope>provided</scope> </dependency> <dependency> - <groupId>commons-io</groupId> + <groupId>org.apache.commons</groupId> <artifactId>commons-io</artifactId> - <version>1.1</version> + <version>1.3-SNAPSHOT</version> <optional>true</optional> </dependency> </dependencies> Modified: jakarta/commons/proper/fileupload/trunk/src/changes/changes.xml URL: http://svn.apache.org/viewvc/jakarta/commons/proper/fileupload/trunk/src/changes/changes.xml?view=diff&rev=482993&r1=482992&r2=482993 ============================================================================== --- jakarta/commons/proper/fileupload/trunk/src/changes/changes.xml (original) +++ jakarta/commons/proper/fileupload/trunk/src/changes/changes.xml Wed Dec 6 01:42:01 2006 @@ -82,6 +82,12 @@ It is now possible to limit the actual file size and not the request size. </action> + + <action dev="jochen" type="add" issue="FILEUPLOAD-120" + due-to="Henry Yandell" due-to-email="[EMAIL PROTECTED]"/> + Added the FileCleanerCleanup as an example for how to close + down the FileCleaner's reaper thread nicely. + </action> </release> <release version="1.1.1" date="2006-06-08" description="Bugfix release"> Modified: jakarta/commons/proper/fileupload/trunk/src/java/org/apache/commons/fileupload/disk/DiskFileItem.java URL: http://svn.apache.org/viewvc/jakarta/commons/proper/fileupload/trunk/src/java/org/apache/commons/fileupload/disk/DiskFileItem.java?view=diff&rev=482993&r1=482992&r2=482993 ============================================================================== --- jakarta/commons/proper/fileupload/trunk/src/java/org/apache/commons/fileupload/disk/DiskFileItem.java (original) +++ jakarta/commons/proper/fileupload/trunk/src/java/org/apache/commons/fileupload/disk/DiskFileItem.java Wed Dec 6 01:42:01 2006 @@ -51,6 +51,16 @@ * [EMAIL PROTECTED] #getInputStream()} and process the file without attempting to load * it into memory, which may come handy with large files. * + * <p>When using the <code>DiskFileItemFactory</code>, then you should + * consider the following: Temporary files are automatically deleted as + * soon as they are no longer needed. (More precisely, when the + * corresponding instance of [EMAIL PROTECTED] java.io.File} is garbage collected.) + * This is done by the so-called reaper thread, which is started + * automatically when the class [EMAIL PROTECTED] FileCleaner} is loaded. + * It might make sense to terminate that thread, for example, if + * your web application ends. See the section on "Resource cleanup" + * in the users guide of commons-fileupload.</p> + * * @author <a href="mailto:[EMAIL PROTECTED]">Rafal Krzewski</a> * @author <a href="mailto:[EMAIL PROTECTED]">Sean Legassick</a> * @author <a href="mailto:[EMAIL PROTECTED]">Jason van Zyl</a> Modified: jakarta/commons/proper/fileupload/trunk/src/java/org/apache/commons/fileupload/disk/DiskFileItemFactory.java URL: http://svn.apache.org/viewvc/jakarta/commons/proper/fileupload/trunk/src/java/org/apache/commons/fileupload/disk/DiskFileItemFactory.java?view=diff&rev=482993&r1=482992&r2=482993 ============================================================================== --- jakarta/commons/proper/fileupload/trunk/src/java/org/apache/commons/fileupload/disk/DiskFileItemFactory.java (original) +++ jakarta/commons/proper/fileupload/trunk/src/java/org/apache/commons/fileupload/disk/DiskFileItemFactory.java Wed Dec 6 01:42:01 2006 @@ -20,6 +20,7 @@ import org.apache.commons.fileupload.FileItem; import org.apache.commons.fileupload.FileItemFactory; +import org.apache.commons.io.FileCleaner; /** * <p>The default [EMAIL PROTECTED] org.apache.commons.fileupload.FileItemFactory} @@ -39,6 +40,16 @@ * </ul> * </p> * + * <p>When using the <code>DiskFileItemFactory</code>, then you should + * consider the following: Temporary files are automatically deleted as + * soon as they are no longer needed. (More precisely, when the + * corresponding instance of [EMAIL PROTECTED] java.io.File} is garbage collected.) + * This is done by the so-called reaper thread, which is started + * automatically when the class [EMAIL PROTECTED] FileCleaner} is loaded. + * It might make sense to terminate that thread, for example, if + * your web application ends. See the section on "Resource cleanup" + * in the users guide of commons-fileupload.</p> + * * @author <a href="mailto:[EMAIL PROTECTED]">Martin Cooper</a> * * @since FileUpload 1.1 Added: jakarta/commons/proper/fileupload/trunk/src/java/org/apache/commons/fileupload/servlet/FileCleanerCleanup.java URL: http://svn.apache.org/viewvc/jakarta/commons/proper/fileupload/trunk/src/java/org/apache/commons/fileupload/servlet/FileCleanerCleanup.java?view=auto&rev=482993 ============================================================================== --- jakarta/commons/proper/fileupload/trunk/src/java/org/apache/commons/fileupload/servlet/FileCleanerCleanup.java (added) +++ jakarta/commons/proper/fileupload/trunk/src/java/org/apache/commons/fileupload/servlet/FileCleanerCleanup.java Wed Dec 6 01:42:01 2006 @@ -0,0 +1,48 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.commons.fileupload.servlet; + +import javax.servlet.ServletContextListener; +import javax.servlet.ServletContextEvent; + +import org.apache.commons.io.FileCleaner; + + +/** + * A servlet context listener, which ensures that the + * [EMAIL PROTECTED] org.apache.commons.io.FileCleaner FileCleaner's} reaper thread is terminated, + * when the web application is destroyed. + */ +public class FileCleanerCleanup implements ServletContextListener { + /** + * Called when the web application is initialized. Does + * nothing. + * @param sce The servlet context (ignored). + */ + public void contextInitialized(ServletContextEvent sce) { + // Does nothing. + } + + /** + * Called when the web application is being destroyed. + * Calls [EMAIL PROTECTED] FileCleaner#exitWhenFinished()}. + * @param sce The servlet context (ignored). + */ + public void contextDestroyed(ServletContextEvent sce) { + FileCleaner.exitWhenFinished(); + } +} Modified: jakarta/commons/proper/fileupload/trunk/xdocs/using.xml URL: http://svn.apache.org/viewvc/jakarta/commons/proper/fileupload/trunk/xdocs/using.xml?view=diff&rev=482993&r1=482992&r2=482993 ============================================================================== --- jakarta/commons/proper/fileupload/trunk/xdocs/using.xml (original) +++ jakarta/commons/proper/fileupload/trunk/xdocs/using.xml Wed Dec 6 01:42:01 2006 @@ -273,6 +273,64 @@ ...]]></source> </section> + <section name="Resource cleanup"> + <p> + This section applies only, if you are using the + <a href="apidocs/org/apache/commons/fileupload/disk/DiskFileItem.html">DiskFileItem</a>. + In other words, it applies, if your uploaded files are written to + temporary files before processing them. + </p> + <p> + Such temporary files are deleted automatically, if they are no longer + used (more precisely, if the corresponding instance of <code>java.io.File</code> + is garbage collected. This is done silently by the <code>org.apache.commons.io.FileCleaner</code> + class, which starts a reaper thread. + </p> + <p> + This reaper thread should be stopped, if it is no longer needed. In + a servlet environment, this is done by using a special servlet + context listener, called + <a href="apidocs/org/apache/commons/fileupload/servlet/FileCleanerCleanup.html">FileCleanerCleanup</a>. + To do so, add a section like the following to your <code>web.xml</code>: +<source><![CDATA[ +<web-app> + ... + <listener> + <listener-class> + org.apache.commons.fileupload.servlet.FileCleanerCleanup + </listener-class> + </listener> + ... +</web-app> +]]></source> + </p> + <p> + Unfortunately, this is not the whole story. The above applies only, if + </p> + <ol> + <li>You are using commons-io 1.3, or later.</li> + <li>You are loading commons-io from your web applications + WEB-INF/lib and not from another location, for example the + common/lib directory of Tomcat. This is not unlikely, because + there are quite a few applications, which do ship commons-io.</li> + </ol> + <p> + If commons-io 1.3 is loaded from your containers class path, then + the following might occur: Suggest that you have two applications, + called A and B running. (It might as well be the same application + with two names aka servlet contexts.) Both applications are using + the <code>FileCleanerCleanup</code>. Now, if you terminate application + A, but B is still running, then A terminates B's reaper thread as + well. + </p> + <p> + In other words, you should consider carefully, whether to use + the <code>FileCleanerCleanup</code>, or not. When unsure, or if you + are happy with commons-fileupload 1.1.1, or before, then you + possibly would like to avoid it. + </p> + </section> + <section name="Interaction with virus scanners"> <p> Virus scanners running on the same system as the web container can cause --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]