Using FileUpload 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. 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. FileUpload depends on Commons IO, so make sure you have the version mentioned on the in your classpath before continuing. FileUpload can parse such a request and provide your application with a list of the individual uploaded items. Each such item implements the FileItem interface, regardless of its underlying implementation. 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. 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 InputStream 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 FileItem interface provides the methods to make such a determination, and to access the data in the most appropriate manner. FileUpload creates new file items using a FileItemFactory. 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. However, this behavior can be customized to suit your application. Servlets and Portlets Starting with version 1. The usage is almost identical in the two environments, so the remainder of this document refers only to the servlet environment. The result of the parse is a List of file items, each of which implements the FileItem interface. Processing these items is discussed below. As you might expect, accessing these is very simple. } 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. } 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. Actually copying the data is only done if the the rename fails, for some reason, or if the data was in memory. If you do need to access the uploaded data in memory, you need simply call the get method to obtain the data as an array of bytes. Resource cleanup This section applies only, if you are using the. In other words, it applies, if your uploaded files are written to temporary files before processing them. Such temporary files are deleted automatically, if they are no longer used more precisely, if the corresponding instance of DiskFileItem is garbage collected. This is done silently by the org. FileCleanerTracker class, which starts a reaper thread. 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. To do so, add a section like the following to your web. This section describes some of the behaviours that you might encounter, and provides some ideas for how to handle them. 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. 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. The details of configuring an external process or integrating virus scanning into an application are outside the scope of this document. Watching progress If you expect really large file uploads, then it would be nice to report to your users, how much is already received. 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 more detail on the methods introduced here, as well as other available methods, you should refer to the. 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 capabilities.
