com.gubutech.xload
Class XloadManager

java.lang.Object
  extended bycom.gubutech.xload.XloadManager

public class XloadManager
extends java.lang.Object

Controller class for all types of file uploads

GENERAL:

This implementation allows a maximum upload request size of 2GB (as this is the largest value the http header content-length will hold).

Every request can contain many file uploads within it or none at all.

File uploads are targeted using the target methods and these targets essentially form a FIFO(First In First Out) list of locations to place files. Each file upload can have many targets or none at all depending upon the programmers requirements. These targets are set before upload() is called. When upload() is called, any targets that have been set using the targetEverything methods are added first into the FIFO list, as though the ordinary target methods have been called for that request parameter. Then, any targets that have been set using the targetAll methods are added to the list in the same way. This is called JITT(Just In Time Targeting).

If no maximum size value(in kb) is used for a particular file upload then a default value of 1Gb will be set as the maximum size for the upload. If a value is set then this will overide the default value even if it is higher than the default value. If more than one value is set for a file upload then the lowest value is used.

This class uploads one file at a time (multiple files can be uploaded) and each file upload corresponds to one request parameter located inside the initial request.

It deploys each file on disk and/or in memory as required depending upon targets set for each file. Each file loaded into memory and/or written to disk is called a file deployment. There can be many file deployments for each file upload but only one file deployment into memory. When a file is copied (using other classes) the new file is also a file deployment and is added to the list of file deployments for that file upload. When a file is moved it remains a file deployment. file deployments only exist for the duration of the upload request. During subsequent requests they revert to being ordinary files on the system like any other file.

An XloadFile object can represent an instance of a file deployment after files have actually bean uploaded. XloadFile instances can also refer to any file on the file system. An XloadFileUpload refers to a single file upload and a single request parameter inside the request and contains individual XloadFile file deployments. The files returned by appropriate methods in this class and others will be appropriate ones (i.e. whether a file deployment or not). These files can be manipulated and tested to see if they indeed are a file deployment or not.

File deployments are written/stored in the order that they are targeted in the FIFO(First In First Out) list described above. The only exception is the memory file deployment which always resides first in the list. Retrieval of file deployments is via this FIFO list and is encapsulated in the XloadFileUpload interface with certain convenience methods existing in this class.

RENAMING STRATEGIES FOR FILES:

Files are written to disk and renamed if necessary. The renaming strategy used is dependant on the programmer. The default mechanism is to attempt to write the file using its remoteName initially (see XloadFile for an explanation of remoteName etc.) and if a name collision occurs, append a numeral(s) to the file name after each failed attempt to rename; for example - filename(1).txt, filename(2).txt, filename(3).txt etc.... Files are created and written to the file system in a totally safe way as regards concurrent operations are concerned, by using this strategy. The programmer does not need to worry about synchronization. The programmer can create a new rename strategy by implementing an inteface called XloadFileRename. Another rename strategy already exists (XloadCounterFileRename) which renames every file to an arbitrary number.

UPLOAD FAILURE:

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

If an individual file upload fails for any reason no file deployments are created at all for that file upload, the reason is stored and Xload moves onto the next upload if there is one; unless an IO Error occurs at which point processing of the request stops and the upload() method returns normally if partial uploads are being allowed OR deletes all files and throws an IOException if partial uploads are not being allowed.

ABSOLUTE AND RELATIVE PATHS:

If using the default constructor for this classes creation, all paths must be absolute otherwise they can be relative or absolute. Absolute paths must be machine specific. Relative paths must not begin with any separation character but must use the "/" for directory separation. All relative paths are relative to the web application root folder.
For example:

C:\webapps\webappRootFolder - root folder
C:\webapps\webappRootFolder\resource - resource folder

The relative path to the resource is just: resource

PARTIAL UPLOADS:

Partial uploads are allowed using Xload and are set by use of appropriate constructors. This means that upon an IO Error while uploading more fine grained results can be obtained from Xload. If partial uploads ARE being allowed then processing of the request is stopped where the IO Error occurred and all file uploads that have occurred prior to the IO Error are NOT deleted and CAN be accessed after the upload() method has returned. Xload will basically have shortened the upload process but will allow the programmer to access files and parameters already uploaded, in the normal way.

