com.gubutech.xload
Class XloadFile

java.lang.Object
  extended bycom.gubutech.xload.XloadFile
All Implemented Interfaces:
XloadDirectoryItem

public abstract class XloadFile
extends java.lang.Object
implements XloadDirectoryItem

Class that represents all types of file deployments and can represent any file on the file system (including a network).

This class represents an actual file on the file system or in memory depending on the nature of the underlying file. Information about this file can be learned using appropriate methods. The file can also be manipulated in a number of ways including renaming, moving or copying.

Please read Introduction documentation of class XloadManager for a discussion on file deployments before continuing.

DEFINITIONS:

1. remoteName: This is the name of the file before an upload, as it was on the client machine. A copy of a file deployment has the same remoteName as the file deployment it was copied from. In the case of an XloadFile object that represents an ordinary file on the file system, that has not just been uploaded, its remoteName will be null.

2. writtenName: This is the actual name of the file on disk. In the case of a memory loaded file this is null.

3. targetName: This is the name associated with an XloadFile object that will be used when creating a file on disk, by carrying out a move or copy operation. A memory loaded file deployment has its targetName set to its remoteName. When a file is written to disk its targetName is set to its writtenName. By default, when a disk file has its writtenName altered the targetName is set to the new value. The targetName can however be changed to whatever the programmer desires at anytime using the resetTargetName(java.lang.String) method giving full control of this mechanism if required so that a new file name can be created for a copied/moved file. Once the resetTargetName(String) method is called however, any alteration of the writtenName will not affect the targetName.

RENAMING DEFINITION:

A file deployment on disk that is NOT a copy is said to have been renamed if its writtenName is in anyway different to its remoteName. A memory loaded file deployment cannot be deemed to be renamed as it is not written to disk. An ordinary (or arbitrary) file on disk not associated with any recent upload is considered renamed if its writtenName is different to its writtenName when the XloadFile object representing it was created. In the case of a copy of any type of file, the copy is deemed to be renamed if its current writtenName is different to its writtenName when the XloadFile object representing it was created, even though its remoteName(in the case of a file deployment) maybe the same as the current writtenName.

MISCELLANEOUS:

If an XloadFile object originated from an XloadManager object that was created using its default constructor then all paths must be absolute, otherwise if the XloadFile object was created from an XloadManager object that was not created using its default constructor paths can be absolute or relative (see XloadManager for a further explanation on relative and absolute paths).

XloadFile objects can be accessed in certain ways:

A java.io.FileInputStream can be created from any file that is on disk by using an XloadFile object. This can then be used to read the file and perform tasks with it such as writing the file to a Database containing it in a BLOB field type. A memory loaded file that is represented by an XloadFile object can be accessed directly by retrieving a byte[] that is held in memory using the getBytes() method.

Since:
1.0

Method Summary
abstract  XloadFile copyTo(java.lang.String dir)
          Copies this file to another directory.
abstract  XloadFile copyTo(XloadDirectory dir)
          Copies this file to another directory.
abstract  boolean delete()
          Deletes this file.
 boolean equals(java.lang.Object o)
          Determines whether or not an object passed as a parameter is an XloadFile object and represents the same file as this object does.
abstract  boolean exists()
          Determines whether or not the file represented by this object actually exists or not.
abstract  byte[] getBytes()
          Retrieves a byte array containing the files bytes.
 java.lang.String getConvertedSize(java.lang.String byteString, java.lang.String kbString, java.lang.String mbString, java.lang.String gbString)
          Retrieves the size of this file as a converted String value.
abstract  XloadDirectory getDirectory()
          Retrieves an XloadDirectory object that represents this objects parent directory.
abstract  java.io.FileInputStream getFileInputStream()
          Retrieves an input stream that is connected to this objects file on disk.
abstract  XloadFileUpload getFileUpload()
          Retrieves this objects appropriate XloadFileUpload instance.
abstract  XloadManager getManager()
          Retrieves this objects associated XloadManager object (i.e.the XloadManager object that this object was created from).
