You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by jo...@apache.org on 2010/06/06 23:19:57 UTC
svn commit: r951978 [5/5] - in /commons/sandbox/commons-fileupload2: ./
.settings/ src/ src/changes/ src/checkstyle/ src/conf/ src/java/
src/java/org/ src/java/org/apache/ src/java/org/apache/commons/
src/java/org/apache/commons/fileupload2/ src/java/o...
Added: commons/sandbox/commons-fileupload2/xdocs/navigation.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/commons-fileupload2/xdocs/navigation.xml?rev=951978&view=auto
==============================================================================
--- commons/sandbox/commons-fileupload2/xdocs/navigation.xml (added)
+++ commons/sandbox/commons-fileupload2/xdocs/navigation.xml Sun Jun 6 21:19:54 2010
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ 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.
+-->
+<!DOCTYPE org.apache.commons.menus SYSTEM 'http://commons.apache.org/build/maven-build.dtd'>
+<project name="FileUpload">
+
+ <title>FileUpload</title>
+ <organizationLogo href="http://commons.apache.org/images/logo.png">
+ Commons
+ </organizationLogo>
+
+ <body>
+ <links>
+ <item name="Commons" href="http://commons.apache.org/"/>
+ </links>
+
+ <menu name="Commons FileUpload">
+ <item name="Overview" href="/index.html"/>
+ <item name="User guide" href="/using.html"/>
+ <item name="Streaming API" href="/streaming.html"/>
+ <!--item name="Customization" href="/customizing.html"/-->
+ <item name="FAQ" href="/faq.html"/>
+ <item name="Javadoc" href="apidocs/index.html"/>
+ <item name="Mailing lists" href="/mail-lists.html"/>
+ <item name="Team" href="/team-list.html"/>
+ <item name="Tasks" href="/tasks.html"/>
+ <item name="SVN repository" href="/cvs-usage.html"/>
+ </menu>
+
+ &commons;
+
+ </body>
+</project>
Propchange: commons/sandbox/commons-fileupload2/xdocs/navigation.xml
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: commons/sandbox/commons-fileupload2/xdocs/overview.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/commons-fileupload2/xdocs/overview.xml?rev=951978&view=auto
==============================================================================
--- commons/sandbox/commons-fileupload2/xdocs/overview.xml (added)
+++ commons/sandbox/commons-fileupload2/xdocs/overview.xml Sun Jun 6 21:19:54 2010
@@ -0,0 +1,64 @@
+<?xml version="1.0"?>
+<!--
+ 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.
+-->
+
+<document>
+
+ <properties>
+ <title>Fileupload Overview</title>
+ <author email="rdonkin@apache.org">Robert Burrell Donkin</author>
+ </properties>
+
+<body>
+
+ <section name="Using FileUpload">
+ <p>
+ Your application should detect whether or not FileUpload should be
+ invoked, based on the HTTP method and the content type of the request.
+ </p>
+ <p>
+ Assuming that you have decided that FileUpload should be invoked, you
+ might write the following code to handle a file upload request:
+<pre>
+ // Create a new file upload handler
+ DiskFileUpload upload = new DiskFileUpload();
+
+ // Set upload parameters
+ upload.setSizeMax(MAX_UPLOAD_SIZE);
+ upload.setSizeThreshold(MAX_MEMORY_SIZE);
+ upload.setRepositoryPath(TEMP_DIR);
+
+ // Parse the request
+ List items = upload.parseRequest(request);
+
+ // Process the uploaded fields
+ Iterator iter = items.iterator();
+ while (iter.hasNext()) {
+ FileItem item = (FileItem) iter.next();
+
+ if (item.isFormField()) {
+ processTextParameter(request, item);
+ } else {
+ processFileParameter(request, item);
+ }
+ }
+</pre>
+ </p>
+ </section>
+
+</body>
+</document>
Propchange: commons/sandbox/commons-fileupload2/xdocs/overview.xml
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: commons/sandbox/commons-fileupload2/xdocs/streaming.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/commons-fileupload2/xdocs/streaming.xml?rev=951978&view=auto
==============================================================================
--- commons/sandbox/commons-fileupload2/xdocs/streaming.xml (added)
+++ commons/sandbox/commons-fileupload2/xdocs/streaming.xml Sun Jun 6 21:19:54 2010
@@ -0,0 +1,88 @@
+<?xml version="1.0"?>
+<!--
+ 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.
+-->
+
+<document>
+
+ <properties>
+ <title>The Streaming API</title>
+ </properties>
+
+<body>
+
+ <section name="Why Streaming?">
+ <p>
+ The traditional API, which is described in the <a href="using.html">User
+ Guide</a>, assumes, that file items must be stored somewhere, before
+ they are actually accessable by the user. This approach is convenient,
+ because it allows easy access to an items contents. On the other hand,
+ it is memory and time consuming.
+ </p>
+ <p>
+ The streaming API allows you to trade a little bit of convenience for
+ optimal performance and and a low memory profile. Additionally, the
+ API is more lightweight, thus easier to understand.
+ </p>
+ </section>
+
+ <section name="How it works">
+ <p>
+ Again, the <code>FileUpload</code> class is used for accessing the
+ form fields and fields in the order, in which they have been sent
+ by the client. However, the <code>FileItemFactory</code> is completely
+ ignored.
+ </p>
+ </section>
+
+ <section name="Parsing the request">
+ <p>
+ First of all, do not forget to ensure, that a request actually is a
+ a file upload request. This is typically done using the same static
+ method, which you already know from the traditional API.
+ </p>
+<source><![CDATA[// Check that we have a file upload request
+boolean isMultipart = ServletFileUpload.isMultipartContent(request);]]></source>
+ <p>
+ Now we are ready to parse the request into its constituent items. Here's
+ how we do it:
+ </p>
+<source><![CDATA[
+// Create a new file upload handler
+ServletFileUpload upload = new ServletFileUpload();
+
+// Parse the request
+FileItemIterator iter = upload.getItemIterator(request);
+while (iter.hasNext()) {
+ FileItemStream item = iter.next();
+ String name = item.getFieldName();
+ InputStream stream = item.openStream();
+ if (item.isFormField()) {
+ System.out.println("Form field " + name + " with value "
+ + Streams.asString(stream) + " detected.");
+ } else {
+ System.out.println("File field " + name + " with file name "
+ + item.getName() + " detected.");
+ // Process the input stream
+ ...
+ }
+}]]></source>
+ <p>
+ That's all that's needed. Really!
+ </p>
+ </section>
+</body>
+</document>
Propchange: commons/sandbox/commons-fileupload2/xdocs/streaming.xml
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: commons/sandbox/commons-fileupload2/xdocs/style/project.css
URL: http://svn.apache.org/viewvc/commons/sandbox/commons-fileupload2/xdocs/style/project.css?rev=951978&view=auto
==============================================================================
--- commons/sandbox/commons-fileupload2/xdocs/style/project.css (added)
+++ commons/sandbox/commons-fileupload2/xdocs/style/project.css Sun Jun 6 21:19:54 2010
@@ -0,0 +1 @@
+@import url("http://commons.apache.org/style/commons-maven.css");
Added: commons/sandbox/commons-fileupload2/xdocs/tasks.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/commons-fileupload2/xdocs/tasks.xml?rev=951978&view=auto
==============================================================================
--- commons/sandbox/commons-fileupload2/xdocs/tasks.xml (added)
+++ commons/sandbox/commons-fileupload2/xdocs/tasks.xml Sun Jun 6 21:19:54 2010
@@ -0,0 +1,137 @@
+<?xml version="1.0"?>
+<!--
+ 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.
+-->
+
+<document>
+ <properties>
+ <title>TODO</title>
+ <author email="rdonkin@apache.org">Robert Burrell Donkin</author>
+ </properties>
+
+ <body>
+ <section name="TODO list">
+ <p>
+ The following is a list of items that need to be completed in
+ Fileupload. Contributions are welcome!
+ </p>
+
+ <subsection name="High priority">
+ </subsection>
+
+ <subsection name="Medium priority">
+ <ul>
+ <li>
+ <strong>Additional unit tests</strong> to increase code coverage.
+ </li>
+ <li>
+ <strong>Documentation</strong> for the customization capabilities.
+ </li>
+ </ul>
+ </subsection>
+
+ <subsection name="Low priority">
+ </subsection>
+
+ </section>
+
+ <section name='Completed'>
+ <subsection name="Since 1.0 Beta 1 Release">
+ <ul>
+ <li>
+ Split the <code>FileUpload</code> class into an abstract base class
+ and two concrete classes, one of which is specific to a disk-based
+ repository and the other a more generic implementation.
+ </li>
+ <li>
+ Replaced the ad hoc <code>newInstance()</code> means of creating
+ <code>FileItem</code> instances with a factory-based scheme for
+ much greater flexibility and simpler customization. This change
+ also eliminates a dependency on Commons BeanUtils.
+ </li>
+ <li>
+ Change the semantics of the size threshold to apply to the size of
+ individual items, instead of the size of the overall request. This
+ is in line with the original documentation, and better meets user
+ expectations.
+ </li>
+ <li>
+ Added unit tests for exceptional conditions, and to test new
+ functionality.
+ </li>
+ </ul>
+ </subsection>
+ </section>
+
+ <section name="Deprecated">
+ <subsection name="Since 1.0 Beta 1 Release">
+ <ul>
+ <li>
+ In the <code>FileItem</code> interface, the <code>setIsFormField()</code>
+ method has been replaced by the <code>setFormField()</code> method.
+ </li>
+ <li>
+ In the <code>FileItem</code> interface, the <code>write(String)</code>
+ method has been replaced by the <code>write(File)</code> method.
+ </li>
+ <li>
+ The <code>sizeThreshold</code> property of the <code>FileUpload</code>
+ class has been moved to the <code>DiskFileUpload</code> class.
+ </li>
+ <li>
+ The <code>repositoryPath</code> property of the <code>FileUpload</code>
+ class has been moved to the <code>DiskFileUpload</code> class.
+ </li>
+ <li>
+ The disk-specific <code>parseRequest()</code> method of the
+ <code>FileUpload</code> class has been moved to the
+ <code>DiskFileUpload</code> class.
+ </li>
+ </ul>
+ </subsection>
+ </section>
+
+ <section name="Backwards Incompatible Changes">
+ <subsection name="Since 1.0 Beta 1">
+ <ul>
+ <li>
+ <code>FileItem.newInstance()</code> has been replaced by the use of
+ factories to create new <code>FileItem</code> instances.
+ </li>
+ <li>
+ The <code>storeLocation</code> property of the <code>FileItem</code>
+ interface has been removed, since it is (disk-based) implementation
+ specific.
+ </li>
+ </ul>
+ </subsection>
+ </section>
+
+ <section name="Semantic Changes">
+ <subsection name="Since 1.0 Beta 1">
+ <ul>
+ <li>
+ The <code>sizeThreshold</code> property now applies to the size of
+ each item, rather than the size of the request as a whole. This is
+ more in keeping which user expectations, as well as matching the
+ original documentation.
+ </li>
+ </ul>
+ </subsection>
+ </section>
+ </body>
+</document>
+
Propchange: commons/sandbox/commons-fileupload2/xdocs/tasks.xml
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: commons/sandbox/commons-fileupload2/xdocs/using.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/commons-fileupload2/xdocs/using.xml?rev=951978&view=auto
==============================================================================
--- commons/sandbox/commons-fileupload2/xdocs/using.xml (added)
+++ commons/sandbox/commons-fileupload2/xdocs/using.xml Sun Jun 6 21:19:54 2010
@@ -0,0 +1,444 @@
+<?xml version="1.0"?>
+<!--
+ 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.
+-->
+
+<document>
+
+ <properties>
+ <title>Using FileUpload</title>
+ <author email="martinc@apache.org">Martin Cooper</author>
+ </properties>
+
+<body>
+
+ <section name="Using FileUpload">
+ <p>
+ FileUpload can be used in a number of different ways, depending upon the
+ requirements of your application. In the simplest case, you will call a
+ single method to parse the servlet request, and then process the list of
+ items as they apply to your application. At the other end of the scale,
+ you might decide to customize FileUpload to take full control of the way
+ in which individual items are stored; for example, you might decide to
+ stream the content into a database.
+ </p>
+ <p>
+ Here, we will describe the basic principles of FileUpload, and illustrate
+ some of the simpler - and most common - usage patterns. Customization of
+ FileUpload is described <a href="customizing.html">elsewhere</a>.
+ </p>
+ <p>
+ FileUpload depends on Commons IO, so make sure you have the version
+ mentioned on the <a href="dependencies.html">dependencies page</a> in
+ your classpath before continuing.
+ </p>
+ </section>
+
+ <section name="How it works">
+ <p>
+ A file upload request comprises an ordered list of <em>items</em> that
+ are encoded according to
+ <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>,
+ "Form-based File Upload in HTML". FileUpload can parse such a request
+ and provide your application with a list of the individual uploaded
+ items. Each such item implements the <code>FileItem</code> interface,
+ regardless of its underlying implementation.
+ </p>
+ <p>
+ This page describes the traditional API of the commons fileupload
+ library. The traditional API is a convenient approach. However, for
+ ultimate performance, you might prefer the faster
+ <a href="streaming.html">Streaming API</a>.
+ </p>
+ <p>
+ Each file item has a number of properties that might be of interest for
+ your application. For example, every item has a name and a content type,
+ and can provide an <code>InputStream</code> to access its data. On the
+ other hand, you may need to process items differently, depending upon
+ whether the item is a regular form field - that is, the data came from
+ an ordinary text box or similar HTML field - or an uploaded file. The
+ <code>FileItem</code> interface provides the methods to make such a
+ determination, and to access the data in the most appropriate manner.
+ </p>
+ <p>
+ FileUpload creates new file items using a <code>FileItemFactory</code>.
+ This is what gives FileUpload most of its flexibility. The factory has
+ ultimate control over how each item is created. The factory implementation
+ that currently ships with FileUpload stores the item's data in memory or
+ on disk, depending on the size of the item (i.e. bytes of data). However,
+ this behavior can be customized to suit your application.
+ </p>
+ </section>
+
+ <section name="Servlets and Portlets">
+ <p>
+ Starting with version 1.1, FileUpload supports file upload requests in
+ both servlet and portlet environments. The usage is almost identical in
+ the two environments, so the remainder of this document refers only to
+ the servlet environment.
+ </p>
+ <p>
+ If you are building a portlet application, the following are the two
+ distinctions you should make as you read this document:
+ <ul>
+ <li>
+ Where you see references to the <code>ServletFileUpload</code> class,
+ substitute the <code>PortletFileUpload</code> class.
+ </li>
+ <li>
+ Where you see references to the <code>HttpServletRequest</code> class,
+ substitute the <code>ActionRequest</code> class.
+ </li>
+ </ul>
+ </p>
+ </section>
+
+ <section name="Parsing the request">
+ <p>
+ Before you can work with the uploaded items, of course, you need to parse
+ the request itself. Ensuring that the request is actually a file upload
+ request is straightforward, but FileUpload makes it simplicity itself, by
+ providing a static method to do just that.
+ </p>
+<source><![CDATA[// Check that we have a file upload request
+boolean isMultipart = ServletFileUpload.isMultipartContent(request);]]></source>
+ <p>
+ Now we are ready to parse the request into its constituent items.
+ </p>
+ <subsection name="The simplest case">
+ <p>
+ The simplest usage scenario is the following:
+ <ul>
+ <li>
+ Uploaded items should be retained in memory as long as they are
+ reasonably small.
+ </li>
+ <li>
+ Larger items should be written to a temporary file on disk.
+ </li>
+ <li>
+ Very large upload requests should not be permitted.
+ </li>
+ <li>
+ The built-in defaults for the maximum size of an item to
+ be retained in memory, the maximum permitted size of an upload
+ request, and the location of temporary files are acceptable.
+ </li>
+ </ul>
+ </p>
+ <p>
+ Handling a request in this scenario couldn't be much simpler:
+ </p>
+<source><![CDATA[// Create a factory for disk-based file items
+FileItemFactory factory = new DiskFileItemFactory();
+
+// Create a new file upload handler
+ServletFileUpload upload = new ServletFileUpload(factory);
+
+// Parse the request
+List /* FileItem */ items = upload.parseRequest(request);]]></source>
+ <p>
+ That's all that's needed. Really!
+ </p>
+ <p>
+ The result of the parse is a <code>List</code> of file items, each of
+ which implements the <code>FileItem</code> interface. Processing these
+ items is discussed below.
+ </p>
+ </subsection>
+
+ <subsection name="Exercising more control">
+ <p>
+ If your usage scenario is close to the simplest case, described above,
+ but you need a little more control, you can easily customize the
+ behavior of the upload handler or the file item factory or both. The
+ following example shows several configuration options:
+ </p>
+<source><![CDATA[// Create a factory for disk-based file items
+DiskFileItemFactory factory = new DiskFileItemFactory();
+
+// Set factory constraints
+factory.setSizeThreshold(yourMaxMemorySize);
+factory.setRepository(yourTempDirectory);
+
+// Create a new file upload handler
+ServletFileUpload upload = new ServletFileUpload(factory);
+
+// Set overall request size constraint
+upload.setSizeMax(yourMaxRequestSize);
+
+// Parse the request
+List /* FileItem */ items = upload.parseRequest(request);]]></source>
+ <p>
+ Of course, each of the configuration methods is independent of the
+ others, but if you want to configure the factory all at once, you can
+ do that with an alternative constructor, like this:
+ </p>
+<source><![CDATA[// Create a factory for disk-based file items
+DiskFileItemFactory factory = new DiskFileItemFactory(
+ yourMaxMemorySize, yourTempDirectory);]]></source>
+ <p>
+ Should you need further control over the parsing of the request, such
+ as storing the items elsewhere - for example, in a database - you will
+ need to look into <a href="customizing.html">customizing</a> FileUpload.
+ </p>
+ </subsection>
+ </section>
+
+ <section name="Processing the uploaded items">
+ <p>
+ Once the parse has completed, you will have a <code>List</code> of file
+ items that you need to process. In most cases, you will want to handle
+ file uploads differently from regular form fields, so you might process
+ the list like this:
+ </p>
+<source><![CDATA[// Process the uploaded items
+Iterator iter = items.iterator();
+while (iter.hasNext()) {
+ FileItem item = (FileItem) iter.next();
+
+ if (item.isFormField()) {
+ processFormField(item);
+ } else {
+ processUploadedFile(item);
+ }
+}]]></source>
+ <p>
+ For a regular form field, you will most likely be interested only in the
+ name of the item, and its <code>String</code> value. As you might expect,
+ accessing these is very simple.
+ </p>
+<source><![CDATA[// Process a regular form field
+if (item.isFormField()) {
+ String name = item.getFieldName();
+ String value = item.getString();
+ ...
+}]]></source>
+ <p>
+ For a file upload, there are several different things you might want to
+ know before you process the content. Here is an example of some of the
+ methods you might be interested in.
+ </p>
+<source><![CDATA[// Process a file upload
+if (!item.isFormField()) {
+ String fieldName = item.getFieldName();
+ String fileName = item.getName();
+ String contentType = item.getContentType();
+ boolean isInMemory = item.isInMemory();
+ long sizeInBytes = item.getSize();
+ ...
+}]]></source>
+ <p>
+ With uploaded files, you generally will not want to access them via
+ memory, unless they are small, or unless you have no other alternative.
+ Rather, you will want to process the content as a stream, or write the
+ entire file to its ultimate location. FileUpload provides simple means of
+ accomplishing both of these.
+ </p>
+<source><![CDATA[// Process a file upload
+if (writeToFile) {
+ File uploadedFile = new File(...);
+ item.write(uploadedFile);
+} else {
+ InputStream uploadedStream = item.getInputStream();
+ ...
+ uploadedStream.close();
+}]]></source>
+ <p>
+ Note that, in the default implementation of FileUpload, <code>write()</code>
+ will attempt to rename the file to the specified destination, if the data
+ is already in a temporary file. Actually copying the data is only done if
+ the the rename fails, for some reason, or if the data was in memory.
+ </p>
+ <p>
+ If you do need to access the uploaded data in memory, you need simply
+ call the <code>get()</code> method to obtain the data as an array of
+ bytes.
+ </p>
+<source><![CDATA[// Process a file upload in memory
+byte[] data = item.get();
+...]]></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>:
+ </p>
+<source><![CDATA[
+<web-app>
+ ...
+ <listener>
+ <listener-class>
+ org.apache.commons.fileupload.servlet.FileCleanerCleanup
+ </listener-class>
+ </listener>
+ ...
+</web-app>
+]]></source>
+
+ <subsection name="Creating a DiskFileItemFactory">
+ <p>
+ The FileCleanerCleanup provides an instance of
+ <code>org.apache.commons.io.FileCleaningTracker</code>. This
+ instance must be used when creating a
+ <code>org.apache.commons.fileupload.disk.DiskFileItemFactory</code>.
+ This should be done by calling a method like the following:
+ </p>
+<source><![CDATA[
+ public static DiskFileItemFactory newDiskFileItemFactory(ServletContext context,
+ File repository) {
+ FileCleaningTracker fileCleaningTracker
+ = FileCleanerCleanup.getFileCleaningTracker(context);
+ DiskFileItemFactory factory
+ = new DiskFileItemFactory(DiskFileItemFactory.DEFAULT_SIZE_THRESHOLD,
+ repository);
+ factory.setFileCleaningTracker(fileCleaningTracker);
+ return factory;
+ }
+]]></source>
+ </subsection>
+
+ <subsection name="Disabling cleanup of temporary files">
+ <p>
+ To disable tracking of temporary files, you may set the
+ <code>FileCleaningTracker</code> to null. Consequently,
+ created files will no longer be tracked. In particular,
+ they will no longer be deleted automatically.</p>
+ </subsection>
+ </section>
+
+ <section name="Interaction with virus scanners">
+ <p>
+ Virus scanners running on the same system as the web container can cause
+ some unexpected behaviours for applications using FileUpload. This section
+ describes some of the behaviours that you might encounter, and provides
+ some ideas for how to handle them.
+ </p>
+ <p>
+ The default implementation of FileUpload will cause uploaded items above
+ a certain size threshold to be written to disk. As soon as such a file is
+ closed, any virus scanner on the system will wake up and inspect it, and
+ potentially quarantine the file - that is, move it to a special location
+ where it will not cause problems. This, of course, will be a surprise to
+ the application developer, since the uploaded file item will no longer be
+ available for processing. On the other hand, uploaded items below that
+ same threshold will be held in memory, and therefore will not be seen by
+ virus scanners. This allows for the possibility of a virus being retained
+ in some form (although if it is ever written to disk, the virus scanner
+ would locate and inspect it).
+ </p>
+ <p>
+ One commonly used solution is to set aside one directory on the system
+ into which all uploaded files will be placed, and to configure the virus
+ scanner to ignore that directory. This ensures that files will not be
+ ripped out from under the application, but then leaves responsibility for
+ virus scanning up to the application developer. Scanning the uploaded
+ files for viruses can then be performed by an external process, which
+ might move clean or cleaned files to an "approved" location, or by
+ integrating a virus scanner within the application itself. The details of
+ configuring an external process or integrating virus scanning into an
+ application are outside the scope of this document.
+ </p>
+ </section>
+
+ <section name="Watching progress">
+ <p>
+ If you expect really large file uploads, then it would be nice to report
+ to your users, how much is already received. Even HTML pages allow to
+ implement a progress bar by returning a multipart/replace response,
+ or something like that.
+ </p>
+ <p>
+ Watching the upload progress may be done by supplying a progress listener:
+ </p>
+<source><![CDATA[//Create a progress listener
+ProgressListener progressListener = new ProgressListener(){
+ public void update(long pBytesRead, long pContentLength, int pItems) {
+ System.out.println("We are currently reading item " + pItems);
+ if (pContentLength == -1) {
+ System.out.println("So far, " + pBytesRead + " bytes have been read.");
+ } else {
+ System.out.println("So far, " + pBytesRead + " of " + pContentLength
+ + " bytes have been read.");
+ }
+ }
+};
+upload.setProgressListener(progressListener);
+]]></source>
+ <p>
+ Do yourself a favour and implement your first progress listener just
+ like the above, because it shows you a pitfall: The progress listener
+ is called quite frequently. Depending on the servlet engine and other
+ environment factory, it may be called for any network packet! In
+ other words, your progress listener may become a performance problem!
+ A typical solution might be, to reduce the progress listeners activity.
+ For example, you might emit a message only, if the number of megabytes
+ has changed:
+ </p>
+<source><![CDATA[//Create a progress listener
+ProgressListener progressListener = new ProgressListener(){
+ private long megaBytes = -1;
+ public void update(long pBytesRead, long pContentLength, int pItems) {
+ long mBytes = pBytesRead / 1000000;
+ if (megaBytes == mBytes) {
+ return;
+ }
+ megaBytes = mBytes;
+ System.out.println("We are currently reading item " + pItems);
+ if (pContentLength == -1) {
+ System.out.println("So far, " + pBytesRead + " bytes have been read.");
+ } else {
+ System.out.println("So far, " + pBytesRead + " of " + pContentLength
+ + " bytes have been read.");
+ }
+ }
+};
+]]></source>
+ </section>
+
+ <section name="What's next">
+ <p>
+ Hopefully this page has provided you with a good idea of how to use
+ FileUpload in your own applications. For more detail on the methods
+ introduced here, as well as other available methods, you should refer
+ to the <a href="apidocs/index.html">JavaDocs</a>.
+ </p>
+ <p>
+ The usage described here should satisfy a large majority of file upload
+ needs. However, should you have more complex requirements, FileUpload
+ should still be able to help you, with it's flexible
+ <a href="customizing.html">customization</a> capabilities.
+ </p>
+ </section>
+
+</body>
+</document>
Propchange: commons/sandbox/commons-fileupload2/xdocs/using.xml
------------------------------------------------------------------------------
svn:mime-type = text/plain