The main advantage of this is that if a client is uploading a large number of files and half way through some network error occurs, at least half the files can be stored properly and do NOT have to be uploaded again. If partial uploads are NOT being allowed then upon an IO Error all uploaded files are deleted, the system state is set to before any uploading has taken place and an IOException is thrown. It must be noted that an IO Error can occur at any time during the reading or writing process which includes the reading of standard request parameters, therefore the possibility of failure to upload any data that was in the request, must be catered for when using partial uploads.

MISCELLANEOUS:

Any attempt to read the body directly via ServletRequest.getInputStream() or ServletRequest.getReader() can interfere with the execution of Xload and the upload() method.

Since:
1.0
See Also:
XloadFileRename, XloadIncrementalFileRename, XloadCounterFileRename, XloadFile, XloadFileUpload

Constructor Summary
XloadManager()
          Creates a new instance of XloadManager with limited functionality.
XloadManager(javax.servlet.http.HttpServletRequest request)
          Creates a new instance of XloadManager from the specified request.
XloadManager(javax.servlet.http.HttpServletRequest request, boolean allowPartialUploads)
          Creates a new instance of XloadManager from the specified request.
XloadManager(javax.servlet.http.HttpServletRequest request, XloadFileRename renameStrategy)
          Creates a new instance of XloadManager from the specified request.
XloadManager(javax.servlet.http.HttpServletRequest request, XloadFileRename renameStrategy, boolean allowPartialUploads)
          Creates a new instance of XloadManager from the specified request.
 
Method Summary
 boolean anyRenamed()
          Informs whether or not any files that have been written to disk were renamed via the installed rename startegy due to naming clashes.
 XloadDirectory createDirectory(java.lang.String dir, java.lang.String newDir)
          Creates a directory in the appropriate directory and returns an XloadDirectory instance.
 boolean deleteAll()
          Deletes all files associated with the upload performed by this XloadManager object.
 boolean directoryExists(java.lang.String dir)
          Indicates whether or not a directory exists on the file system designated by the parameter dir.
 XloadFile getAnyFile(java.lang.String dir, java.lang.String fileName)
          Gets access to a file that is designated by a given directory and filename.
 java.util.List getAttemptedTargetUploads()
          Returns an immutable List containing all the file uploads (represented as XloadFileUpload objects) that were attempted irrespective of the outcome (success or failure).
 XloadDirectory getDirectory(java.lang.String dir)
          Returns an XloadDirectory representing a directory on the file system given a path dir.
 java.util.List getFailedFileUploads()
          Returns an immutable List containing all the file uploads (represented as XloadFileUpload objects) that were attempted but failed.
 XloadFile getFile(java.lang.String paramName)
          Gets access to the first file deployment from the list, for a file upload designated on the client side by paramName.
 XloadFile getFile(java.lang.String paramName, java.lang.String dir)
          Gets access to the first file deployment from the list, in the designated directory dir for a file upload designated on the client side by paramName.
 XloadFile getFile(java.lang.String paramName, XloadDirectory dir)
          Gets access to the first file deployment from the list, in designated directory dir for a file upload designated on the client side by paramName.
 java.util.List getFileParameterNames()
          Returns an immutable List of all the parameter names which are of type 'file'.
 XloadFileUpload getFileUpload(java.lang.String paramName)
          Gets an object that corresponds to a single file upload attempt.
 XloadFile getMemoryFile(java.lang.String paramName)
          Returns an XloadFile that represents a file deployment to memory for the file upload designated on the client side by paramName.
 java.lang.String getParameter(java.lang.String paramName)
          Returns the value of a request parameter as a String, or null if the parameter does not exist.
 java.util.Map getParameterMap()
          Returns a Map of the parameters of this request.
 java.util.Enumeration getParameterNames()
          Returns an Enumeration of String objects containing the names of the parameters contained in this request.
 java.lang.String[] getParameterValues(java.lang.String paramName)
          Returns an array of String objects containing all of the values for the given request parameter paramName, or null if the parameter does not exist.
 XloadProgressData getProgressData()
          Gets progress data for a particular upload.
 java.util.List getRedundantTargetUploads()
          Returns an immutable List containing all the potential file uploads (represented as XloadFileUpload objects) that were NOT attempted.
 java.util.List getRenamed()
          Gets a list of file deployments that have been written to disk and were renamed via the installed rename startegy due to naming clashes.
 java.util.List getSuccessfulFileUploads()
          Returns an immutable List containing all the file uploads (represented as XloadFileUpload objects) that were successful.
 boolean hasMultipleTargets(java.lang.String paramName)
          Informs whether or not at anytime there is more than one target for the file upload designated on the client side by the paramName.
 boolean hasPartialUploadOccurred()
          Indicates whether or not a partial upload has occurred.
 void setEncoding(java.lang.String encoding)
          Sets internal encoding allowing the use of a custom encoding if needed.
