xdocs/index.xml - turbine-fulcrum-upload - Git at Google

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