com.gubutech.xload
Interface XloadFileUpload


public interface XloadFileUpload

Provides a representation of a single file upload whether successful or not.

Implementations of this interface provide a representation of a single file upload designated on the client side by a single parameter name. The upload does not have to succeed and this interface provides methods to show the outcome of an attempted upload. (Implementations of this interface can also represent potential file uploads that were specifically targeted but did not appear in the request).

File uploads are checked in the following order for the following for failure.

Objects of this interface hold within it a FIFO(First In First Out) 'list' of all file deployments that have been completed for this file upload. They are listed using the following mechanism.

File uploads are targeted using the target methods and these targets essentially form the FIFO(First In First Out) list of file deployments previously mentioned in the order that they are targeted. At the point of uploading any targets that have been set using the XloadManager.targetEverything methods are loaded into the list as though the ordinary target methods have been called for that request parameter, and then any targets that have been set using the XloadManager.targetAll methods are added to the list in the same way. This is called JITT(Just In Time Targetting). If a file is targeted to memory (memory load) then this file deployment is moved to the head of the FIFO list.

When files, that are already file deployments are copied using the copy methods that are in the XloadFile interface, the FIFO list is altered accordingly appending the files to the end of the list. When files that are file deployments are deleted, the list is closed up and indexes altered accordingly.

When files, that are file deployments are moved to another location they remain in the FIFO list in their respective positions and are unaltered except if a memory loaded file is the file being moved. In this case a new file deployment is created and added to the end of the FIFO list and the original file deployment representing the memory loaded file is destroyed.

Many of the methods provided in this interface perform an underlying file existence check. The FIFO list is checked to see if any files have been inadvertantly deleted by some other process. If they have, the list is altered accordingly as though they had been deleted by Xload methods and recovery is graceful. If all files have been deleted by some underlying process then this object will behave as if the deleteAll() method had been called.

Since:
1.0

Method Summary
 boolean anyRenamed()
          Indicates whether or not any file deployments for this file upload have been renamed either by an installed renaming strategy on the initial upload or later by the programmer.
 boolean deleteAll()
          Deletes all file deployments associated with this file upload.
 boolean fileTooLarge()
          Indicates whether or not this file upload has failed.
 boolean formFieldBlank()
          Indicates whether or not this file upload has failed.
 java.util.List getDiskFiles()
          Returns an immutable List containing all disk based file deployments as XloadFile instances.
 int getFailureCode()
          Returns the failure code associated with this file upload.
 XloadFile getFile(int fileSequenceNumber)
          Returns the appropriate file related to the sequence number given from the FIFO (First In First Out) list described in the introduction of this class.
 XloadFile getFile(java.lang.String dir)
          Gets access to the first file deployment for this file upload that exists in the given directory from the FIFO (First In First Out) list described in the introduction for this class.
 XloadFile getFile(XloadDirectory dir)
          Gets access to the first file deployment for this file upload that exists in the given directory from the FIFO (First In First Out) list described in the introduction for this class.
 long getMaxSize()
          Returns the maximum allowable size associated with this upload.
 XloadFile getMemoryFile()
          Returns the memory file deployment associated with this file upload.
 java.lang.String getMIMEType()
          Returns the MIME type of this file upload.
 XloadFile getNext()
          This method works in conjunction with the hasMore family of methods of this class.
 java.lang.String getRemoteName()
          Returns the original name of this file upload that was given to it by the client on a remote machine (usually a browser).
 java.util.List getRenamed()
          Returns a List of file deployments that have been renamed either by an installed renaming strategy on the initial upload or later by the programmer.
 java.lang.String getRequestParameter()
          Returns the request parameter inside the request that this file upload is associated with.
 long getSize()
          Returns the actual size of this file upload.
 boolean hasAttemptedToUpload()
          Indicates whether this is a file upload that has been attempted or not.
 boolean hasIncorrectMIME()
          Indicates whether or not this file upload has failed.
 boolean hasMore()
          Indicates whether or not there are anymore existing file deployments related to this file upload.
 boolean hasMore(java.lang.String dir)
          Indicates whether or not there are anymore existing file deployments related to this file upload.
 boolean hasMore(XloadDirectory dir)
          Indicates whether or not there are anymore existing file deployments related to this file upload.
 boolean hasMultipleTargets()
          Indicates whether or not this file upload has been given more than one target to place a file deployment.
 boolean hasUploaded()
          Indicates whether or not this file upload has uploaded or not.
 boolean IOError()
          Indicates whether or not this file upload has failed.
 boolean isAnUploadFailure()
          Indicates whether or not this file upload is an upload failure or not.
 boolean isDeleted()
          Indicates whether or not all the file deployments for this file upload have been deleted.
 boolean notAFile()
          Indicates whether or not this file upload has failed.
 void reset()
          Resets the iterator so that using the hasMore set of methods iteration can be restarted.
 