static void setKeyCode(java.lang.String code, java.lang.String details)
          Allows the setting of a KeyCode and User Details that turns this evaluation version into a full version.
 void setMIMETypes(java.lang.String paramName, java.lang.String[] mimes)
          Sets allowable MIME types for a particular file upload designated on the client side by paramName.
 void target(java.lang.String paramName, int maxSize)
          Targets a file upload designated on the client side by the paramName to memory(memory loading) with a given maximum size.
 void target(java.lang.String paramName, java.lang.String target)
          Convenience method that targets a file upload designated on the client side by the paramName to the specified target.
 void target(java.lang.String paramName, java.lang.String target, int maxSize)
          Targets a file upload designated on the client side by the paramName to the specified target with a given maximum size.
 void targetAll(int maxSize)
          Targets ALL file uploads inside a request to memory(memory loading) with a given maximum size.
 void targetAll(java.lang.String target)
          Convenience method that targets ALL file uploads inside a request to a specified target.
 void targetAll(java.lang.String target, int maxSize)
          Targets ALL file uploads inside a request to a specified target with a given maximum size.
static void targetEverything(int maxSize)
          Targets EVERY file upload that is performed by an XloadManager to memory(memory loading) across all instances of XloadManager objects; with reference to the class loader that originally loaded the XloadManager class(note: what this means is that different web applications most probably have different class loaders therefore a call to targetEverything() methods will only apply to XloadManager instances in the same web application).
static void targetEverything(java.lang.String target)
          Convenience method that targets EVERY file upload that is performed by an XloadManager to a specified target across all instances of XloadManager objects; with reference to the class loader that originally loaded the XloadManager class(note: what this means is that different web applications most probably have different class loaders therefore a call to targetEverything() methods will only apply to XloadManager instances in the same web application).
static void targetEverything(java.lang.String target, int maxSize)
          Targets EVERY file upload that is performed by an XloadManager to a specified target across all instances of XloadManager objects; with reference to the class loader that originally loaded the XloadManager class(note: what this means is that different web applications most probably have different class loaders therefore a call to targetEverything() will only apply to XloadManager instances in the same web application).
 void upload()
          Parses request and performs uploads required.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XloadManager

public XloadManager(javax.servlet.http.HttpServletRequest request)
Creates a new instance of XloadManager from the specified request. This XloadManager uses the default encoding UTF-8 and default file incremental renaming. Partial uploads are not allowed, see the introduction of this class for an explanation.

Parameters:
request - HttpServletRequest object from initial request.
Throws:
XloadNullArgumentException - Thrown if request is null.
Since:
1.0

XloadManager

public XloadManager(javax.servlet.http.HttpServletRequest request,
                    boolean allowPartialUploads)
Creates a new instance of XloadManager from the specified request. This XloadManager uses the default encoding UTF-8 and default file incremental renaming. The parameter allowPartialUploads can be used to determine whether or not partial uploads are allowed, see the introduction to this class for an explanation.

Parameters:
request - HttpServletRequest object from initial request.
allowPartialUploads - If set to true partial uploads are allowed.
Throws:
XloadNullArgumentException - Thrown if request is null.
Since:
1.0

XloadManager

public XloadManager(javax.servlet.http.HttpServletRequest request,
                    XloadFileRename renameStrategy)
Creates a new instance of XloadManager from the specified request. This XloadManager uses the default encoding UTF-8 and a given file rename strategy. Partial uploads are not allowed, see the introduction of this class for an explanation.

Parameters:
request - HttpServletRequest object from initial request.
renameStrategy - Rename strategy for file name collisions.
Throws:
XloadNullArgumentException - Thrown if request or renameStrategy are null.
Since:
1.0

XloadManager

public XloadManager(javax.servlet.http.HttpServletRequest request,
                    XloadFileRename renameStrategy,
                    boolean allowPartialUploads)
