src/site/fml/faq.fml - commons-fileupload - Git at Google

 <?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

       https://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.
 -->

 <faqs title="FileUpload FAQ">

   <part id="general">
     <title>General</title>

     <faq id="empty-parse">
       <question>
         Why is parseRequest() returning no items?
       </question>
       <answer>
         This most commonly happens when the request has already been parsed, or
         processed in some other way. Since the input stream has aleady been
         consumed by that earlier process, it is no longer available for parsing
         by Commons FileUpload.
       </answer>
     </faq>

     <faq id="read-timeout">
       <question>
         Why am I getting "Read timed out" exceptions while parsing?
       </question>
       <answer>
         The most common cause of these exceptions is when FileUpload is being
         used on a site that is using the Tomcat ISAPI redirector. There was a
         bug in earlier versions of that component that caused problems with
         multipart requests. The bug was fixed some time ago, so you probably
         just need to pick up a newer version. See the
         <a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=15278">Tomcat bug report</a>
         for full details.
       </answer>
     </faq>

     <faq id="class-not-found">
       <question>
         Why is NoClassDefFoundError being thrown?
       </question>
       <answer>
         <p>There are two common causes for this error. </p>

         <p>Firstly, it might simply mean that you do not have the Commons IO
         jar in your classpath. FileUpload depends on IO (see
         <a href="dependencies.html">dependencies</a>) - you can tell if
         this is the case if the missing class is within the
         <code>org.apache.commons.io</code> package. </p>

         <p>Secondly this happens when attempting to rely on a shared copy of
         the Commons FileUpload jar file provided by your web container. The
         solution is to include the FileUpload jar file as part of your own
         web application, instead of relying on the container. The same may
         hold for FileUpload's IO dependency. </p>
       </answer>
     </faq>

     <faq id="whole-path-from-IE">
       <question>
         Why does FileItem.getName() return the whole path, and not just the file name?
       </question>
       <answer>
         Internet Explorer provides the entire path to the uploaded file and not
         just the base file name. Since FileUpload provides exactly what was
         supplied by the client (browser), you may want to remove this path
         information in your application. You can do that using the following
         method from Commons IO (which you already have, since it is used by
         FileUpload).
         <pre>
     String fileName = item.getName();
     if (fileName != null) {
         filename = FilenameUtils.getName(filename);
     }
         </pre>
       </answer>
     </faq>
   </part>

   <part id="struts">
     <title>FileUpload and Struts 1</title>

     <faq id="parse-in-action-fails">
       <question>
         I'm using FileUpload in an Action, but it's not working. Why?
       </question>
       <answer>
         Struts 1 recognises multipart requests, and parses them automatically,
         presenting the request parameters to your code in the same manner as
         if they were regular request parameters. Since Struts has already
         processed the request, and made it available in your form bean, the
         input stream is no longer available for parsing, so attempting to do
         so with FileUpload will fail.
       </answer>
     </faq>

     <faq id="howto-parse-in-action">
       <question>
         But I need to parse the request myself. How can I do that?
       </question>
       <answer>
         Struts 1 parses multipart a request as a part of the process of populating
         your form bean from that request. If, for some reason, you need to have
         full control over the multipart parsing, you can do so by configuring
         your action mapping without an associated form bean. (A better way of
         doing this, however, is to replace the default multipart handler with
         your own. See the Struts 1 documentation for details.)
       </answer>
     </faq>
   </part>

   <part id="flash">
     <title>FileUpload and Flash</title>

     <faq id="missing-boundary-terminator">
       <question>
         I'm using FileUpload to receive an upload from flash, but
         FileUpload will always throw an Exception "Stream ended unexpectedly".
         What can I do?
       </question>
       <answer>
         <p>
           At least as of version 8, Flash contains a known bug: The multipart
           stream it produces is broken, because the final boundary doesn't
           contain the suffix "--", which ought to indicate, that no more
           items are following. Consequently, FileUpload waits for the next
           item (which it doesn't get) and throws an exception.
         </p>
         <p>
           The problems details and a possible workaround are outlined in
           <a href="https://issues.apache.org/jira/browse/FILEUPLOAD-143">
             Bug 143
           </a>
           . The workaround suggests to use the streaming API
           and catch the exception. The resulting code could look like
           this:
         </p>
         <pre><![CDATA[final List<FileItem> items = new ArrayList<FileItem>();

 HttpServletRequest servletRequest = [...];
 RequestContext ctx = new ServletRequestContext(servletRequest);

 FileItemFactory fileItemFactory = new DiskFileItemFactory();

 ServletFileUpload upload = new ServletFileUpload();
 FileItemIterator iter = upload.getItemIterator(ctx);
 try {
     while (iter.hasNext()) {
         FileItemStream item = iter.next();
         FileItem fileItem = fileItemFactory.createItem(item.getFieldName(),
                                                        item.getContentType(),
                                                        item.isFormField(),
                                                        item.getName());
         Streams.copy(item.openStream(), fileItem.getOutputStream(), true);
         items.add(fileItem);
     }
 } catch (MalformedStreamException e) {
     // Ignore this
 }]]></pre>
       </answer>
     </faq>
   </part>

   <part id="security">
       <title>FileUpload and Flash</title>

       <faq id="diskfileitem-serializable">
         <question> I have read, that there is a security problem in Commons FileUpload, because there is a class called
           DiskFileItem, which can be used for malicious attacks.
         </question>
         <answer>
           <p>
           	Starting in version 2.0.0-M1, no FileUpload classes implement Serializable.
           </p>
           <p>
             It is true, that this class exists, and can be serialized/deserialized in FileUpload versions, up to, and
             including 1.3.2. It is also true, that a malicious attacker can abuse this possibility to create arbitrarily
             located files (assuming the required permissions) with arbitrary contents, if he gets the opportunity to
             provide specially crafted data, which is being deserialized by a Java application, which has either of the
             above versions of Commons FileUpload in the classpath, and which puts no limitations on the classes being
             deserialized.
           </p>
           <p>
             That being said, we (the Apache Commons team) hold the view, that the actual problem is not the DiskFileItem
             class, but the "if" in the previous sentence. A Java application should carefully consider, which classes
             can be deserialized. A typical approach would be, for example, to provide a blacklist, or whitelist of
             packages, and/or classes, which may, or may not be deserialized.
           </p>
           <p>
             On the other hand, we acknowledge, that the likelyhood of application container vendors taking such a
             simple security measure is extremely low. So, in order to support the Commons FileUpload users, we have
             decided to choose a different approach:
           </p>
           <p>
             Beginning with 1.3.3, the class DiskFileItem is still implementing the interface java.io.Serializable.
             In other words, it still declares itself as serializable, and deserializable to the JVM. In practice,
             however, an attempt to deserialize an instance of DiskFileItem will trigger an Exception. In the unlikely
             case, that your application depends on the deserialization of DiskFileItems, you can revert to the
             previous behavior by setting the system property "org.apache.commons.fileupload.DiskFileItem.serializable"
             to "true".
           </p>
         </answer>
       </faq>
   </part>
 </faqs>
	<?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

	https://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.
	-->

	<faqs title="FileUpload FAQ">

	<part id="general">
	<title>General</title>

	<faq id="empty-parse">
	<question>
	Why is parseRequest() returning no items?
	</question>
	<answer>
	This most commonly happens when the request has already been parsed, or
	processed in some other way. Since the input stream has aleady been
	consumed by that earlier process, it is no longer available for parsing
	by Commons FileUpload.
	</answer>
	</faq>

	<faq id="read-timeout">
	<question>
	Why am I getting "Read timed out" exceptions while parsing?
	</question>
	<answer>
	The most common cause of these exceptions is when FileUpload is being
	used on a site that is using the Tomcat ISAPI redirector. There was a
	bug in earlier versions of that component that caused problems with
	multipart requests. The bug was fixed some time ago, so you probably
	just need to pick up a newer version. See the
	<a href="https://issues.apache.org/bugzilla/show_bug.cgi?id=15278">Tomcat bug report</a>
	for full details.
	</answer>
	</faq>

	<faq id="class-not-found">
	<question>
	Why is NoClassDefFoundError being thrown?
	</question>
	<answer>
	<p>There are two common causes for this error. </p>

	<p>Firstly, it might simply mean that you do not have the Commons IO
	jar in your classpath. FileUpload depends on IO (see
	<a href="dependencies.html">dependencies</a>) - you can tell if
	this is the case if the missing class is within the
	<code>org.apache.commons.io</code> package. </p>

	<p>Secondly this happens when attempting to rely on a shared copy of
	the Commons FileUpload jar file provided by your web container. The
	solution is to include the FileUpload jar file as part of your own
	web application, instead of relying on the container. The same may
	hold for FileUpload's IO dependency. </p>
	</answer>
	</faq>

	<faq id="whole-path-from-IE">
	<question>
	Why does FileItem.getName() return the whole path, and not just the file name?
	</question>
	<answer>
	Internet Explorer provides the entire path to the uploaded file and not
	just the base file name. Since FileUpload provides exactly what was
	supplied by the client (browser), you may want to remove this path
	information in your application. You can do that using the following
	method from Commons IO (which you already have, since it is used by
	FileUpload).
	<pre>
	String fileName = item.getName();
	if (fileName != null) {
	filename = FilenameUtils.getName(filename);
	}
	</pre>
	</answer>
	</faq>
	</part>

	<part id="struts">
	<title>FileUpload and Struts 1</title>

	<faq id="parse-in-action-fails">
	<question>
	I'm using FileUpload in an Action, but it's not working. Why?
	</question>
	<answer>
	Struts 1 recognises multipart requests, and parses them automatically,
	presenting the request parameters to your code in the same manner as
	if they were regular request parameters. Since Struts has already
	processed the request, and made it available in your form bean, the
	input stream is no longer available for parsing, so attempting to do
	so with FileUpload will fail.
	</answer>
	</faq>

	<faq id="howto-parse-in-action">
	<question>
	But I need to parse the request myself. How can I do that?
	</question>
	<answer>
	Struts 1 parses multipart a request as a part of the process of populating
	your form bean from that request. If, for some reason, you need to have
	full control over the multipart parsing, you can do so by configuring
	your action mapping without an associated form bean. (A better way of
	doing this, however, is to replace the default multipart handler with
	your own. See the Struts 1 documentation for details.)
	</answer>
	</faq>
	</part>

	<part id="flash">
	<title>FileUpload and Flash</title>

	<faq id="missing-boundary-terminator">
	<question>
	I'm using FileUpload to receive an upload from flash, but
	FileUpload will always throw an Exception "Stream ended unexpectedly".
	What can I do?
	</question>
	<answer>
	<p>
	At least as of version 8, Flash contains a known bug: The multipart
	stream it produces is broken, because the final boundary doesn't
	contain the suffix "--", which ought to indicate, that no more
	items are following. Consequently, FileUpload waits for the next
	item (which it doesn't get) and throws an exception.
	</p>
	<p>
	The problems details and a possible workaround are outlined in
	<a href="https://issues.apache.org/jira/browse/FILEUPLOAD-143">
	Bug 143
	</a>
	. The workaround suggests to use the streaming API
	and catch the exception. The resulting code could look like
	this:
	</p>
	<pre><![CDATA[final List<FileItem> items = new ArrayList<FileItem>();

	HttpServletRequest servletRequest = [...];
	RequestContext ctx = new ServletRequestContext(servletRequest);

	FileItemFactory fileItemFactory = new DiskFileItemFactory();

	ServletFileUpload upload = new ServletFileUpload();
	FileItemIterator iter = upload.getItemIterator(ctx);
	try {
	while (iter.hasNext()) {
	FileItemStream item = iter.next();
	FileItem fileItem = fileItemFactory.createItem(item.getFieldName(),
	item.getContentType(),
	item.isFormField(),
	item.getName());
	Streams.copy(item.openStream(), fileItem.getOutputStream(), true);
	items.add(fileItem);
	}
	} catch (MalformedStreamException e) {
	// Ignore this
	}]]></pre>
	</answer>
	</faq>
	</part>

	<part id="security">
	<title>FileUpload and Flash</title>

	<faq id="diskfileitem-serializable">
	<question> I have read, that there is a security problem in Commons FileUpload, because there is a class called
	DiskFileItem, which can be used for malicious attacks.
	</question>
	<answer>
	<p>
	Starting in version 2.0.0-M1, no FileUpload classes implement Serializable.
	</p>
	<p>
	It is true, that this class exists, and can be serialized/deserialized in FileUpload versions, up to, and
	including 1.3.2. It is also true, that a malicious attacker can abuse this possibility to create arbitrarily
	located files (assuming the required permissions) with arbitrary contents, if he gets the opportunity to
	provide specially crafted data, which is being deserialized by a Java application, which has either of the
	above versions of Commons FileUpload in the classpath, and which puts no limitations on the classes being
	deserialized.
	</p>
	<p>
	That being said, we (the Apache Commons team) hold the view, that the actual problem is not the DiskFileItem
	class, but the "if" in the previous sentence. A Java application should carefully consider, which classes
	can be deserialized. A typical approach would be, for example, to provide a blacklist, or whitelist of
	packages, and/or classes, which may, or may not be deserialized.
	</p>
	<p>
	On the other hand, we acknowledge, that the likelyhood of application container vendors taking such a
	simple security measure is extremely low. So, in order to support the Commons FileUpload users, we have
	decided to choose a different approach:
	</p>
	<p>
	Beginning with 1.3.3, the class DiskFileItem is still implementing the interface java.io.Serializable.
	In other words, it still declares itself as serializable, and deserializable to the JVM. In practice,
	however, an attempt to deserialize an instance of DiskFileItem will trigger an Exception. In the unlikely
	case, that your application depends on the deserialization of DiskFileItems, you can revert to the
	previous behavior by setting the system property "org.apache.commons.fileupload.DiskFileItem.serializable"
	to "true".
	</p>
	</answer>
	</faq>
	</part>
	</faqs>