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]
