7) Handle File Upload Failures.

 

back to main index

 

An individual file upload can fail to upload for a number of reasons. When a file fails to upload Xload will store the reason for failure, skip over the offending file and continue to upload the next item in the request. If partial uploads are NOT being allowed (default situation) then when some IO Error occurs Xload will remove all file deployments, restore the system as it was before the HTTP request was made and throw an IOException from the upload() method. If partial uploads ARE being allowed then Xload will treat the IO Error has another type of upload failure condition for that particular part of the upload and return from the upload() method normally.

 

As we can see, upload failure works in close conjunction with partial uploads as the failure condition IO Error only occurs when partial uploads are being allowed. Please read the How Do I Use Partial Uploads section in conjunction with this one to get a full understanding. Normally, the IO Error will have been caused by a break in the connection between client and server and therefore it will be not possible to send a response back to the client. There is however a less likely situation when an IO Error occurs. This is when writing a file to the disk of the server and the connection between client and server still exists. In this case, a response can still be sent to the client.

 

The file upload failure conditions are checked for, in the following order:

 

1 - The file form field is blank; this maybe allowable within the requirements of what the programmer wants but is still technically an upload failure and therefore is treated as such.

 

2 - Not a file. In other words, no file was sent with the request for whatever reason such as an incorrect path to the file.

 

3 - Incorrect MIME Type (by default all MIME types are accepted but this can be restricted by the use of the setMIMETypes(String, String[]) method of the XloadManager class.

 

4 - The file is too large as specified by the default file size of 1GB or the lowest maximum size specified by the programmer.

 

Any - An IO Error has occurred at some point (Only applicable if partial uploads are being allowed and can occur at any point when uploading files, ordinary parameters and writing to the disk of the server).

 

 

IMPORTANT:-  You should always handle file upload failure situations even if it is just a simple check to see if any have failed (please note that you may be allowing the 'form field blank' failure condition). You may also want to use a more fine grained approach which determines exactly the cause of the failure (see code below for examples) so you can report this to the user. If partial uploads are being allowed, then IO Error failure should be included if using a more fine grained approach to upload failure. With partial uploads a response should always be sent because a client/server connection can still exist even if an IO Error has stopped processing. This said, be pragmatic in these situations as most of the time a partial upload occurs due to a breakdown in the client/server connection which means a response cannot then be sent.

 

 

IMPORTANT:-  The default maximum size for a file upload is 1GB. When you optionally specify a maximum size for a file upload then the default maximum size value of 1GB is ignored for that file upload; if you specify more than one maximum size for a file upload when uploading a file to multiple locations then the lowest value is used for that particular file upload.

 

 

 

The following code will handle file uploads that have failed due to one of the above reasons. Note that we are NOT using partial uploads in this case therefore if an IO Error occurs at any point during the upload process then the upload() method will throw an IOException.

 

 

1   XloadManager xman = new XloadManager(request);

2   xman.target("file1", "uploaded");

3   xman.target("file2", "uploaded");

4   xman.target("file3", "uploaded");

5   xman.target("file4", "uploaded");

6   xman.upload();

7                  

8   List uploadFailures = xman.getFailedFileUploads();

9   Iterator it = uploadFailures.iterator();

10  while(it.hasNext()){

11     XloadFileUpload fail = (XloadFileUpload)it.next();

12     //deal with upload failure generically as a single failure 

13  }

 

 

 

where:

request - HttpServletRequest object.

uploaded - directory to upload files to (relative to the web application directory).

file* - File parameter inside html (or other) form.

       

 

Alternatively a more fine grained approach is as follows:

 

//Replace Lines 11 and 12 with the following.

 

 

XloadFileUpload fail = (XloadFileUpload)it.next();

switch(fail.getFailureCode()){

case 1:

//deal with blank form field

case 2:

//deal with not a file

case 3:

//deal with incorrect MIME type

case 4:

//deal with file too large

case 5:

//deal with IO Error (If using partial uploads)

default:

//default situation if not handling specific errors

}

 

 

 

OR:

 

//Replace Lines 11 and 12 with the following.

 

 

XloadFileUpload fail = (XloadFileUpload)it.next();

if(fail.formFieldBlank(){

  //handling code here

}

if(fail.notAFile()){

  //handling code here

}

if(fail.hasIncorrectMime()){

  //handling code here

}

if(fail.fileTooLarge()){

  //handling code here

}

if(fail.IOError()){

  //if using partial uploads.

}

 

 

 

 

 

Xload provides methods to directly access different results of uploading and these are directly and indirectly linked to upload failures. We have already seen one of these methods; getFailedFileUploads() which retrieves all failed file uploads.

 

The other three are as follows:

getSuccessfulFileUploads() which retrieves all file uploads that were successful.

getRedundantTargetUploads() which retrieves all file uploads that were specifically targeted using the target() family of methods.

getAttemptedTargetUploads() which will retrieve all file uploads that were attempted whether successful or not.

 

How these are accessed is shown below:

 

 

XloadManager xman = new XloadManager(request);

...

...

xman.upload();

 

List uploadFailures = xman.getFailedFileUploads();

List successfulUploads = xman.getSuccessfulFileUploads();

List redundantUploads = xman.getRedundantTargetUploads();

List redundantUploads = xman.getAttemptedTargetUploads();

 

 

 

 

where:

request - HttpServletRequest object.

 

Other useful methods are available to help with the handling of upload failure and redundant uploads. These are hasAttemptedToUpload(), hasUploaded(), isAnUploadFailure(). These are demonstrated below:

 

 

XloadManager xman = new XloadManager(request);

...

...

xman.upload();

XloadFileUpload upload = xman.getFileUpload("file");

upload.hasAttemptedToUpload();

upload.hasUploaded();

upload.isAnUploadFailure();

 

 

 

 

Please see the Putting it all together section, specifically Handling Upload Failure with and without Partial Uploads for detailed examples.

 

back to main index

top of page

 

© Gubutech(Xload) 2006  (v1.2)