xdocs/index.xml (118 lines of code) (raw):
<?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>
<properties>
<title>Upload Component</title>
<author email="epugh@opensourceconnections.com">Eric Pugh</author>
</properties>
<body>
<section name="Overview">
<p>
The Upload Service handles the parsing of multi-part/form-data from
POST Requests for Servlets and Portlets, making the multi-part files available
from either memory or from a specified location on the file system.
</p>
<p>
It is written for use in Turbine but it can be used in Avalon
compatible container.
</p>
</section>
<section name="Configuration">
<subsection name="Role Configuration">
<source><![CDATA[
<role
name="org.apache.fulcrum.upload.UploadService"
shorthand="upload"
default-class="org.apache.fulcrum.upload.DefaultUploadService"/>
]]></source>
</subsection>
<subsection name="Component Configuration">
<table>
<tr>
<th>Item</th>
<th>Datatype</th>
<th>Cardinality</th>
<th>Description</th>
</tr>
<tr>
<td>repository</td>
<td>String</td>
<td>[0|1]</td>
<td>
The directory where files will be temporarily stored (default is
".").
On Win32 file systems an entry of the form
<code>f:\path\to\upload\repository</code>
is most likely necessary.
</td>
</tr>
<tr>
<td>sizeMax</td>
<td>Integer</td>
<td>[0|1]</td>
<td>
The maximum size of a request that will be processed
(default is 1048576 bytes).
</td>
</tr>
<tr>
<td>sizeThreshold</td>
<td>Integer</td>
<td>[0|1]</td>
<td>
The maximum size of a request that will have it's elements cached in
memory (default is 10240 bytes).
</td>
</tr>
<tr>
<td>headerEncoding</td>
<td>String</td>
<td>[0|1]</td>
<td>
Used to specify how the headers are encoded (default is
"ISO-8859-1").
</td>
</tr>
</table>
</subsection>
<subsection name="Component Configuration Example">
<source><![CDATA[
<upload repository="target" sizeMax="1048576" sizeThreshold="10240" headerEncoding="UTF-8"/>
]]></source>
</subsection>
</section>
<section name="Usage">
<p>
Create an HTML form of the type:
</p>
<source test=""><![CDATA[
<form enctype="multipart/form-data" method="POST">
<input type="hidden" name="action" value="UploadExample" />
<input type="file" name="filename">
<input type="submit" value="upload" />
</form>
]]></source>
<p>
The Upload Service manages the storage of the FileItem in memory or at
the configured repository location in the file system. It is also possible to
override the repository location using the overloaded parseRequest()
methods.
</p>
<p>
Typically a request would be parsed using the Fulcrum ParameterParser
service, but you can achieve this manually thus:
</p>
<source test=""><![CDATA[
UploadService us = (UploadService) this.lookup(UploadService.ROLE);
List fileItems = us.parse(request);
]]></source>
<p>
FileItem provides many methods for working with the uploaded files that will
function whether a file is loaded into memory or as a temporary
file.
All the temporary storage management and clean up occurs behind the
scenes transparently to your application. FileItem objects do not span Requests,
finalizers remove any temporary files created along the way.
</p>
</section>
</body>
</document>