You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by ma...@apache.org on 2003/05/12 07:24:52 UTC
cvs commit: jakarta-commons/fileupload/src/java/org/apache/commons/fileupload DefaultFileItem.java FileItem.java
martinc 2003/05/11 22:24:52
Modified: fileupload/src/java/org/apache/commons/fileupload
DefaultFileItem.java FileItem.java
Log:
Document the fact that the FileItem.write() method is only guaranteed to
work once for each file item. This restriction is a compromise that allows
for significant performance gain in the case that an implementation uses a
disk file for temporary storage, and uses file renaming to implement the
write() method. The only cost of this restriction is that multiple calls
to write() for the same file item -- an unlikely requirement in any case
-- would fail. (Bug #19369, reported by Thierry De Leeuw)
Also document that the value returned by FileItem.getName() is dependent
on the browser, or other client, and may or may not include the full path
to the uploaded file, since RFC 1867 is silent on the issue.
Revision Changes Path
1.18 +19 -10 jakarta-commons/fileupload/src/java/org/apache/commons/fileupload/DefaultFileItem.java
Index: DefaultFileItem.java
===================================================================
RCS file: /home/cvs/jakarta-commons/fileupload/src/java/org/apache/commons/fileupload/DefaultFileItem.java,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- DefaultFileItem.java 27 Apr 2003 17:30:06 -0000 1.17
+++ DefaultFileItem.java 12 May 2003 05:24:52 -0000 1.18
@@ -367,9 +367,18 @@
/**
* A convenience method to write an uploaded item to disk. The client code
- * is not concerned whether or not the item is stored in memory, or on disk
- * in a temporary location. They just want to write the uploaded item to
- * disk.
+ * is not concerned with whether or not the item is stored in memory, or on
+ * disk in a temporary location. They just want to write the uploaded item
+ * to a file.
+ * <p>
+ * This implementation first attempts to rename the uploaded item to the
+ * specified destination file, if the item was originally written to disk.
+ * Otherwise, the data will be copied to the specified file.
+ * <p>
+ * This method is only guaranteed to work <em>once</em>, the first time it
+ * is invoked for a particular item. This is because, in the event that the
+ * method renames a temporary file, that file will no longer be available
+ * to copy or rename again at a later time.
*
* @param file The <code>File</code> into which the uploaded item should
* be stored.
@@ -457,9 +466,9 @@
/**
* A convenience method to write an uploaded item to disk. The client code
- * is not concerned whether or not the item is stored in memory, or on disk
- * in a temporary location. They just want to write the uploaded item to
- * disk.
+ * is not concerned with whether or not the item is stored in memory, or on
+ * disk in a temporary location. They just want to write the uploaded item
+ * to a file.
*
* @param file The full path to location where the uploaded file should
* be stored.
1.14 +24 -11 jakarta-commons/fileupload/src/java/org/apache/commons/fileupload/FileItem.java
Index: FileItem.java
===================================================================
RCS file: /home/cvs/jakarta-commons/fileupload/src/java/org/apache/commons/fileupload/FileItem.java,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- FileItem.java 27 Apr 2003 17:30:06 -0000 1.13
+++ FileItem.java 12 May 2003 05:24:52 -0000 1.14
@@ -130,7 +130,10 @@
/**
- * Returns the original filename in the client's filesystem.
+ * Returns the original filename in the client's filesystem, as provided by
+ * the browser (or other client software). In most cases, this will be the
+ * base file name, without path information. However, some clients, such as
+ * the Opera browser, do include path information.
*
* @return The original filename in the client's filesystem.
*/
@@ -194,9 +197,14 @@
/**
* A convenience method to write an uploaded item to disk. The client code
- * is not concerned whether or not the item is stored in memory, or on disk
- * in a temporary location. They just want to write the uploaded item to
- * disk.
+ * is not concerned with whether or not the item is stored in memory, or on
+ * disk in a temporary location. They just want to write the uploaded item
+ * to a file.
+ * <p>
+ * This method is not guaranteed to succeed if called more than once for
+ * the same item. This allows a particular implementation to use, for
+ * example, file renaming, where possible, rather than copying all of the
+ * underlying data, thus gaining a significant performance benefit.
*
* @param file The <code>File</code> into which the uploaded item should
* be stored.
@@ -208,9 +216,14 @@
/**
* A convenience method to write an uploaded item to disk. The client code
- * is not concerned whether or not the item is stored in memory, or on disk
- * in a temporary location. They just want to write the uploaded item to
- * disk.
+ * is not concerned with whether or not the item is stored in memory, or on
+ * disk in a temporary location. They just want to write the uploaded item
+ * to a file.
+ * <p>
+ * This method is not guaranteed to succeed if called more than once for
+ * the same item. This allows a particular implementation to use, for
+ * example, file renaming, where possible, rather than copying all of the
+ * underlying data, thus gaining a significant performance benefit.
*
* @param file The full path to location where the uploaded item should
* be stored.
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org