2.17.2: 2011-06-17

net.sf.basedb.clients.web.fileupload
Class FileUpload

java.lang.Object
  extended by net.sf.basedb.clients.web.fileupload.FileUpload

public class FileUpload
extends Object

Objects of this class are used to handle file upload from browsers using the standard mechanism described in RFC1867.

Version:
2.0
Author:
Nicklas
Last modified
$Date$

Nested Class Summary
private static class FileUpload.SectionHeaders
          This class contains information extracted from the section headers for a form field or file upload field.
private static class FileUpload.UploadStatus
          This class contains information about the read status on the ServletInputStream
private  class FileUpload.UploadStream
           
 
Field Summary
private  byte[] boundary
          The multipart/formdata boundary
static long DEFAULT_TIMEOUT
          The default timeout to use when waiting for the next data packet to arrive.
private static String EMPTY_STRING
           
private static Pattern FILENAME_PATTERN
           
private  Map<String,List<UploadedFile>> files
          Contains information about uploaded files name --> UploadedFile
private  ServletInputStream in
          The stream coming from the browser.
private static Logger log
          Debug file upload.
private static Pattern NAME_PATTERN
           
private  Map<String,List<String>> parameters
          Contains information about regular input field parameters name --> value
private  FileUploadProgress progress
          Progress information for the upload
private  FileUpload.UploadStatus status
          The status of the upload.
private  long timeout
          The timeout in milliseconds that we wait for more data to arrive.
private  int transferRate
          The maximum transefer rate (bytes/second)
 
Constructor Summary
FileUpload(ServletRequest request)
          Create a new FileUpload object which will read the posted data from the given ServletRequest object.
FileUpload(ServletRequest request, int transferRate, long timeout)
          Create a new FileUpload object which will read the posted data from the given ServletRequest object limiting the transfer rate.
 
Method Summary
private  void addFile(String name, UploadedFile file)
          Store information about an uploaded file.
private  void addParameter(String name, String value)
          Store the value of a regular form field.
private  void checkAbortAndDelay()
          Check if upload has been aborted.
private  void checkBoundary(byte[] line, int lineLength, byte[] boundary, int boundaryLength)
          Check if the given line matches the boundary.
(package private)  void doUpload(OutputStream out, UploadedFile uf)
          Upload a single file section to the specified output stream
 boolean eof()
          Check if the end of the upload has been reached or not.
 UploadedFile getFile(String name)
          Get the file information for an uplodaded file.
 UploadedFile[] getFileValues(String name)
          Get the file information for uplodaded files.
private  String getHeaderAttribute(String header, Pattern p)
           
(package private)  InputStream getInputStream(UploadedFile uf)
          Get an input stream for reading from the current file section.
 String getParameter(String name)
          Get the value for a form field.
 Iterator getParameterNames()
          Get the names for all fields used in the form, excluding file input fields.
 String[] getParameterValues(String name)
          Get an array of values for a form field.
 FileUploadProgress getProgress()
          Get progress information about the upload.
 UploadedFile next()
          Read from the input stream until a file section is found or the end is encountered.
private  String readFormData(byte[] boundary)
          Read from ServletInputStream until the boundary is found.
private  int readLine(byte[] b, int off, int len)
          Read next line of data into a buffer.
private  String readLineAsString()
          Reads the next line of input and returns it as a string.
private  FileUpload.SectionHeaders readSectionHeaders()
          Read from ServletInputStream until an empty line is found.
private  void readToBoundary(byte[] boundary)
          Read from ServletInputStream until the boundary is found on a line by itself.
 void setException(Throwable t)
          Set exception information on the associated FileUploadProgress object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

log

private static final Logger log
Debug file upload.


DEFAULT_TIMEOUT

public static final long DEFAULT_TIMEOUT
The default timeout to use when waiting for the next data packet to arrive.

See Also:
Constant Field Values

EMPTY_STRING

private static final String EMPTY_STRING
See Also:
Constant Field Values

parameters

private Map<String,List<String>> parameters
Contains information about regular input field parameters name --> value


files

private Map<String,List<UploadedFile>> files
Contains information about uploaded files name --> UploadedFile


in

private ServletInputStream in
The stream coming from the browser.


status

private FileUpload.UploadStatus status
The status of the upload.


progress

private FileUploadProgress progress
Progress information for the upload


boundary

private byte[] boundary
The multipart/formdata boundary


transferRate

private int transferRate
The maximum transefer rate (bytes/second)


timeout

private long timeout
The timeout in milliseconds that we wait for more data to arrive. Default value is 60000 = 60 seconds.


NAME_PATTERN

private static final Pattern NAME_PATTERN

FILENAME_PATTERN

private static final Pattern FILENAME_PATTERN
Constructor Detail

FileUpload

public FileUpload(ServletRequest request)
           throws IOException,
                  UploadAbortedException
Create a new FileUpload object which will read the posted data from the given ServletRequest object.

Parameters:
request - The ServletRequest object containg information about the request (and file upload)
Throws:
IOException - If there is an error reading from the request stream
UploadAbortedException - If the upload was aborted

FileUpload

public FileUpload(ServletRequest request,
                  int transferRate,
                  long timeout)
           throws IOException,
                  UploadAbortedException