abstract  java.lang.String getMIMEType()
          Retrieves the MIME type of this object if this object is a file deployment.
abstract  java.lang.String getRemoteName()
          Retrieves the original file name (remoteName) as it was on the client (usually a browser) before the file was uploaded (see the introduction for this class, specifically the DEFINITIONS section for further information).
abstract  java.lang.String getRequestParameter()
          Retrieves the HttpServletRequest parameter name for the file upload associated with this XloadFile object.
abstract  long getSize()
          Retrieves the size of this file.
abstract  java.lang.String getTargetName()
          Retrieves the targetName for this file (see the introduction for this class, specifically the DEFINITIONS section for further information).
abstract  java.lang.String getWrittenName()
          Retrieves the actual name on disk for the file represented by this object if and only if it represents a file written to disk (see the introduction for this class, specifically the DEFINITIONS section for further information).
 boolean isDeleted()
          Determines whether or not this file has been deleted or not.
abstract  boolean isDirectory()
          Determines whether this object represents a directory as opposed to a file.
abstract  boolean isDiskFile()
          Determines whether or not this object represents a file on disk whether it is a file deployment or an ordinary file on the system.
abstract  boolean isFile()
          Determines whether this object represents a file as opposed to a directory.
abstract  boolean isFileDeployment()
          Determines whether or not this file is a file deployment or not.
abstract  boolean isMemoryFile()
          Determines whether or not this object represents a memory loaded file or not.
 boolean isRenamed()
          Determines if this file has been renamed.
abstract  XloadFile moveTo(java.lang.String dir)
          Moves this file to a directory.
abstract  XloadFile moveTo(XloadDirectory dir)
          Moves this file to a directory.
abstract  boolean renameTo(java.lang.String name)
          Renames, on disk, the file represented by this XloadFile object in the same directory.
abstract  void resetTargetName(java.lang.String name)
          Resets the targetName for this XloadFile object.
abstract  boolean uploaded()
          Determines whether or not this object is a file deployment and has been recently uploaded.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

isMemoryFile

public abstract boolean isMemoryFile()
Determines whether or not this object represents a memory loaded file or not.

Returns:
Returns true if this is a memory load, false otherwise.
Since:
1.0

isDiskFile

public abstract boolean isDiskFile()
Determines whether or not this object represents a file on disk whether it is a file deployment or an ordinary file on the system.

Returns:
Returns true if this is a file written on disk, false otherwise.
Since:
1.0

getWrittenName

public abstract java.lang.String getWrittenName()
Retrieves the actual name on disk for the file represented by this object if and only if it represents a file written to disk (see the introduction for this class, specifically the DEFINITIONS section for further information).

Returns:
Returns the written file name if it is written to disk, null otherwise.
Since:
1.0

getTargetName

public abstract java.lang.String getTargetName()
Retrieves the targetName for this file (see the introduction for this class, specifically the DEFINITIONS section for further information).

Returns:
Returns the current targetName.
Since:
1.0

getRemoteName

public abstract java.lang.String getRemoteName()
Retrieves the original file name (remoteName) as it was on the client (usually a browser) before the file was uploaded (see the introduction for this class, specifically the DEFINITIONS section for further information).

Returns:
Returns the remoteName of this file before an upload, if this file is a file deployment. Returns null if the file field was empty at the client. Also returns null if this file was not recently uploaded and is just an ordinary file on the system.
Since:
1.0

copyTo

public abstract XloadFile copyTo(java.lang.String dir)
                          throws javax.servlet.ServletException,
                                 java.io.IOException
Copies this file to another directory. If the file being copied is a file deployment then the new file created (in the directory dir) will be a new file deployment and added to the list of file deployments accordingly for the original file upload. See XloadFileUpload for a full description of file deployment ordering and storage.