Creates a new instance of XloadManager from the specified request. This XloadManager uses the default encoding UTF-8 and a given file rename strategy. The parameter allowPartialUploads can be used to determine whether or not partial uploads are allowed, see the introduction to this class for an explanation.

Parameters:
request - HttpServletRequest object from initial request.
renameStrategy - Rename strategy for file name collisions.
allowPartialUploads - If set to true partial uploads are allowed.
Throws:
XloadNullArgumentException - Thrown if request or renameStrategy are null.
Since:
1.0

XloadManager

public XloadManager()
Creates a new instance of XloadManager with limited functionality. Functionality is confined to any methods that do not involve the request object. These are file retreival and directory manipulation methods only. This constructor is designed to be used in code that manipulates a file structure for some administration purpose and that does not necessarily revolve around a specific request.

Since:
1.0
Method Detail

setEncoding

public void setEncoding(java.lang.String encoding)
Sets internal encoding allowing the use of a custom encoding if needed.

Parameters:
encoding - - Encoding used to read content with.
Since:
1.0

upload

public void upload()
            throws javax.servlet.ServletException,
                   java.io.IOException
Parses request and performs uploads required. Only after this method is called are any uploads performed. Until this method is called none of the request is parsed.

Throws:
javax.servlet.ServletException - Thrown if more than one file is uploaded using the same parameter name or if this method is called more than once in the life of this object or if any path conversion problems occur while adding targeting that was specified using the targetAll, targetEverything methods.
java.io.IOException - Thrown if an IO error occurs while uploading.
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
java.lang.SecurityException - Thrown if there is a problem accessing some of the target directories on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

target

public void target(java.lang.String paramName,
                   java.lang.String target,
                   int maxSize)
            throws javax.servlet.ServletException
Targets a file upload designated on the client side by the paramName to the specified target with a given maximum size.

Parameters:
paramName - Parameter name inside the request that corresponds to a file upload.
target - Target to write the file to. Must be a directory (but can include a file name to write to if required).
maxSize - Maximum size allowable in kilobytes for this individual file. The lowest maximum size value is used if multiple maximum sizes exist(via multiple targetting) for the same file.
Throws:
javax.servlet.ServletException - Throws a ServletException if the target given has conversion problems.
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadNullArgumentException - Thrown if paramName or target are null.
XloadUploadException - Thrown if calling this method after calling upload() which is semantically incorrect.
java.lang.SecurityException - Thrown if there is a problem accessing some of the target directories on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

target

public void target(java.lang.String paramName,
                   java.lang.String target)
            throws javax.servlet.ServletException
Convenience method that targets a file upload designated on the client side by the paramName to the specified target. A default maximum size(1Gb) is requested using this method but will only be used if no other maximum size is set for this file upload.

Parameters:
paramName - Parameter name inside the request that corresponds to a file upload.
target - Target to write the file to. Must be a directory (but can include a file name to write to if required).
Throws:
javax.servlet.ServletException - Throws a ServletException if the target given has conversion problems.
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadNullArgumentException - Thrown if paramName or target are null.
XloadUploadException - Thrown if calling this method after calling upload() which is semantically incorrect.
java.lang.SecurityException - Thrown if there is a problem accessing some of the target directories on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

target

public void target(java.lang.String paramName,
                   int maxSize)
Targets a file upload designated on the client side by the paramName to memory(memory loading) with a given maximum size. It must be noted that when setting the maximum size, a number of bytes equal to the maximum size will be allocated in memory to this file upload even if the actual size of the file uploaded may be considerably smaller.

Parameters:
paramName - Parameter name inside the request that corresponds to a file upload.
maxSize - Maximum size allowable in kilobytes for this individual file. The lowest maximum size value is used if multiple maximum sizes exist(via multiple targeting) for the same file.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadNullArgumentException - Thrown if paramName is null.
XloadUploadException - Thrown if calling this method after calling upload() which is semantically incorrect.
Since:
1.0

targetAll

public void targetAll(java.lang.String target,
                      int maxSize)
Targets ALL file uploads inside a request to a specified target with a given maximum size.

Parameters:
target - Target to write the file to. Must be a directory (but can include a file name to write to if required).
maxSize - Maximum size allowable in kilobytes for ALL files. The lowest maximum size value is used if multiple maximum sizes exist(via multiple targeting) for the same file.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadNullArgumentException - Thrown if target is null.
XloadUploadException - Thrown if calling this method after calling upload() which is semantically incorrect.
Since:
1.0

