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, 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">

     <p>
       First, here is the role configuration.
     </p>

     <source>
     <![CDATA[
         <role
             name="org.apache.fulcrum.upload.UploadService"
             shorthand="cache"
             default-class="org.apache.fulcrum.upload.DefaultUploadService"/>
     ]]>
     </source>

       <p>
         And here is the configuration:
       </p>
     <source>

     <![CDATA[
         <upload repository="target" sizeMax="1048576" sizeThreshold="10240"/>
     ]]>
     </source>
     <p>
 sizeMax is the maximum size of a request that will be processed.
 </p>
     <p>
 sizeThreshold is the maximum size of a request that will have it's elements cached in
 </p>


   </section>

   <section name="Usage">


 <p>
 Any
 multi-part/form-data requests which Turbine fields, will be parsed and the
 appropriate files made available to ParameterParser as FileItem objects. If
 this is set as false, the FileItems will have to be parsed out of RunData
 manually with the method getRequest() available from TurbineUpload.
 </p>

 <p>
 Set the remaining values to ones approriate for your installation. On Win32
 file systems for the repository directive, an entry of the form:
 <ul>
   <code>f:\path\to\upload\repository</code>
 </ul>
 is most likely necessary.
 </p>


 <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 if the FileItem is stored in Memory or in the
 Repository specified in TurbineReources.properties. It is also possible to
 overide the TurbineResources setting for the repository by using
 UploadServiceFacade.getRequest()  to parse the request with a custom repository
 directory. The UploadServiceFacade object serves as a Facade to the Upload Service
 by making available static methods to manage the upload internally in your
 application. The FileItems can be accessed in an UploadExample Action class by:
 </p>

 <source test=""><![CDATA[
     public void doPerform(RunData data, Context context) throws Exception
     {
         //get the ParameterParser from RunData
         ParameterParser params = data.getParameters();

         //grab the FileItems available in ParameterParser
         FileItem fi = params.getFileItem("filename");

         //do work on the FileItem
         //get the file as a File
         //or outputstream etc.

     }

 ]]></source>

 <p>
 Once a new instance of the FileItem is created many public methods are
 available to work on the object, whether it is in temporary storage as memory or as
 a temporary file on part of the file system. All the temporary storage management and
 clean up occurs behind the scenes and is transparent to the application being
 based on Turbine. There is no need to manually clean up the FileItems as the
 FileItem object doesn't span Requests ( or RunData instances ) and the temporary
 files that use the file system are cleaned up in a finalize() method inherited
 from Object().
 </p>

 <p>
 The UploadServiceFacade object and the FileItem object give all the functionality
 needed to manage this sort of operation or action at the application level.
 For more detailed information on the methods available to deal with uploaded
 files, view the relevant Javadocs for UploadServiceFacade, ParameterParser and
 FileItem.
 </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, 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">

	<p>
	First, here is the role configuration.
	</p>

	<source>
	<![CDATA[
	<role
	name="org.apache.fulcrum.upload.UploadService"
	shorthand="cache"
	default-class="org.apache.fulcrum.upload.DefaultUploadService"/>
	]]>
	</source>

	<p>
	And here is the configuration:
	</p>
	<source>

	<![CDATA[
	<upload repository="target" sizeMax="1048576" sizeThreshold="10240"/>
	]]>
	</source>
	<p>
	sizeMax is the maximum size of a request that will be processed.
	</p>
	<p>
	sizeThreshold is the maximum size of a request that will have it's elements cached in
	</p>


	</section>

	<section name="Usage">


	<p>
	Any
	multi-part/form-data requests which Turbine fields, will be parsed and the
	appropriate files made available to ParameterParser as FileItem objects. If
	this is set as false, the FileItems will have to be parsed out of RunData
	manually with the method getRequest() available from TurbineUpload.
	</p>

	<p>
	Set the remaining values to ones approriate for your installation. On Win32
	file systems for the repository directive, an entry of the form:
	<ul>
	<code>f:\path\to\upload\repository</code>
	</ul>
	is most likely necessary.
	</p>


	<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 if the FileItem is stored in Memory or in the
	Repository specified in TurbineReources.properties. It is also possible to
	overide the TurbineResources setting for the repository by using
	UploadServiceFacade.getRequest() to parse the request with a custom repository
	directory. The UploadServiceFacade object serves as a Facade to the Upload Service
	by making available static methods to manage the upload internally in your
	application. The FileItems can be accessed in an UploadExample Action class by:
	</p>

	<source test=""><![CDATA[
	public void doPerform(RunData data, Context context) throws Exception
	{
	//get the ParameterParser from RunData
	ParameterParser params = data.getParameters();

	//grab the FileItems available in ParameterParser
	FileItem fi = params.getFileItem("filename");

	//do work on the FileItem
	//get the file as a File
	//or outputstream etc.

	}

	]]></source>

	<p>
	Once a new instance of the FileItem is created many public methods are
	available to work on the object, whether it is in temporary storage as memory or as
	a temporary file on part of the file system. All the temporary storage management and
	clean up occurs behind the scenes and is transparent to the application being
	based on Turbine. There is no need to manually clean up the FileItems as the
	FileItem object doesn't span Requests ( or RunData instances ) and the temporary
	files that use the file system are cleaned up in a finalize() method inherited
	from Object().
	</p>

	<p>
	The UploadServiceFacade object and the FileItem object give all the functionality
	needed to manage this sort of operation or action at the application level.
	For more detailed information on the methods available to deal with uploaded
	files, view the relevant Javadocs for UploadServiceFacade, ParameterParser and
	FileItem.
	</p>
	</section>

	</body>
	</document>