martinc 2002/08/08 21:02:43
Modified: src/share/org/apache/struts/upload FormFile.java
Log:
Document that the caller must close the input stream after obtaining it
from getInputStream(), as suggested by Hans-Joachim Matheus is Bugzilla
#3465. Miscellaneous other Javadoc cleanup.
Revision Changes Path
1.4 +51 -38 jakarta-struts/src/share/org/apache/struts/upload/FormFile.java
Index: FormFile.java
===================================================================
RCS file: /home/cvs/jakarta-struts/src/share/org/apache/struts/upload/FormFile.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- FormFile.java 6 Jul 2002 04:44:07 -0000 1.3
+++ FormFile.java 9 Aug 2002 04:02:43 -0000 1.4
@@ -59,81 +59,94 @@
*
*/
+
package org.apache.struts.upload;
+
import java.io.InputStream;
import java.io.IOException;
import java.io.FileNotFoundException;
+
/**
- * This interface is used to define a file uploaded by a client.
+ * This interface represents a file that has been uploaded by a client. It is
+ * the only interface or class in upload package which is typically referenced
+ * directly by a Struts application.
*/
public interface FormFile
{
/**
- * Get the content type for this file.
- * @return A String representing content type
+ * Returns the content type for this file.
+ *
+ * @return A String representing content type.
*/
public String getContentType();
/**
- * Set the content type for this file
- * @param contentType The content type
+ * Sets the content type for this file.
+ *
+ * @param contentType The content type for the file.
*/
public void setContentType(String contentType);
/**
- * Get the size of this file
- * @return An int representing the size of the file in bytes
+ * Returns the size of this file.
+ *
+ * @return The size of the file, in bytes.
*/
public int getFileSize();
/**
- * Set the file size
- * @param filesize An int reprsenting the size of the file in bytes
+ * Sets the file size.
+ *
+ * @param fileSize The size of the file, in bytes,
*/
- public void setFileSize(int filesize);
+ public void setFileSize(int fileSize);
/**
- * Get the file name of this file.
- * @return A String reprsenting a file name
+ * Returns the file name of this file. This is the base name of the file,
+ * as supplied by the user when the file was uploaded.
+ *
+ * @return The base file name.
*/
public String getFileName();
/**
- * Set the filename of this file
- * @param fileName The name of the file
+ * Sets the file name of this file.
+ *
+ * @param fileName The base file name.
*/
public void setFileName(String fileName);
/**
- * Get the data in byte array for for this file. Note that this can be
- * a very hazardous method, files can be large enough to cause
- * OutOfMemoryErrors. Short of being deprecated, it's strongly recommended
- * that you use {@link #getInputStream() getInputStream} to get the file
- * data.
+ * Returns the data for the entire file as byte array. Care is needed when
+ * using this method, since a large upload could easily exhaust available
+ * memory. The preferred method for accessing the file data is
+ * {@link #getInputStream() getInputStream}.
*
- * @exception FileNotFoundException If some sort of file representation
- * cannot be found for the FormFile
- * @exception IOException If there is some sort of IOException
- * @return An array of bytes representing the data contained
- * in the form file
+ * @return The file data as a byte array.
+ *
+ * @exception FileNotFoundException if the uploaded file is not found.
+ * @exception IOException if an error occurred while reading the
+ * file.
*/
- public byte[] getFileData() throws FileNotFoundException, IOException;
+ public byte[] getFileData()
+ throws FileNotFoundException, IOException;
/**
- * Get an InputStream that represents this file. This is the preferred
- * method of getting file data.
- * @exception FileNotFoundException If some sort of file representation
- * cannot be found for the FormFile
- * @exception IOException If there is some sort of IOException
+ * Returns an input stream for this file. The caller must close the
+ * stream when it is no longer needed.
+ *
+ * @exception FileNotFoundException if the uploaded file is not found.
+ * @exception IOException if an error occurred while reading the
+ * file.
*/
- public InputStream getInputStream() throws FileNotFoundException, IOException;
+ public InputStream getInputStream()
+ throws FileNotFoundException, IOException;
/**
- * Destroy all content for this form file.
- * Implementations should remove any temporary
- * files or any temporary file data stored somewhere
+ * Destroys all content for the uploaded file, including any underlying
+ * data files.
*/
public void destroy();
-}
\ No newline at end of file
+}
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