Parameters:
dir - Directory to copy this file to.
Returns:
Returns the XloadFile that now exists in the new directory as a new object.
Throws:
javax.servlet.ServletException - Thrown if the file being copied has been deleted OR the directory given is not actually a directory OR if there is a file with exactly the same name as the targetName of this file, in the directory dir given (i.e. there is a name clash). Please note that a further exception (XloadFileException) can be thrown which is a subclass of ServletException if a file name clash just described occurs. This can give the programmer fine control over failure conditions if required.
java.io.IOException - Thrown if some IO Error occurs while copying the file.
XloadNullArgumentException - Thrown if dir is null.
java.lang.SecurityException - Thrown if a there is a problem accessing the directory on the file system with regard to permissions set by any existing SecurityManager.
Since:
1.0

copyTo

public abstract XloadFile copyTo(XloadDirectory dir)
                          throws javax.servlet.ServletException,
                                 java.io.IOException
Copies this file to another directory. If the file being copied is a file deployment then the new file created (in the directory dir) will be a new file deployment and added to the list of file deployments accordingly for the original file upload. See XloadFileUpload for a full description of file deployment ordering and storage.

Parameters:
dir - Directory to copy this file to as an XloadDirectory object.
Returns:
Returns the XloadFile that now exists in the new directory as a new object.
Throws:
javax.servlet.ServletException - Thrown if the file being copied has been deleted OR the directory given is not actually a directory OR if there is a file with exactly the same name as the targetName of this file, in the directory dir given (i.e. there is a name clash). Please note that a further exception (XloadFileException) can be thrown which is a subclass of ServletException if a file name clash just described occurs. This can give the programmer fine control over failure conditions if required.
java.io.IOException - Thrown if some IO Error occurs while copying the file.
XloadNullArgumentException - Thrown if dir is null.
java.lang.SecurityException - Thrown if a there is a problem accessing the directory on the file system with regard to permissions set by any existing SecurityManager.
Since:
1.0

moveTo

public abstract XloadFile moveTo(java.lang.String dir)
                          throws javax.servlet.ServletException,
                                 java.io.IOException
Moves this file to a directory. If this object represents a memory file deployment then a new XloadFile object is returned which represents this objects file on disk. This new object is then added to the list of file deployments at the end of the FIFO list. The original XloadFile instance representing the memory load is then deleted. Alternatively, if the file being moved is a disk based file then this objects state is left intact and only the location of the file on disk is altered. See XloadFileUpload for a full description of file deployment ordering and storage.

Parameters:
dir - Directory to move this file to as a String object.
Returns:
If this object is a memory loaded file then this method returns a new XloadFile object representing the new file on the file system. This new XloadFile object will be added to the list of file deployments accordingly. If this object represents a file on disk then this method returns null and no objects are added to the list of file deployments.
Throws:
javax.servlet.ServletException - Thrown if the file being moved has been deleted OR the directory given is not actually a directory OR if there is a file with exactly the same name as the targetName of this file, in the directory dir given (i.e. there is a name clash). Please note that a further exception (XloadFileException) can be thrown which is a subclass of ServletException if a file name clash just described occurs. This can give the programmer fine control over failure conditions if required.
java.io.IOException - Thrown if there is a problem accessing the directory (this may be due to system access permission restrictions).
XloadNullArgumentException - Thrown if dir is null.
java.lang.SecurityException - Thrown if a there is a problem accessing the directory on the file system with regard to permissions set by any existing SecurityManager.
Since:
1.0

moveTo

public abstract XloadFile moveTo(XloadDirectory dir)
                          throws javax.servlet.ServletException,
                                 java.io.IOException
Moves this file to a directory. If this object represents a memory file deployment then a new XloadFile object is returned which represents this objects file on disk. This new object is then added to the list of file deployments at the end of the FIFO list. The original XloadFile instance representing the memory load is then deleted. Alternatively, if the file being moved is a disk based file then this objects state is left intact and only the location of the file on disk is altered. See XloadFileUpload for a full description of file deployment ordering and storage.

