Author: seade
Date: Tue Jun 16 22:27:27 2009
New Revision: 785433
URL: http://svn.apache.org/viewvc?rev=785433&view=rev
Log:
A bunches of documentation fixes to fulcrum-upload, possibly not 100% accurate,
but certainly an improvement.
Modified:
turbine/fulcrum/trunk/upload/src/java/org/apache/fulcrum/upload/DefaultUploadService.java
turbine/fulcrum/trunk/upload/src/java/org/apache/fulcrum/upload/UploadService.java
turbine/fulcrum/trunk/upload/xdocs/index.xml
Modified:
turbine/fulcrum/trunk/upload/src/java/org/apache/fulcrum/upload/DefaultUploadService.java
URL:
http://svn.apache.org/viewvc/turbine/fulcrum/trunk/upload/src/java/org/apache/fulcrum/upload/DefaultUploadService.java?rev=785433&r1=785432&r2=785433&view=diff
==============================================================================
---
turbine/fulcrum/trunk/upload/src/java/org/apache/fulcrum/upload/DefaultUploadService.java
(original)
+++
turbine/fulcrum/trunk/upload/src/java/org/apache/fulcrum/upload/DefaultUploadService.java
Tue Jun 16 22:27:27 2009
@@ -44,15 +44,15 @@
* <p> Files will be stored in temporary disk storage on in memory,
* depending on request size, and will be available from the {...@link
* org.apache.fulcrum.util.parser.ParameterParser} as {...@link
- * org.apache.fulcrum.upload.FileItem}s.
+ * org.apache.commons.fileupload.FileItem} objects.
*
* <p>This implementation of {...@link UploadService} handles multiple
- * files per single html widget, sent using multipar/mixed encoding
+ * files per single html form, sent using multipart/form-data encoding
* type, as specified by RFC 1867. Use {...@link
- * org.apache.fulcrum.util.parser.ParameterParser#getFileItems(String)} to
+ * org.apache.fulcrum.parser.ParameterParser#getFileItems(String)} to
* acquire an array of {...@link
- * org.apache.fulcrum.upload.FileItem}s associated with given
- * html widget.
+ * org.apache.commons.fileupload.FileItem} onjects associated with given
+ * html form.
*
* @author <a href="mailto:[email protected]";>Rafal Krzewski</a>
* @author <a href="mailto:[email protected]";>Daniel Rall</a>
Modified:
turbine/fulcrum/trunk/upload/src/java/org/apache/fulcrum/upload/UploadService.java
URL:
http://svn.apache.org/viewvc/turbine/fulcrum/trunk/upload/src/java/org/apache/fulcrum/upload/UploadService.java?rev=785433&r1=785432&r2=785433&view=diff
==============================================================================
---
turbine/fulcrum/trunk/upload/src/java/org/apache/fulcrum/upload/UploadService.java
(original)
+++
turbine/fulcrum/trunk/upload/src/java/org/apache/fulcrum/upload/UploadService.java
Tue Jun 16 22:27:27 2009
@@ -29,9 +29,9 @@
/**
* <p> This service handles parsing <code>multipart/form-data</code>
- * POST requests and turing them into form fields and uploaded files.
+ * POST requests and turning them into form fields and uploaded files.
* This can be either performed automatically by the {...@link
- * org.apache.fulcrum.util.parser.ParameterParser} or manually by an user
+ * org.apache.fulcrum.parser.ParameterParser} or manually by an user
* definded {...@link org.apache.turbine.modules.Action}.
*
* @author <a href="mailto:[email protected]";>Rafal Krzewski</a>
@@ -94,7 +94,7 @@
/**
* <p> The default value of 'repository' property (.). This is
- * the directory where uploaded fiels will get stored temporarily.
+ * the directory where uploaded files will get stored temporarily.
* Note that "." is whatever the servlet container chooses to be
* it's 'current directory'.
*/
Modified: turbine/fulcrum/trunk/upload/xdocs/index.xml
URL:
http://svn.apache.org/viewvc/turbine/fulcrum/trunk/upload/xdocs/index.xml?rev=785433&r1=785432&r2=785433&view=diff
==============================================================================
--- turbine/fulcrum/trunk/upload/xdocs/index.xml (original)
+++ turbine/fulcrum/trunk/upload/xdocs/index.xml Tue Jun 16 22:27:27 2009
@@ -49,7 +49,7 @@
<![CDATA[
<role
name="org.apache.fulcrum.upload.UploadService"
- shorthand="cache"
+ shorthand="upload"
default-class="org.apache.fulcrum.upload.DefaultUploadService"/>
]]>
</source>
@@ -60,39 +60,27 @@
<source>
<![CDATA[
- <upload repository="target" sizeMax="1048576" sizeThreshold="10240"/>
+ <upload repository="target" sizeMax="1048576" sizeThreshold="10240"
headerEncoding="UTF-8"/>
]]>
</source>
- <p>
-sizeMax is the maximum size of a request that will be processed.
+<p>
+repository is 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.
</p>
- <p>
-sizeThreshold is the maximum size of a request that will have it's elements
cached in
+<p>
+sizeMax is the maximum size of a request that will be processed (default is
1048576 bytes).
</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.
+sizeThreshold is the maximum size of a request that will have it's elements
cached in memory (default is 10240 bytes).
</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.
+headerEncoding is used to specify how the headers are encoded (default is
"ISO-8859-1").
</p>
+ </section>
+
+ <section name="Usage">
<p>
Create an HTML form of the type:
@@ -109,50 +97,28 @@
]]></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:
+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[
- 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.
-
- }
-
+ UploadService us = (UploadService) this.lookup(UploadService.ROLE);
+ List fileItems = us.parse(request);
]]></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().
+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>
-<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>