Method Detail

formFieldBlank

public boolean formFieldBlank()
Indicates whether or not this file upload has failed. If it has, the client application (usually the browser) will have sent no name in the form field associated with this file upload.

Returns:
Returns true if the form field is blank, false otherwise.
Since:
1.0

fileTooLarge

public boolean fileTooLarge()
Indicates whether or not this file upload has failed. If it has, the client application (usually the browser) will have sent a file that is too large for this file upload (larger than the designated maximum size).

Returns:
Returns true if the file is too large, false otherwise.
Since:
1.0
See Also:
XloadManager

IOError

public boolean IOError()
Indicates whether or not this file upload has failed. If it has, there has been some IO problem while either sending this file or while file deployments of this file were being created. Note that after this IO error has occured no more file uploading will take place. This error only occurs when partial uploads are being allowed.

Returns:
Returns true if a file IO error has occured, false otherwise.
Since:
1.0
See Also:
XloadManager

notAFile

public boolean notAFile()
Indicates whether or not this file upload has failed. If it has, the client application (usually the browser) will have not sent a file. This normally means that the path given to the file is incorrect.

Returns:
Returns true if a file name and path were sent but no file data, false otherwise.
Since:
1.0

hasIncorrectMIME

public boolean hasIncorrectMIME()
Indicates whether or not this file upload has failed. If it has, the client application (usually the browser) will have sent a file with an incorrect MIME type not listed in the allowable MIME types set by XloadManager.setMIMETypes(String, String[]).

Returns:
true if a file name and path were sent but no file data, false otherwise.
Since:
1.0
See Also:
XloadManager

getDiskFiles

public java.util.List getDiskFiles()
Returns an immutable List containing all disk based file deployments as XloadFile instances.

Returns:
Immutable List containing all disk based file deployments. Returns an empty List if no disk based file deployments exist. Returns null if this file upload has been deleted, is an upload failure or was never attempted (redundant upload).
Throws:
java.lang.SecurityException - Thrown if there is a problem accessing files on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

getRequestParameter

public java.lang.String getRequestParameter()
Returns the request parameter inside the request that this file upload is associated with.

Returns:
The request parameter associated with this file upload.
Since:
1.0

getMaxSize

public long getMaxSize()
Returns the maximum allowable size associated with this upload.

Returns:
The maximum size in bytes.
Since:
1.0

getRemoteName

public java.lang.String getRemoteName()
Returns the original name of this file upload that was given to it by the client on a remote machine (usually a browser).

Returns:
The remote name.
Since:
1.0

getSize

public long getSize()
Returns the actual size of this file upload.

Returns:
The size of the upload in bytes. returns zero if this upload has been deleted, is an upload failure or has not been attempted.
Throws:
java.lang.SecurityException - Thrown if there is a problem accessing files on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

getMIMEType

public java.lang.String getMIMEType()
Returns the MIME type of this file upload.

Returns:
MIME type of file or null if no file has been uploaded.
Since:
1.0

hasMore

public boolean hasMore()
Indicates whether or not there are anymore existing file deployments related to this file upload. This method uses the FIFO list described in the introduction section and includes all file deployments for this file upload. It works in conjunction with the getNext() method which retrieves the next element in the list and the reset() method which resets the list to start back at the beginning again.

The order of the list will be dictated by the FIFO list described in this classes introduction, and will include a memory file deployment if one exists. If, while an iteration loop is in progress any alteration is made to the underlying file system this method will not show this alteration until the reset() method is called and a new iteration loop is started. This method will not display any fail-fast behaviour if an alteration occurs.

Returns:
Returns true if there are anymore file deployments in the list, false otherwise.
Throws:
java.lang.SecurityException - Thrown if there is a problem accessing files on the file system with regard to permissions set by the SecurityManager.
Since:
1.0
See Also:
getNext(), reset()

hasMore

public boolean hasMore(java.lang.String dir)
                throws javax.servlet.ServletException
