martinc 2004/10/31 11:54:10 Modified: fileupload/src/java/org/apache/commons/fileupload package.html Added: fileupload/src/java/org/apache/commons/fileupload/disk package.html fileupload/src/java/org/apache/commons/fileupload/portlet package.html fileupload/src/java/org/apache/commons/fileupload/servlet package.html Log: Fix up the existing package.html file and add new ones for the newly introduced packages. Fairly minimal, but with a link to the user guide. Revision Changes Path 1.6 +54 -46 jakarta-commons/fileupload/src/java/org/apache/commons/fileupload/package.html Index: package.html =================================================================== RCS file: /home/cvs/jakarta-commons/fileupload/src/java/org/apache/commons/fileupload/package.html,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- package.html 25 Feb 2004 21:07:12 -0000 1.5 +++ package.html 31 Oct 2004 19:54:10 -0000 1.6 @@ -15,42 +15,46 @@ --> <!-- $Id$ --> <html> - <head> - <title>Overview of the org.apache.commons.fileupload component</title> - </head> - <body> - <p> - Component for handling html file uploads as given by rfc 1867 - <a href="http://www.ietf.org/rfc/rfc1867.txt">RFC 1867</a>. - </p> - <p> - Normal usage of the package involves - [EMAIL PROTECTED] org.apache.commons.fileupload.DiskFileUpload DiskFileUpload} - parsing the HttpServletRequest and returning a list of - [EMAIL PROTECTED] org.apache.commons.fileupload.FileItem FileItem}'s. - These <code>FileItem</code>'s provide easy access to the data - given in the upload. There is also a low level api for - manipulating the upload data encapsulated in the - [EMAIL PROTECTED] org.apache.commons.fileupload.MultipartStream MultipartStream} - class. - </p> - - <p> - Normal usage example: - </p> + <head> + <title>Overview of the org.apache.commons.fileupload component</title> + </head> + <body> + <p> + A component for handling HTML file uploads as specified by + <a href="http://www.ietf.org/rfc/rfc1867.txt" target="_top">RFC 1867</a>. + This component provides support for uploads within both servlets (JSR 53) + and portlets (JSR 168). + </p> + <p> + While this package provides the generic functionality for file uploads, + these classes are not typically used directly. Instead, normal usage + involves one of the provided extensions of + [EMAIL PROTECTED] org.apache.commons.fileupload.FileUpload FileUpload} such as + [EMAIL PROTECTED] org.apache.commons.fileupload.servlet.ServletFileUpload ServletFileUpload} + or + [EMAIL PROTECTED] org.apache.commons.fileupload.portlet.PortletFileUpload PortletFileUpload}, + together with a factory for + [EMAIL PROTECTED] org.apache.commons.fileupload.FileItem FileItem} instances, + such as + [EMAIL PROTECTED] org.apache.commons.fileupload.disk.DiskFileItemFactory DiskFileItemFactory}. + </p> + <p> + The following is a brief example of typical usage in a servlet, storing + the uploaded files on disk. + </p> <pre> - - public void doPost(HttpServletRequest req, HttpServletResponse res) - { - DiskFileUpload fu = new DiskFileUpload(); - // maximum size before a FileUploadException will be thrown - fu.setSizeMax(1000000); + public void doPost(HttpServletRequest req, HttpServletResponse res) { + DiskFileItemFactory factory = new DiskFileItemFactory(); // maximum size that will be stored in memory - fu.setSizeThreshold(4096); + factory.setSizeThreshold(4096); // the location for saving data that is larger than getSizeThreshold() - fu.setRepositoryPath("/tmp"); + factory.setRepository(new File("/tmp")); + + ServletFileUpload upload = new ServletFileUpload(factory); + // maximum size before a FileUploadException will be thrown + upload.setSizeMax(1000000); - List fileItems = fu.parseRequest(req); + List fileItems = upload.parseRequest(req); // assume we know there are two files. The first file is a small // text file, the second is unknown and is written to a file on // the server @@ -65,17 +69,21 @@ fi.write(new File("/www/uploads/", fileName)); } </pre> - <p> - In the example above the first file is loaded into memory as a - <code>String</code>. Before calling the getString method, the data - may have been in memory or on disk depending on its size. The second - file we assume it will be large and therefore never explicitly load - it into memory, though if it is less than 4096 bytes it will be - in memory before it is written to its final location. When writing to - the final location, if the data is larger than the - threshold, an attempt is made to rename the temporary file to - the given location. If it cannot be renamed, it is streamed to the - new location. - </p> - </body> + <p> + In the example above, the first file is loaded into memory as a + <code>String</code>. Before calling the <code>getString</code> method, + the data may have been in memory or on disk depending on its size. The + second file we assume it will be large and therefore never explicitly + load it into memory, though if it is less than 4096 bytes it will be + in memory before it is written to its final location. When writing to + the final location, if the data is larger than the threshold, an attempt + is made to rename the temporary file to the given location. If it cannot + be renamed, it is streamed to the new location. + </p> + <p> + Please see the FileUpload + <a href="http://jakarta.apache.org/commons/fileupload/using.html" target="_top">User Guide</a> + for further details and examples of how to use this package. + </p> + </body> </html> 1.1 jakarta-commons/fileupload/src/java/org/apache/commons/fileupload/disk/package.html Index: package.html =================================================================== <!-- Copyright 2002-2004 The Apache Software Foundation Licensed 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. --> <!-- $Id: package.html,v 1.1 2004/10/31 19:54:10 martinc Exp $ --> <html> <head> <title>Overview of the org.apache.commons.fileupload.disk component</title> </head> <body> <p> A disk-based implementation of the [EMAIL PROTECTED] org.apache.commons.fileupload.FileItem FileItem} interface. This implementation retains smaller items in memory, while writing larger ones to disk. The threshold between these two is configurable, as is the location of files that are written to disk. </p> <p> In typical usage, an instance of [EMAIL PROTECTED] org.apache.commons.fileupload.disk.DiskFileItemFactory DiskFileItemFactory} would be created, configured, and then passed to a [EMAIL PROTECTED] org.apache.commons.fileupload.FileUpload FileUpload} implementation such as [EMAIL PROTECTED] org.apache.commons.fileupload.servlet.ServletFileUpload ServletFileUpload} or [EMAIL PROTECTED] org.apache.commons.fileupload.portlet.PortletFileUpload PortletFileUpload}. </p> <p> The following code fragment demonstrates this usage. </p> <pre> DiskFileItemFactory factory = new DiskFileItemFactory(); // maximum size that will be stored in memory factory.setSizeThreshold(4096); // the location for saving data that is larger than getSizeThreshold() factory.setRepository(new File("/tmp")); ServletFileUpload upload = new ServletFileUpload(factory); </pre> <p> Please see the FileUpload <a href="http://jakarta.apache.org/commons/fileupload/using.html" target="_top">User Guide</a> for further details and examples of how to use this package. </p> </body> </html> 1.1 jakarta-commons/fileupload/src/java/org/apache/commons/fileupload/portlet/package.html Index: package.html =================================================================== <!-- Copyright 2002-2004 The Apache Software Foundation Licensed 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. --> <!-- $Id: package.html,v 1.1 2004/10/31 19:54:10 martinc Exp $ --> <html> <head> <title>Overview of the org.apache.commons.fileupload.portlet component</title> </head> <body> <p> An implementation of [EMAIL PROTECTED] org.apache.commons.fileupload.FileUpload FileUpload} for use in portlets conforming to JSR 168. This implementation requires only access to the portlet's current <code>ActionRequest</code> instance, and a suitable [EMAIL PROTECTED] org.apache.commons.fileupload.FileItemFactory FileItemFactory} implementation, such as [EMAIL PROTECTED] org.apache.commons.fileupload.disk.DiskFileItemFactory DiskFileItemFactory}. </p> <p> The following code fragment demonstrates typical usage. </p> <pre> DiskFileItemFactory factory = new DiskFileItemFactory(); // Configure the factory here, if desired. PortletFileUpload upload = new PortletFileUpload(factory); // Configure the uploader here, if desired. List fileItems = upload.parseRequest(request); </pre> <p> Please see the FileUpload <a href="http://jakarta.apache.org/commons/fileupload/using.html" target="_top">User Guide</a> for further details and examples of how to use this package. </p> </body> </html> 1.1 jakarta-commons/fileupload/src/java/org/apache/commons/fileupload/servlet/package.html Index: package.html =================================================================== <!-- Copyright 2002-2004 The Apache Software Foundation Licensed 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. --> <!-- $Id: package.html,v 1.1 2004/10/31 19:54:10 martinc Exp $ --> <html> <head> <title>Overview of the org.apache.commons.fileupload.servlet component</title> </head> <body> <p> An implementation of [EMAIL PROTECTED] org.apache.commons.fileupload.FileUpload FileUpload} for use in servlets conforming to JSR 53. This implementation requires only access to the servlet's current <code>HttpServletRequest</code> instance, and a suitable [EMAIL PROTECTED] org.apache.commons.fileupload.FileItemFactory FileItemFactory} implementation, such as [EMAIL PROTECTED] org.apache.commons.fileupload.disk.DiskFileItemFactory DiskFileItemFactory}. </p> <p> The following code fragment demonstrates typical usage. </p> <pre> DiskFileItemFactory factory = new DiskFileItemFactory(); // Configure the factory here, if desired. ServletFileUpload upload = new ServletFileUpload(factory); // Configure the uploader here, if desired. List fileItems = upload.parseRequest(request); </pre> <p> Please see the FileUpload <a href="http://jakarta.apache.org/commons/fileupload/using.html" target="_top">User Guide</a> for further details and examples of how to use this package. </p> </body> </html>
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]