|
|||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||
java.lang.Objectcom.gubutech.xload.XloadFile
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.
| 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 |
public abstract boolean isMemoryFile()
true if this is a memory load, false otherwise.public abstract boolean isDiskFile()
file deployment or an ordinary file on the system.
true if this is a file written on disk, false otherwise.public abstract java.lang.String getWrittenName()
null otherwise.public abstract java.lang.String getTargetName()
targetName for this file (see the introduction for this class, specifically the DEFINITIONS section for further information).
targetName.public abstract java.lang.String getRemoteName()
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).
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.
public abstract XloadFile copyTo(java.lang.String dir)
throws javax.servlet.ServletException,
java.io.IOException
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.
dir - Directory to copy this file to.
XloadFile that now exists in the new directory as a new object.
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.
public abstract XloadFile copyTo(XloadDirectory dir)
throws javax.servlet.ServletException,
java.io.IOException
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.
dir - Directory to copy this file to as an XloadDirectory object.
XloadFile that now exists in the new directory as a new object.
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.
public abstract XloadFile moveTo(java.lang.String dir)
throws javax.servlet.ServletException,
java.io.IOException
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.
dir - Directory to move this file to as a String object.
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.
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.
public abstract XloadFile moveTo(XloadDirectory dir)
throws javax.servlet.ServletException,
java.io.IOException
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.
dir - Directory to copy this file to as an XloadDirectory object.
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.
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.public abstract boolean delete()
delete in interface XloadDirectoryItemtrue 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.
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.public abstract java.lang.String getRequestParameter()
HttpServletRequest parameter name for the file upload associated with this XloadFile object.
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.public abstract boolean renameTo(java.lang.String name)
XloadFile object in the same directory.
name - The name used to rename the file with.
true if the file has been renamed successfully, false otherwise (i.e. another file with the same name
exists within the directory).
XloadNullArgumentException - Thrown if the parameter name is null.
java.lang.UnsupportedOperationException - Thrown if this is an instance representing a memory loaded file.public abstract void resetTargetName(java.lang.String name)
targetName for this XloadFile object. See the introduction section of this class for a more detailed
explanation of the targetName parameter.
name - The name used to reset the targetName parameter. After calling this method the targetName will become this
value.
XloadNullArgumentException - Thrown if name is null.public abstract XloadFileUpload getFileUpload()
XloadFileUpload instance.
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).public abstract XloadManager getManager()
XloadManager object (i.e.the XloadManager object that this object was created from).
XloadManager object.public abstract XloadDirectory getDirectory()
XloadDirectory object that represents this objects parent directory.
null if one does not exist (i.e. this object represents a memory loaded file).public abstract boolean uploaded()
file deployment and has been recently uploaded.
true if this object is a file deployment and has been recently uploaded,
false otherwise.public abstract java.lang.String getMIMEType()
file deployment.
null (i.e. this object represents an ordinary file on the file system).public abstract long getSize()
public java.lang.String getConvertedSize(java.lang.String byteString,
java.lang.String kbString,
java.lang.String mbString,
java.lang.String gbString)
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.
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.
String value representing the file size.public abstract boolean isFile()
XloadDirectoryItem objects.
isFile in interface XloadDirectoryItemtrue if the file represented by this object exists, false otherwise.XloadDirectory.hasMore(),
XloadDirectory.getNext()public abstract boolean isDirectory()
XloadDirectoryItem objects.
isDirectory in interface XloadDirectoryItemfalseXloadDirectory.hasMore(),
XloadDirectory.getNext()public abstract boolean exists()
exists in interface XloadDirectoryItemtrue if the file exists, false otherwise.
java.lang.SecurityException - Thrown if there is a problem accessing the file on the file system with regard to permissions
set by the SecurityManager.public boolean equals(java.lang.Object o)
XloadFile object and represents the same file
as this object does.
equals in interface XloadDirectoryItemo - Object to be tested for equality.
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)
java.lang.SecurityException - Thrown if there is a problem accessing the directories on the file system with regard to permissions
set by the SecurityManager.public abstract byte[] getBytes()
java.lang.UnsupportedOperationException - Thrown if this method is called from an XloadFile object that represents
any disk based file.public abstract java.io.FileInputStream getFileInputStream()
FileInputStream connected to a this objects represented disk file or null if one does not exist.
java.lang.UnsupportedOperationException - Thrown if this method is called from an XloadFile object that represents a memory loaded file.public boolean isRenamed()
true if this objects represented file has been renamed, false otherwise.public boolean isDeleted()
isDeleted in interface XloadDirectoryItemtrue if this file has been deleted, false otherwise.public abstract boolean isFileDeployment()
file deployment or not.
true if this file is a file deployment, false otherwise.
|
|||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||