~~   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.

    -----------------
    The Streaming API
    -----------------

The Streaming API

* Why Streaming?

  The traditional, and more comfortable API, which is described in the
  {{{using.html}User Guide}}, 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.

  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.

* How it works

  Again, the <<<FileUpload>>> class is used for accessing the
  form fields and fields in the order, in which they have been sent
  by the client. However, the <<<FileItemStore>>>, or its main
  implementation, the <<<DiskFileItemStore>>>, is completely
  ignored.

* Parsing the request

  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.

---------------------------------------------------------------------------
  // Check that we have a file upload request
  boolean isMultipart = HttpServletUploadRequest.isMultipartContent(request);
---------------------------------------------------------------------------

  Now we are ready to parse the request into its constituent items. Here's
  how we do it:

---------------------------------------------------------------------------
  // Create a new file upload handler
  FileUpload upload = new FileUpload();

  // Parse the request
  HttpServletRequest req;
  HttpServletUploadRequest request = new HttpServletUploadRequest(req);
  FileItemIterator iter = upload.parse(request);
  while (iter.hasNext()) {
    FileItem item = iter.next();
    String name = item.getFieldName();
    if (item.isFormField()) {
        System.out.println("Form field " + name + " with value "
            + Streams.asString(item) + " detected.");
    } else {
        System.out.println("File field " + name + " with file name "
            + item.getName() + " detected.");
        // Process the input stream
        InputStream istream = item.getInputStream();
        ...
    }
---------------------------------------------------------------------------

  That's all that's needed. Really!