Indicates whether or not there are anymore existing file deployments related to this file upload. This method uses the FIFO list described in the introduction section and includes all file deployments for this file upload in the given directory. It works in conjunction with the getNext() method which retrieves the next element in the list and the reset() method which resets the list to start back at the beginning again.

The order of the list will be dictated by the FIFO list described in this classes introduction, and will include a memory file deployment if one exists. If, while an iteration loop is in progress any alteration is made to the underlying file system this method will not show this alteration until the reset() method is called and a new iteration loop is started. This method will not display any fail-fast behaviour if an alteration occurs.

Parameters:
dir - Directory, as a String to look inside for file deployments. Can be relative or absolute(see XloadManager for an explanation).
Returns:
returns true if there are anymore file deployments in the list, false otherwise.
Throws:
javax.servlet.ServletException - Thrown if there are path conversion problems with the given dir.
XloadNullArgumentException - Thrown if paramName or dir are null.
java.lang.SecurityException - Thrown if there is a problem accessing files on the file system with regard to permissions set by the SecurityManager.
Since:
1.0
See Also:
getNext(), reset()

hasMore

public boolean hasMore(XloadDirectory dir)
Indicates whether or not there are anymore existing file deployments related to this file upload. This method uses the FIFO list described in the introduction section and includes all file deployments for this file upload in the given directory. It works in conjunction with the getNext() method which retrieves the next element in the list and the reset() method which resets the list to start back at the beginning again.

The order of the list will be dictated by the FIFO list described in this classes introduction, and will include a memory file deployment if one exists. If, while an iteration loop is in progress any alteration is made to the underlying file system this method will not show this alteration until the reset() method is called and a new iteration loop is started. This method will not display any fail-fast behaviour if an alteration occurs.

Parameters:
dir - Directory, as an XloadDirectory to look inside for file deployments.
Returns:
true if there are any more file deployments in the list, false otherwise.
Throws:
XloadNullArgumentException - Thrown if paramName or dir are null.
java.lang.SecurityException - Thrown if there is a problem accessing files on the file system with regard to permissions set by the SecurityManager.
Since:
1.0
See Also:
getNext(), reset()

anyRenamed

public boolean anyRenamed()
Indicates whether or not any file deployments for this file upload have been renamed either by an installed renaming strategy on the initial upload or later by the programmer. Renaming is specified as the file having a different written name as the one that the file was initially targeted to have (see XloadFile for a more detailed explanation).

Returns:
Returns true if any file deployments have been renamed, false otherwise or if this file upload has been deleted.
Throws:
java.lang.SecurityException - Thrown if there is a problem accessing files on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

getRenamed

public java.util.List getRenamed()
Returns a List of file deployments that have been renamed either by an installed renaming strategy on the initial upload or later by the programmer. Renaming is specified as the file having a different written name as the one that the file was initially targeted to have (see XloadFile for a more detailed explanation).

Returns:
An immutable List of file deployments that have been renamed which maybe empty if none have been. Returns null if this upload has been deleted, is an upload failure or has not been attempted.
Throws:
java.lang.SecurityException - Thrown if there is a problem accessing files on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

getFile

public XloadFile getFile(int fileSequenceNumber)
Returns the appropriate file related to the sequence number given from the FIFO (First In First Out) list described in the introduction of this class. The file deployments are listed and written in the order that they are targetted. Except for a file that is targeted to memory, which is always listed and written first.

Parameters:
fileSequenceNumber - Index position of the file in the FIFO list to retrieve (indexes begin at 1 and NOT 0 as with arrays).
Returns:
An XloadFile that relates to the sequence number given or null if one does not exist for the given sequence number. Also returns null if this file upload has been deleted, is an upload failure or has not been attempted.
Throws:
java.lang.SecurityException - Thrown if there is a problem accessing files on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

hasMultipleTargets

public boolean hasMultipleTargets()
Indicates whether or not this file upload has been given more than one target to place a file deployment.

Returns:
Returns whether multiple targeting is being used for this file upload.
Since:
1.0

deleteAll

public boolean deleteAll()
Deletes all file deployments associated with this file upload.

Returns:
Returns true if all file deployments are deleted successfully, false otherwise. Even if this method returns false, the state of all the file deployments associated with this file upload will be set to deleted within Xload even if their underlying files are not.
Throws:
java.lang.SecurityException - Thrown if there is a problem accessing files on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