Parameters:
dir - Directory to copy this file to as an XloadDirectory object.
Returns:
If this object is a memory loaded file then this method returns a new XloadFile object representing the new file on the file system. This new XloadFile object will be added to the list of file deployments accordingly. If this object represents a file on disk then this method returns null and no objects are added to the list of file deployments.
Throws:
javax.servlet.ServletException - Thrown if the file being moved has been deleted OR the directory given is not actually a directory OR if there is a file with exactly the same name as the targetName of this file, in the directory dir given (i.e. there is a name clash). Please note that a further exception (XloadFileException) can be thrown which is a subclass of ServletException if a file name clash just described occurs. This can give the programmer fine control over failure conditions if required.
java.io.IOException - Thrown if there is a problem accessing the directory (this may be due to system access permission restrictions).
XloadNullArgumentException - Thrown if dir is null.
java.lang.SecurityException - Thrown if a there is a problem accessing the directory on the file system with regard to permissions set by any existing SecurityManager.
Since:
1.0

delete

public abstract boolean delete()
Deletes this file.

Specified by:
delete in interface XloadDirectoryItem
Returns:
Returns true if this objects file has been successfully deleted and false if this objects file cannot be deleted, which maybe due to operating system access permissions.
Throws:
java.lang.SecurityException - Thrown if a there is a problem accessing the underlying file on the file system with regard to permissions set by any existing SecurityManager.
Since:
1.0

getRequestParameter

public abstract java.lang.String getRequestParameter()
Retrieves the HttpServletRequest parameter name for the file upload associated with this XloadFile object.

