net.sourceforge.stripes.action
Class FileBean

java.lang.Object
  extended by net.sourceforge.stripes.action.FileBean

public class FileBean
extends Object

Represents a file that was submitted as part of an HTTP POST request. Provides methods for examining information about the file, and the retrieving the contents of the file. When a file is uploaded by a user it is stored as a temporary file on the file system, which is wrapped by an instance of this class. This is necessary because browsers may send file upload segments before sending any other form parameters needed to identify what to do with the uploaded files!

The application developer is responsible for removing this temporary file once they have processed it. This can be accomplished in one of two ways. Firstly a call to save(File) will effect a save by moving the temporary file to the desired location. In this case there is no need to call delete(), although doing so will not delete the saved file. The second way is to simply call delete(). This is more applicable when consuming the file as an InputStream. An example code fragment for reading a text based file might look like this:

 FileBean bean = getUserIcon();
 BufferedReader reader = new BufferedReader( new InputStreamReader(bean.getInputStream()) );
 String line = null

 while ( (line = reader.readLine()) != null) {
     // do something with line
 }

 bean.delete();
 

Author:
Tim Fennell

Constructor Summary
FileBean(File file, String contentType, String originalName)
          Constructs a FileBean pointing to an on-disk representation of the file uploaded by the user.
FileBean(File file, String contentType, String originalName, String charset)
          Constructs a FileBean pointing to an on-disk representation of the file uploaded by the user.
 
Method Summary
 void delete()
          Deletes the temporary file associated with this file upload if one still exists.
 String getContentType()
          Returns the content type of the file that the user selected and uploaded.
 String getFileName()
          Returns the name of the file that the user selected and uploaded (this is not necessarily the name that the underlying file is now stored on the server using).
 InputStream getInputStream()
          Gets an input stream to read from the file uploaded
 Reader getReader()
          Gets a reader to read characters from the uploaded file.
 Reader getReader(String charset)
          Gets a reader to read characters from the uploaded file using the given charset.
 long getSize()
          Gets the size of the file that was uploaded.
 void save(File toFile)
          Saves the uploaded file to the location on disk represented by File.
protected  void saveViaCopy(File toFile)
          Attempts to save the uploaded file to the specified file by performing a stream based copy.
 String toString()
          Returns the name of the file and the content type in a String format.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

FileBean

public FileBean(File file,
                String contentType,
                String originalName)
Constructs a FileBean pointing to an on-disk representation of the file uploaded by the user.

Parameters:
file - the File object on the server which holds the uploaded contents of the file
contentType - the content type of the file declared by the browser during upload
originalName - the name of the file as declared by the user's browser

FileBean

public FileBean(File file,
                String contentType,
                String originalName,
                String charset)
Constructs a FileBean pointing to an on-disk representation of the file uploaded by the user.

Parameters:
file - the File object on the server which holds the uploaded contents of the file
contentType - the content type of the file declared by the browser during upload
originalName - the name of the file as declared by the user's browser
charset - the charset specified by the servlet request
Method Detail

getFileName

public String getFileName()
Returns the name of the file that the user selected and uploaded (this is not necessarily the name that the underlying file is now stored on the server using).


getContentType

public String getContentType()
Returns the content type of the file that the user selected and uploaded.


getSize

public long getSize()
Gets the size of the file that was uploaded.


getInputStream

public InputStream getInputStream()
                           throws IOException
Gets an input stream to read from the file uploaded

Throws:
IOException

getReader

public Reader getReader()
                 throws UnsupportedEncodingException,
                        IOException
Gets a reader to read characters from the uploaded file. If the servlet request specifies a charset, then that charset is used. Otherwise, the reader uses the default charset.

Returns:
a new reader
Throws:
UnsupportedEncodingException
IOException

getReader

public Reader getReader(String charset)
                 throws UnsupportedEncodingException,
                        IOException
Gets a reader to read characters from the uploaded file using the given charset.

Parameters:
charset - the charset the reader should use
Returns:
a new reader
Throws:
UnsupportedEncodingException
IOException

save

public void save(File toFile)
          throws IOException
Saves the uploaded file to the location on disk represented by File. First attempts a simple rename of the underlying file that was created during upload as this is the most efficient route. If the rename fails an attempt is made to copy the file bit by bit to the new File and then the temporary file is removed.

Parameters:
toFile - a File object representing a location
Throws:
IOException - if the save will fail for a reason that we can detect up front, for example, missing files, permissions etc. or we try to save get a failure.

saveViaCopy

protected void saveViaCopy(File toFile)
                    throws IOException
Attempts to save the uploaded file to the specified file by performing a stream based copy. This is only used when a rename cannot be executed, e.g. because the target file is on a different file system than the temporary file.

Parameters:
toFile - the file to save to
Throws:
IOException

delete

public void delete()
            throws IOException
Deletes the temporary file associated with this file upload if one still exists. If save() has already been called then there is no temporary file any more, and this is a no-op.

Throws:
IOException - if the delete will fail for a reason we can detect up front, or if we try to delete and get a failure

toString

public String toString()
Returns the name of the file and the content type in a String format.

Overrides:
toString in class Object


? Copyright 2005-2006, Stripes Development Team.