Author: martinc Date: Thu Dec 8 22:23:07 2005 New Revision: 355393 URL: http://svn.apache.org/viewcvs?rev=355393&view=rev Log: Update the User Guide to document the "right" way of using FileUpload 1.1, rather than the older, and thus deprecated, ways that are compatible with FileUpload 1.0.
Modified: jakarta/commons/proper/fileupload/trunk/xdocs/using.xml Modified: jakarta/commons/proper/fileupload/trunk/xdocs/using.xml URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/fileupload/trunk/xdocs/using.xml?rev=355393&r1=355392&r2=355393&view=diff ============================================================================== --- jakarta/commons/proper/fileupload/trunk/xdocs/using.xml (original) +++ jakarta/commons/proper/fileupload/trunk/xdocs/using.xml Thu Dec 8 22:23:07 2005 @@ -64,10 +64,33 @@ <p> FileUpload creates new file items using a <code>FileItemFactory</code>. This is what gives FileUpload most of its flexibility. The factory has - ultimate control over how each item is created. The default factory - stores the item's data in memory or on disk, depending on the size of - the item (i.e. bytes of data). However, this behavior can be customized - to suit your application. + ultimate control over how each item is created. The factory implementation + that currently ships with FileUpload stores the item's data in memory or + on disk, depending on the size of the item (i.e. bytes of data). However, + this behavior can be customized to suit your application. + </p> + </section> + + <section name="Servlets and Portlets"> + <p> + Starting with version 1.1, FileUpload supports file upload requests in + both servlet and portlet environments. The usage is almost identical in + the two environments, so the remainder of this document refers only to + the servlet environment. + </p> + <p> + If you are building a portlet application, the following are the two + distinctions you should make as you read this document: + <ul> + <li> + Where you see references to the <code>ServletFileUpload</code> class, + substitute the <code>PortletFileUpload</code> class. + </li> + <li> + Where you see references to the <code>HttpServletRequest</code> class, + substitute the <code>ActionRequest</code> class. + </li> + </ul> </p> </section> @@ -107,8 +130,11 @@ <p> Handling a request in this scenario couldn't be much simpler: </p> -<source><![CDATA[// Create a new file upload handler -DiskFileUpload upload = new DiskFileUpload(); +<source><![CDATA[// Create a factory for disk-based file items +FileItemFactory factory = new DiskFileItemFactory(); + +// Create a new file upload handler +ServletFileUpload upload = new ServletFileUpload(factory); // Parse the request List /* FileItem */ items = upload.parseRequest(request);]]></source> @@ -122,34 +148,36 @@ </p> </subsection> - <subsection name="Exercising more control"> + <subsection name="Exercising more control"> <p> If your usage scenario is close to the simplest case, described above, - but you need a little more control over the size thresholds or the - location of temporary files, you can customize the behavior using the - methods of the <code>DiskFileUpload</code> class, like this: + but you need a little more control, you can easily customize the + behavior of the upload handler or the file item factory or both. The + following example shows several configuration options: </p> -<source><![CDATA[// Create a new file upload handler -DiskFileUpload upload = new DiskFileUpload(); +<source><![CDATA[// Create a factory for disk-based file items +DiskFileItemFactory factory = new DiskFileItemFactory(); + +// Set factory constraints +factory.setSizeThreshold(yourMaxMemorySize); +factory.setRepositoryPath(yourTempDirectory); + +// Create a new file upload handler +ServletFileUpload upload = new ServletFileUpload(factory); -// Set upload parameters -upload.setSizeThreshold(yourMaxMemorySize); +// Set overall request size constraint upload.setSizeMax(yourMaxRequestSize); -upload.setRepositoryPath(yourTempDirectory); // Parse the request List /* FileItem */ items = upload.parseRequest(request);]]></source> <p> Of course, each of the configuration methods is independent of the - others, but if you want to configure them all at once, you can do that - with an alternate <code>parseRequest()</code> method, like this: + others, but if you want to configure the factory all at once, you can + do that with an alternative constructor, like this: </p> -<source><![CDATA[// Create a new file upload handler -DiskFileUpload upload = new DiskFileUpload(); - -// Parse the request -List /* FileItem */ items = upload.parseRequest(request, - yourMaxMemorySize, yourMaxRequestSize, yourTempDirectory);]]></source> +<source><![CDATA[// Create a factory for disk-based file items +DiskFileItemFactory factory = new DiskFileItemFactory( + yourMaxMemorySize, yourTempDirectory);]]></source> <p> Should you need further control over the parsing of the request, such as storing the items elsewhere - for example, in a database - you will --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]