Returns:
Returns the request parameter associated with this XloadFile object or null if one does not exist (i.e. this object is not a file deployment and represents a an ordinary file on the file system.
Since:
1.0

renameTo

public abstract boolean renameTo(java.lang.String name)
Renames, on disk, the file represented by this XloadFile object in the same directory.

Parameters:
name - The name used to rename the file with.
Returns:
Returns true if the file has been renamed successfully, false otherwise (i.e. another file with the same name exists within the directory).
Throws:
XloadNullArgumentException - Thrown if the parameter name is null.
java.lang.UnsupportedOperationException - Thrown if this is an instance representing a memory loaded file.
Since:
1.0

resetTargetName

public abstract void resetTargetName(java.lang.String name)
Resets the targetName for this XloadFile object. See the introduction section of this class for a more detailed explanation of the targetName parameter.

Parameters:
name - The name used to reset the targetName parameter. After calling this method the targetName will become this value.
Throws:
XloadNullArgumentException - Thrown if name is null.
Since:
1.0

getFileUpload

public abstract XloadFileUpload getFileUpload()
Retrieves this objects appropriate XloadFileUpload instance.

Returns:
Returns this objects associated XloadFileUpload object or null if one does not exist (i.e. this object represents an ordinary file on the system and is not a file deployment).
Since:
1.0

getManager

public abstract XloadManager getManager()
Retrieves this objects associated XloadManager object (i.e.the XloadManager object that this object was created from).

Returns:
Returns this objects XloadManager object.
Since:
1.0

getDirectory

public abstract XloadDirectory getDirectory()
Retrieves an XloadDirectory object that represents this objects parent directory.

Returns:
Returns this objects parent dirctory or null if one does not exist (i.e. this object represents a memory loaded file).
Since:
1.1

uploaded

public abstract boolean uploaded()
Determines whether or not this object is a file deployment and has been recently uploaded.

Returns:
Returns true if this object is a file deployment and has been recently uploaded, false otherwise.
Since:
1.0

getMIMEType

public abstract java.lang.String getMIMEType()
Retrieves the MIME type of this object if this object is a file deployment.

Returns:
Returns the MIME type string that was sent with this objects associated file upload. If this object is not associated with a file upload then this method returns null (i.e. this object represents an ordinary file on the file system).
Since:
1.0

getSize

public abstract long getSize()
Retrieves the size of this file.

Returns:
Returns the size of the file in bytes.
Since:
1.0

getConvertedSize

public java.lang.String getConvertedSize(java.lang.String byteString,
                                         java.lang.String kbString,
                                         java.lang.String mbString,
                                         java.lang.String gbString)
Retrieves the size of this file as a converted String value. The resulting value will be a number to one decimal place (if required) followed by a String representing the appropriate size (i.e. "byte(s)", "kb", "mb" and "gb"). You can customize these appropriate size Strings by inserting another String value using the appropriate parameter.

Parameters:
byteString - String value used to describe a number of bytes for the file size. If this parameter is null then a default String of "byte(s)" is used.
kbString - String value used to describe a number of kilobytes for the file size. If this parameter is null then a default String of "kb" is used.
mbString - String value used to describe a number of megabytes for the file size. If this parameter is null then a default String of "mb" is used.
gbString - String value used to describe a number of gigabytes for the file size. If this parameter is null then a default String of "gb" is used.
Returns:
Returns the appropriate String value representing the file size.
Since:
1.0

isFile

public abstract boolean isFile()
Determines whether this object represents a file as opposed to a directory. This method is available so that it can be used when iterating through a list of XloadDirectoryItem objects.

Specified by:
isFile in interface XloadDirectoryItem
Returns:
Returns true if the file represented by this object exists, false otherwise.
Since:
1.1
See Also:
XloadDirectory.hasMore(), XloadDirectory.getNext()

isDirectory

public abstract boolean isDirectory()
Determines whether this object represents a directory as opposed to a file. This method is available so that it can be used when iterating through a list of XloadDirectoryItem objects.

Specified by:
isDirectory in interface XloadDirectoryItem
Returns:
Always returns false
Since:
1.1
See Also:
XloadDirectory.hasMore(), XloadDirectory.getNext()

exists

public abstract boolean exists()
Determines whether or not the file represented by this object actually exists or not.

Specified by:
exists in interface XloadDirectoryItem
Returns:
Returns true if the file exists, false otherwise.
Throws:
java.lang.SecurityException - Thrown if there is a problem accessing the file on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

equals

public boolean equals(java.lang.Object o)
Determines whether or not an object passed as a parameter is an XloadFile object and represents the same file as this object does.

Specified by:
equals in interface XloadDirectoryItem
Parameters:
o - Object to be tested for equality.
Returns:
Returns true if this object is equal to the object represented by the parameter o, false otherwise; o is only equal, if and only if, it is an instance of XloadFile and it represents exactly the same file on the file system, as this objects represented file such that -

this.file.equals(o.file) (where file is of type java.io.File)

In the case of a memory based file then the two objects are tested for equality using the default equals() method, provided by the object Object and are equal such that -

super.equals(o)

Throws:
java.lang.SecurityException - Thrown if there is a problem accessing the directories on the file system with regard to permissions set by the SecurityManager.
Since:
1.0

getBytes

public abstract byte[] getBytes()
Retrieves a byte array containing the files bytes. This method is used in conjunction with memory loaded files only.

Returns:
Returns a byte [] containing memory loaded file bytes.
Throws:
java.lang.UnsupportedOperationException - Thrown if this method is called from an XloadFile object that represents any disk based file.
Since:
1.0

getFileInputStream

public abstract java.io.FileInputStream getFileInputStream()
Retrieves an input stream that is connected to this objects file on disk. Allows the programmer to wrap this basic stream as they wish and then read the contents of the file to perform an arbitrary task. This method is used with disk based files only.

Returns:
Returns a FileInputStream connected to a this objects represented disk file or null if one does not exist.
Throws:
java.lang.UnsupportedOperationException - Thrown if this method is called from an XloadFile object that represents a memory loaded file.
Since:
1.0

isRenamed

public boolean isRenamed()
Determines if this file has been renamed. Please see the Introduction section of this class, specifically the RENAMING DEFINITION section to see what determines whether or not a file has been renamed.

Returns:
Returns true if this objects represented file has been renamed, false otherwise.
Since:
1.0

isDeleted

public boolean isDeleted()
Determines whether or not this file has been deleted or not.

Specified by:
isDeleted in interface XloadDirectoryItem
Returns:
Returns true if this file has been deleted, false otherwise.
Since:
1.0

isFileDeployment

public abstract boolean isFileDeployment()
Determines whether or not this file is a file deployment or not.

Returns:
Returns true if this file is a file deployment, false otherwise.
Since:
1.0