targetAll

public void targetAll(java.lang.String target)
Convenience method that targets ALL file uploads inside a request to a specified target. For each file upload, a default maximum size(1Gb) is requested using this method but will only be used if no other maximum size is set.

Parameters:
target - Target to write the file to. Must be a directory (but can include a file name to write to if required).
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadNullArgumentException - Thrown if target is null.
XloadUploadException - Thrown if calling this method after calling upload() which is semantically incorrect.
Since:
1.0

targetAll

public void targetAll(int maxSize)
Targets ALL file uploads inside a request to memory(memory loading) with a given maximum size. It must be noted that when setting the maximum size, a number of bytes equal to the maximum size will be allocated in memory to the file upload even if the actual size of the file uploaded is considerably smaller.

Parameters:
maxSize - Maximum size allowable in kilobytes for ALL files. The lowest maximum size value is used if multiple maximum sizes exist(via multiple targeting) for the same file.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadUploadException - Thrown if calling this method after calling upload() which is semantically incorrect.
Since:
1.0

targetEverything

public static void targetEverything(java.lang.String target,
                                    int maxSize)
Targets EVERY file upload that is performed by an XloadManager to a specified target across all instances of XloadManager objects; with reference to the class loader that originally loaded the XloadManager class(note: what this means is that different web applications most probably have different class loaders therefore a call to targetEverything() will only apply to XloadManager instances in the same web application). A specified maximum size is requested.

Parameters:
target - Target to write the file to. Must be a directory (but can include a file name to write to if required).
maxSize - Maximum size allowable in kilobytes for ALL files. The lowest maximum size value is used if multiple maximum sizes exist(via multiple targeting) for the same file.
Throws:
XloadNullArgumentException - Thrown if target is null.
Since:
1.0

targetEverything

public static void targetEverything(java.lang.String target)
Convenience method that targets EVERY file upload that is performed by an XloadManager to a specified target across all instances of XloadManager objects; with reference to the class loader that originally loaded the XloadManager class(note: what this means is that different web applications most probably have different class loaders therefore a call to targetEverything() methods will only apply to XloadManager instances in the same web application). For each file upload, a default maximum size(1Gb) is requested using this method but will only be used if no other maximum size is set.

Parameters:
target - Target to write the file to. Must be a directory (but can include a file name to write to if required).
Throws:
XloadNullArgumentException - Thrown if target is null.
Since:
1.0

targetEverything

public static void targetEverything(int maxSize)
Targets EVERY file upload that is performed by an XloadManager to memory(memory loading) across all instances of XloadManager objects; with reference to the class loader that originally loaded the XloadManager class(note: what this means is that different web applications most probably have different class loaders therefore a call to targetEverything() methods will only apply to XloadManager instances in the same web application). A specified maximum size is requested. It must be noted that when setting the maximum size, a number of bytes equal to the maximum size will be allocated in memory to this file upload even if the actual size of the file uploaded may be considerably smaller.

Parameters:
maxSize - Maximum size allowable in kilobytes for ALL files. The lowest maximum size value is used if multiple maximum sizes exist(via multiple targeting) for the same file.
Since:
1.0

getFileUpload

public XloadFileUpload getFileUpload(java.lang.String paramName)
Gets an object that corresponds to a single file upload attempt. The paramName is a parameter name inside the intial request that corresponds to this file upload. This file upload object may contain many file deployments for the file that has been uploaded whether they are to memory or to disk.

Parameters:
paramName - Parameter name inside the request that corresponds to this file upload.
Returns:
XloadFileUpload object that contains all the file deployments for this file upload. Can also return an XloadFileUpload object that was an upload failure due to one of the five stated reasons. Returns null if the file parameter has no targeting, or if the file parameter does not exist within the request (which maybe due to a partial upload).
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadNullArgumentException - Thrown if paramName is null.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
Since:
1.0

getAnyFile

public XloadFile getAnyFile(java.lang.String dir,
                            java.lang.String fileName)
                     throws javax.servlet.ServletException
Gets access to a file that is designated by a given directory and filename. This method can be called at anytime and can be used to retrieve any file on the file system, permissions allowed. It does not have to retrieve a recent file deployment but may do if the programmer chooses.