getNext

public XloadFile getNext()
This method works in conjunction with the hasMore family of methods of this class. It retrieves the next element in the list described by the variations of hasMore methods that it is working with. It should not be used outside a loop defined by the hasMore family of methods.

Returns:
The next element in the FIFO list as an XloadFile instance.
Throws:
java.util.NoSuchElementException - Thrown if calling this method in an inappropriate location (for example: outside of a hasMore loop).
Since:
1.0
See Also:
hasMore(), hasMore(String), hasMore(XloadDirectory), reset()

getMemoryFile

public XloadFile getMemoryFile()
Returns the memory file deployment associated with this file upload.

Returns:
Returns the memory file deployment or null if one does not exist. Also returns null if this file upload has been deleted, is an upload failure or has not been attempted.
Since:
1.0

hasAttemptedToUpload

public boolean hasAttemptedToUpload()
Indicates whether this is a file upload that has been attempted or not. If targeting was specifically specified for a particular request parameter and that request parameter did not appear in the request then this XloadFileUpload object will be redundant and therefore not have been attempted.

Returns:
Returns true if a file upload has been attempted for this object, otherwise this object will have been redundant and this method returns false.
Since:
1.0

getFile

public XloadFile getFile(java.lang.String dir)
                  throws javax.servlet.ServletException
Gets access to the first file deployment for this file upload that exists in the given directory from the FIFO (First In First Out) list described in the introduction for this class. The file deployments are listed and written in the order that they are targeted.

Parameters:
dir - Directory, as a String object to look inside to retrieve the file deployment
Returns:
The first file deployment that exists for this file upload in the given directory or null if one does not exist. Also returns null if this upload has been deleted, is an upload failure or has not been attempted.
Throws:
javax.servlet.ServletException - Thrown if there are path conversion problems with the parameter dir.
XloadNullArgumentException - Thrown if dir is null.
java.lang.SecurityException - Thrown if there is a problem accessing files on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

getFile

public XloadFile getFile(XloadDirectory dir)
Gets access to the first file deployment for this file upload that exists in the given directory from the FIFO (First In First Out) list described in the introduction for this class. The file deployments are listed and written in the order that they are targeted.

Parameters:
dir - Directory, as a XloadDirectory object to look inside to retrieve the file deployment
Returns:
The first file deployment that exists for this file upload in the given directory or null if one does not exist. Also returns null if this upload has been deleted, is an upload failure or has not been attempted.
Throws:
XloadNullArgumentException - Thrown if dir is null.
java.lang.SecurityException - Thrown if there is a problem accessing files on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

isAnUploadFailure

public boolean isAnUploadFailure()
Indicates whether or not this file upload is an upload failure or not. A file upload can fail due to one of five conditions.
  • 1 - Blank form field.
  • 2 - Not a file. In other words, no file was sent with the request for whatever reason.
  • 3 - Incorrect MIME Type.
  • 4 - The file is too large.
  • any - An IO Error has occurred at some point. (Only applicable if partial uploads are being allowed and can occur at any point)

Returns:
Returns true if this file upload is an upload failure, false otherwise.
Since:
1.0

hasUploaded

public boolean hasUploaded()
Indicates whether or not this file upload has uploaded or not. If it hasn't this upload is either an upload failure or is a redundant upload.

Returns:
Returns true if this file upload has uploaded, false otherwise.
Since:
1.0

reset

public void reset()
Resets the iterator so that using the hasMore set of methods iteration can be restarted.

Throws:
java.lang.SecurityException - Thrown if there is a problem accessing files on the file system with regard to permissions set by the SecurityManager.
Since:
1.0
See Also:
hasMore(), hasMore(String), hasMore(XloadDirectory), getNext()

isDeleted

public boolean isDeleted()
Indicates whether or not all the file deployments for this file upload have been deleted.

Returns:
Returns true if all file deployments for this file upload have been deleted, false otherwise.
Since:
1.0

getFailureCode

public int getFailureCode()
Returns the failure code associated with this file upload.

Returns:
Returns the failure code associated with this file upload or 0 if no failure occurred.
  • 1 - Blank form field.
  • 2 - Not a file. In other words, no file was sent with the request for whatever reason.
  • 3 - Incorrect MIME Type.
  • 4 - The file is too large.
  • 5 - An IO Error has occurred at some point. (Only applicable if partial uploads are being allowed)
Since:
1.0