|
|||||||||||
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 XloadDirectoryItem
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.
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 XloadDirectoryItem
true
if the file represented by this object exists, false
otherwise.XloadDirectory.hasMore()
,
XloadDirectory.getNext()
public abstract boolean isDirectory()
XloadDirectoryItem
objects.
isDirectory
in interface XloadDirectoryItem
false
XloadDirectory.hasMore()
,
XloadDirectory.getNext()
public abstract boolean exists()
exists
in interface XloadDirectoryItem
true
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 XloadDirectoryItem
o
- 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 XloadDirectoryItem
true
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 |