Parameters:
dir - Directory as a String that the file is in. Can be relative or absolute (must be absolute if using XloadManager() constructor. See introduction of this class for an explanation.
fileName - Name of the file to be retrieved.
Returns:
Returns an XloadFile object that represents the file on the file system. This maybe a file deployment or a file that was already on the file system.(See introduction for an explanation of what a file deployment is).
Throws:
javax.servlet.ServletException - Thrown if the directory path dir has conversion problems.
XloadNullArgumentException - Thrown if dir or fileName are null.
java.lang.SecurityException - Thrown if there is a problem accessing the directory on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

getFile

public XloadFile getFile(java.lang.String paramName,
                         java.lang.String dir)
                  throws javax.servlet.ServletException
Gets access to the first file deployment from the list, in the designated directory dir for a file upload designated on the client side by paramName. The file deployments are written and listed in the order that they are targeted for each parameter. The list is a FIFO (First In First Out) list.

Parameters:
paramName - Parameter name inside the request that corresponds to a file upload.
dir - Directory to look inside for file deployments.
Returns:
Returns first XloadFile object representing a file inside the designated directory that is a file deployment from a single file upload designated on the client side by the paramName. Returns null if there is no such file deployment because the file parameter has no targeting, or if the file parameter does not exist within the request (which maybe due to a partial upload).
Throws:
javax.servlet.ServletException - Thrown if there are path conversion problems with dir.
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadNullArgumentException - Thrown if paramName or dir are null.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
java.lang.SecurityException - Thrown if there is a problem accessing the directory or files on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

getFile

public XloadFile getFile(java.lang.String paramName)
Gets access to the first file deployment from the list, for a file upload designated on the client side by paramName. The file deployments are written and listed in the order that they are targeted for each parameter. The list is a FIFO (First In First Out) list. If a file deployment in memory exists it is always placed at the first position in the FIFO list and therefore always returned with this method.

Parameters:
paramName - Parameter name inside request that corresponds to a file upload.
Returns:
Returns first XloadFile object that represents a file deployment from a single file upload designated on the client side by the paramName. Returns null if there is no such file deployment because the file parameter has no targeting, or if the file parameter does not exist within the request (which maybe due to a partial upload).
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadNullArgumentException - Thrown if paramName or dir are null.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
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(java.lang.String paramName,
                         XloadDirectory dir)
                  throws javax.servlet.ServletException
Gets access to the first file deployment from the list, in designated directory dir for a file upload designated on the client side by paramName. The file deployments are written and listed in the order that they are targetted for each parameter. The list is a FIFO (First In First Out) list.

Parameters:
paramName - Parameter name inside request that corresponds to a file upload.
dir - XloadDirectory to look inside for file deployment.
Returns:
Returns first XloadFile instance inside the designated directory that is a file deployment from a single file upload designated on the client side by the paramName. Returns null if there is no such file deployment because the file parameter has no targeting, or if the file parameter does not exist within the request (which maybe due to a partial upload).
Throws:
javax.servlet.ServletException - Thrown if there are path conversion problems with dir.
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadNullArgumentException - Thrown if paramName or dir are null.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
java.lang.SecurityException - Thrown if there is a problem accessing the directory or files on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

hasMultipleTargets

public boolean hasMultipleTargets(java.lang.String paramName)
Informs whether or not at anytime there is more than one target for the file upload designated on the client side by the paramName. Even if the paramName is not a file parameter contained in the request, this method will still check whether or not there is more than one target for the parameter. This method includes targeting provided by the targetAll and targetEverything family of methods.

Parameters:
paramName - Parameter name that may or may not reside in the request as a file parameter.
Returns:
true if > 1 targets exist, false otherwise. This method will return different boolean states depending upon when it is called, for example when in the middle of setting different targets.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadNullArgumentException - Thrown if paramName is null.
Since:
1.0

anyRenamed

public boolean anyRenamed()
Informs whether or not any files that have been written to disk were renamed via the installed rename startegy due to naming clashes.

Returns:
true if any files were renamed, false otherwise.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
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()
Gets a list of file deployments that have been written to disk and were renamed via the installed rename startegy due to naming clashes.

Returns:
An immutable List containing all the file deployments as XloadFile instances that were renamed. The order of the list is undetermined.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
java.lang.SecurityException - Thrown if there is a problem accessing the files on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

hasPartialUploadOccurred

public boolean hasPartialUploadOccurred()
Indicates whether or not a partial upload has occurred.

Returns:
Returns true if a partial upload has occurred. false otherwise.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
Since:
1.0

getParameter

public java.lang.String getParameter(java.lang.String paramName)
Returns the value of a request parameter as a String, or null if the parameter does not exist. Request parameters are extra information sent with the request and are separate from file parameters that contain file data. These parameters are contained as posted form data. You should only use this method when you are sure the parameter has only one value. If the parameter might have more than one value, use getParameterValues(java.lang.String).

If you use this method with a multivalued parameter, the value returned is equal to the first value in the array returned by getParameterValues.

Parameters:
paramName - Parameter name in request.
Returns:
String value associated with this parameter name.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadNullArgumentException - Thrown if paramName is null.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
Since:
1.0

getParameterValues

public java.lang.String[] getParameterValues(java.lang.String paramName)
Returns an array of String objects containing all of the values for the given request parameter paramName, or null if the parameter does not exist. If the parameter has a single value, the array has a length of 1.

Parameters:
paramName - Parameter name in request.
Returns:
An array of String objects associated with this parameter name.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadNullArgumentException - Thrown if paramName is null.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
Since:
1.0

getParameterMap

public java.util.Map getParameterMap()
Returns a Map of the parameters of this request. File parameters are not included. Request parameters are extra information sent with the request.

Returns:
An immutable Map containing parameter names as keys and parameter values as map values. The keys in the parameter map are of type String. The values in the parameter map are of type String array. Xload includes all parameters whether embedded in the body of the request and parameters in the query string.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
Since:
1.0

getParameterNames

public java.util.Enumeration getParameterNames()
Returns an Enumeration of String objects containing the names of the parameters contained in this request. File parameters are not included. If the request contains no parameters or just file parameters, the method returns an empty Enumeration.

Returns:
An Enumeration of String objects, each String containing the name of a request parameter; or an empty Enumeration if the request contains no parameters or just file parameters.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
Since:
1.0

getFileParameterNames

public java.util.List getFileParameterNames()
Returns an immutable List of all the parameter names which are of type 'file'.

Returns:
An immutable List containing file parameter names only.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
Since:
1.0

setMIMETypes

public void setMIMETypes(java.lang.String paramName,
                         java.lang.String[] mimes)
Sets allowable MIME types for a particular file upload designated on the client side by paramName. Once set by this method the only allowable MIME types will be the ones set by this method. This method can be called multiple times for a particular paramName. If this method is not called for a particular parameter then ALL MIME types are allowable.

Parameters:
paramName - Parameter name inside the request that corresponds to a file upload.
mimes - String array of mime types that are allowable.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadNullArgumentException - Thrown if paramName or mimes are null.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
Since:
1.0

getAttemptedTargetUploads

public java.util.List getAttemptedTargetUploads()
Returns an immutable List containing all the file uploads (represented as XloadFileUpload objects) that were attempted irrespective of the outcome (success or failure).

Returns:
Immutable List containing all attempted file uploads. An empty List is returned if no file uploads were attempted.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
Since:
1.0

getSuccessfulFileUploads

public java.util.List getSuccessfulFileUploads()
Returns an immutable List containing all the file uploads (represented as XloadFileUpload objects) that were successful.

Returns:
Immutable List containing all successful file uploads. An empty List is returned if no file uploads were successful.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
Since:
1.0

getFailedFileUploads

public java.util.List getFailedFileUploads()
Returns an immutable List containing all the file uploads (represented as XloadFileUpload objects) that were attempted but failed.

Returns:
Immutable List containing all failed file uploads. An empty List is returned if no file uploads have failed.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
Since:
1.0

getRedundantTargetUploads

public java.util.List getRedundantTargetUploads()
Returns an immutable List containing all the potential file uploads (represented as XloadFileUpload objects) that were NOT attempted. Specific targeting (NOT using targetAll or targetEverything methods) existed for these uploads but no files with matching parameter names existed in the request.

Returns:
Immutable List containing all file uploads that were NOT attempted. An empty List is returned if all file uploads were attempted.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
Since:
1.0

getMemoryFile

public XloadFile getMemoryFile(java.lang.String paramName)
                        throws javax.servlet.ServletException
Returns an XloadFile that represents a file deployment to memory for the file upload designated on the client side by paramName.

Parameters:
paramName - Parameter name inside request that corresponds to a file upload.
Returns:
Returns an XloadFile that represents a memory load or null if one does not exist.
Throws:
javax.servlet.ServletException - Thrown if paramName does not appear as a file parameter in the initial request.
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadNullArgumentException - Thrown if paramName or dir are null.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
Since:
1.0

directoryExists

public boolean directoryExists(java.lang.String dir)
                        throws javax.servlet.ServletException
Indicates whether or not a directory exists on the file system designated by the parameter dir.

Parameters:
dir - Directory path to test for existence. Can be relative or absolute (must be absolute if using XloadManager() constructor. See introduction of this class for an explanation.
Returns:
Returns true if the directory exists, false otherwise.
Throws:
XloadNullArgumentException - Thrown if dir is null.
javax.servlet.ServletException - Thrown if path conversion problems occur.
java.lang.SecurityException - Thrown if there is a problem accessing the directory on the file system with regard to permissions set by the SecurityManager.
Since:
1.1

getDirectory

public XloadDirectory getDirectory(java.lang.String dir)
                            throws javax.servlet.ServletException
Returns an XloadDirectory representing a directory on the file system given a path dir.

Parameters:
dir - Path to directory as a String. Can be relative or absolute (must be absolute if using XloadManager() constructor. See introduction of this class for an explanation.
Returns:
An XloadDirectory instance or null if the directory does not exist.
Throws:
javax.servlet.ServletException - Thrown if path conversion problems occur.
XloadNullArgumentException - Thrown if dir is null.
java.lang.SecurityException - Thrown if there is a problem accessing the directory on the file system with regard to permissions set by the SecurityManager.
Since:
1.1

createDirectory

public XloadDirectory createDirectory(java.lang.String dir,
                                      java.lang.String newDir)
                               throws java.io.IOException,
                                      javax.servlet.ServletException
Creates a directory in the appropriate directory and returns an XloadDirectory instance. If the directory already exists then this directory is returned.

Parameters:
dir - Directory to create the new directory in. Can be relative or absolute (must be absolute if using XloadManager() constructor. See introduction of this class for an explanation.
newDir - New directory name.
Returns:
XloadDirectory instance representing the new directory.
Throws:
javax.servlet.ServletException - Thrown if path conversion problems occur or if dir is not a valid directory.
java.io.IOException - Thrown if the new directory cannot be created for some reason such as an incorrect system dependant naming convention or access permission restrictions (not though if the new directory already exists).
XloadNullArgumentException - Thrown if dir or newDir is null.
java.lang.SecurityException - Thrown if there is a problem accessing the directory on the file system with regard to permissions set by the SecurityManager.
Since:
1.1

deleteAll

public boolean deleteAll()
Deletes all files associated with the upload performed by this XloadManager object. Any file deployment that was made by the calling of the upload() method of this instance will be deleted by this method. Also, any files that are copied from the original uploaded files will be deleted. If files are moved they too will be deleted.

Returns:
Indicates whether all files have been deleted or not, true if they have, false otherwise.
Throws:
XloadRequestNullException - Thrown if working with an XloadManager created from its default constructor.
XloadUploadException - Thrown if calling this method before calling upload() which is semantically incorrect.
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

setKeyCode

public static void setKeyCode(java.lang.String code,
                              java.lang.String details)
Allows the setting of a KeyCode and User Details that turns this evaluation version into a full version.

When this method is called once for a particular machine, then permissions allowed, these credentials are stored in the backing store therefore not requiring any further calls to this method for the life of the backing store.

If for some reason the backing store is unavailable and this method has been called on a particular machine then Xload will revert to being a trial version and stop working after 15 minutes. To solve this, this method needs to be called at least once within the life of a vm or more specifially for each web application (as each application will probably use different class loaders). So for example a call could be made to this method in some application scope JavaBean component that you know will be loaded before Xload is used, or alternatively in some Servlet that is loaded when the application starts (i.e. with a 'load-on-startup' order). alternatively the programmer could call this method upon each usage of Xload with a slight detriment to performance.

Parameters:
code - KeyCode exactly as supplied for use.
details - User details which will include email address and either user name or user organisation (NOT case sensitive). To be written in the format: email@mydomain.com_my_organisation.
Since:
1.0

getProgressData

public XloadProgressData getProgressData()
Gets progress data for a particular upload.

Since:
1.2