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