<?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 xmlns="http://maven.apache.org/XDOC/2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

  <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.getInputStream();
    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>