Create a new FileUpload object which will read the posted data from the given ServletRequest object limiting the transfer rate.

Parameters:
request - The ServletRequest object containg information about the request (and file upload)
transferRate - The maximum transfer rate in bytes per second, or 0 to transfer as fast as possible
timeout - The timeout in milliseconds to wait for the next packet of data to arrive
Throws:
IOException - If there is an error reading from the request stream
UploadAbortedException - If the upload was aborted
Method Detail

getProgress

public FileUploadProgress getProgress()
Get progress information about the upload.


eof

public boolean eof()
Check if the end of the upload has been reached or not.

Returns:
TRUE if the end has been reached, FALSE otherwise

next

public UploadedFile next()
                  throws IOException,
                         UploadAbortedException
Read from the input stream until a file section is found or the end is encountered.

Returns:
An UploadedFile object with information about the next file section, or null if there are no more file sections
Throws:
IOException - If reading the file fails.
UploadAbortedException - If the uploaded has been requested to abort.

doUpload

void doUpload(OutputStream out,
              UploadedFile uf)
        throws IOException,
               UploadAbortedException
Upload a single file section to the specified output stream

Throws:
IOException
UploadAbortedException

getInputStream

InputStream getInputStream(UploadedFile uf)
                     throws IOException
Get an input stream for reading from the current file section.

Throws:
IOException

addParameter

private void addParameter(String name,
                          String value)
Store the value of a regular form field.

Parameters:
name - The name of the form field
value - The value

addFile

private void addFile(String name,
                     UploadedFile file)
Store information about an uploaded file.

Parameters:
name - The name of the form field
file - A UploadedFile object containing information about the uploaded file

getParameter

public String getParameter(String name)
Get the value for a form field. Use this method if the form contains only a single element with this name, otherwise use the getParameterValues(String) method.

Parameters:
name - The name of the form field
Returns:
The value of form field or NULL if it is not found
See Also:
getParameterValues(String)

getParameterValues

public String[] getParameterValues(String name)
Get an array of values for a form field. Use this method if the form contains several elements with the same name, otherwise use the getParameter(String) method.

Parameters:
name - The name of the form field
Returns:
An array of values, or NULL if no values are found
See Also:
getParameter(String)

getParameterNames

public Iterator getParameterNames()
Get the names for all fields used in the form, excluding file input fields.

Returns:
An Iterator object that can be used to iterate through the collection of form fields

getFile

public UploadedFile getFile(String name)
Get the file information for an uplodaded file. Use this method if the form contains only a single element with this name, otherwise use the getFileValues(String) method.

Parameters:
name - The name of the upload form field
Returns:
An UploadedFile object or NULL if it the field with this name is not found
See Also:
getFileValues(String)

getFileValues

public UploadedFile[] getFileValues(String name)
Get the file information for uplodaded files. Use this method if the form contains several elements with the same name, otherwise use the getFile(String) method.

Parameters:
name - The name of the upload form field(s)
Returns:
An array of UploadedFile objects or NULL if it no fields with this name are not found
See Also:
getFile

setException

public void setException(Throwable t)
Set exception information on the associated FileUploadProgress object. This is a useful way to communicate if the uploading is done by one thread and the progress display in another. This method is also called if an exception occures internally in this object.

Parameters:
t - The throwable object to set.

getHeaderAttribute

private String getHeaderAttribute(String header,
                                  Pattern p)

checkBoundary

private void checkBoundary(byte[] line,
                           int lineLength,
                           byte[] boundary,
                           int boundaryLength)
Check if the given line matches the boundary. The line always has an extra CRLF pair at the end and may also have two dashes (--). The two dashes indicates the end of the input for the form.


readLineAsString

private String readLineAsString()
                         throws IOException
Reads the next line of input and returns it as a string. We assume that the length of the line is less than 1000 bytes, or this method will clip the string after that many characters. This method is used when reading section headers.

Returns:
The string
Throws:
IOException

readFormData

private String readFormData(byte[] boundary)
                     throws IOException,
                            UploadAbortedException
Read from ServletInputStream until the boundary is found. This method is used to read data from ordinary (not file upload) form fields.

Returns:
A string representation of the data that was read
Throws:
IOException
UploadAbortedException

readToBoundary

private void readToBoundary(byte[] boundary)
                     throws IOException,
                            UploadAbortedException
Read from ServletInputStream until the boundary is found on a line by itself. This method is used to skip data whenver necessary.

Throws:
IOException
UploadAbortedException

readSectionHeaders

private FileUpload.SectionHeaders readSectionHeaders()
                                              throws IOException,
                                                     UploadAbortedException
Read from ServletInputStream until an empty line is found. This method is used to read section headers. return A SectionHeaders object with information about the headers found

Throws:
IOException
UploadAbortedException

checkAbortAndDelay

private void checkAbortAndDelay()
                         throws UploadAbortedException
Check if upload has been aborted. Check the transfer rate and wait if necessary.

Throws:
UploadAbortedException

readLine

private int readLine(byte[] b,
                     int off,
                     int len)
              throws IOException
Read next line of data into a buffer.

Returns:
The number of bytes read or -1 if the end is reached
Throws:
IOException
Since:
2.1.2

2.17.2: 2011-06-17