com.gubutech.xload
Class XloadDirectory

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

public class XloadDirectory
extends java.lang.Object
implements XloadDirectoryItem

Class that represents a directory/folder on the file system.

An instance of this class represents a directory on the file system and information can be gleaned from this directory using appropriate methods. There are also a number of operations that can be performed on the represented directory.

All contained files and directories within a directory represented by an XloadDirectory object, are termed directory items.

Since:
1.1

Method Summary
 XloadDirectory createDirectory(java.lang.String direct)
          Creates a directory within the directory represented by this object.
 boolean delete()
          Deletes this objects directory (and contained files) and all sub-directories and files.
 boolean directoryExists(java.lang.String direct)
          Determines whether or not a directory exists within this objects directory or not.
 boolean equals(java.lang.Object o)
          Determines whether or not an object passed as a parameter is an XloadDirectory object and represents the same directory as this object does.
 boolean exists()
          Determines whether or not this objects directory exists or not.
 boolean fileExists(java.lang.String fileName)
          Determines whether or not a file exists within this objects directory or not.
 XloadDirectory getDirectory(java.lang.String dirName)
          Returns a directory represented as an XloadDirectory object if one exists in the directory represented by this object.
 java.lang.String getDirectoryPath()
          Returns the absolute directory path of this objects directory on the file system.
 XloadFile getFile(java.lang.String fileName)
          Returns a file represented as an XloadFile object if one exists in the directory represented by this object.
 float getMegabyteSize(boolean includeSubfolders)
          Determines the total size of files inside this objects represented directory.
 java.lang.String getName()
          Returns the name of this directory on the file system.
 XloadDirectoryItem getNext()
          Returns the next directory item in sequence depending upon the settings provided by the sortBy(int, boolean), sortBy(int), setOmmitFiles(boolean) and setOmmitDirectories(boolean) methods.
 int getSize()
          Gets the number of files and/or directories in this directory depending whether or not the programmer has specified to ommit files and/or directories in that calculation using setOmmitFiles(boolean) or setOmmitDirectories(boolean).
 boolean hasMore()
          Indicates whether or not there are any more existing directory items in this objects directory.
 boolean isDeleted()
          Determines whether or not the directory represented by this object has been deleted or not.
 boolean isDirectory()
          Determines whether or not this object represents a directory or not.
 boolean isFile()
          Determines whether or not this object represents a file or not.
 void reset()
          Resets the iteration list cursor provided by this class back to the beginning of the list for all directory items within this objects directory.
 void setOmmitDirectories(boolean b)
          When set to true, then when using certain methods, directories contained in this objects represented directory are ommitted in certain calculations.
 void setOmmitFiles(boolean b)
          When set to true, then when using certain methods, files contained in this objects represented directory are ommitted in certain calculations.
 void sortBy(int sortBy)
          Convenience method performing exactly the same function as sortBy(int sortBy, boolean ascending) with the ascending parameter set to true.
 void sortBy(int sortBy, boolean ascending)
          Sets the 'sort by' algorithm for when any iteration is performed on this object using the hasMore() and associated methods.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

isFile

public boolean isFile()
Determines whether or not this object represents a file or not. 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:
Always returns false.
Since:
1.1

isDirectory

public boolean isDirectory()
Determines whether or not this object represents a directory or not. 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:
Returns true if this objects represented directory exists, false otherwise.
Throws:
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.1

isDeleted

public boolean isDeleted()
Determines whether or not the directory represented by this object has been deleted or not.

Specified by:
isDeleted in interface XloadDirectoryItem
Returns:
Returns true if the directory represented has been deleted, false otherwise.
Throws:
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.1

createDirectory

public XloadDirectory createDirectory(java.lang.String direct)
                               throws java.io.IOException
Creates a directory within the directory represented by this object.

Parameters:
direct - The name of the new directory to be created as a String object.
Returns:
Returns an XloadDirectory object representing the new directory created (or one that already exists with the same name) or null if this objects directory does not exist.
Throws:
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.
XloadNullArgumentException - Thrown if the parameter direct is null.
java.lang.SecurityException - Thrown if a there is a problem creating the directory on the file system with regard to permissions set by any existing SecurityManager.
Since:
1.1

getMegabyteSize

public float getMegabyteSize(boolean includeSubfolders)
                      throws java.io.IOException
Determines the total size of files inside this objects represented directory.

Parameters:
includeSubfolders - boolean parameter specifying whether or not sub-folders(directories) of this objects directory should be included when computing the total size of files contained within this objects directory.
Returns:
Returns a total value of all file sizes in the chosen directories (depending on the value of the includeSubfolders parameter), in megabytes as a floating point value. This method returns zero if this objects directory has been deleted.
Throws:
java.io.IOException - Thrown if there is a problem accessing any of the directories involved in the computation. (Maybe due to access permisssion restrictions).
java.lang.SecurityException - Thrown if a there is a problem accessing the appropriate directories and/or files on the file system with regard to permissions set by any existing SecurityManager.
Since:
1.1

delete

public boolean delete()
Deletes this objects directory (and contained files) and all sub-directories and files.

Specified by:
delete in interface XloadDirectoryItem
Returns:
Returns true if this objects directory has been successfully deleted and false if this objects directory cannot be deleted, which maybe due to operating system access permissions.
Throws:
java.lang.SecurityException - Thrown if a there is a problem accessing the appropriate directories and/or files on the file system with regard to permissions set by any existing SecurityManager. Please note that if this exception is thrown then there will be some directories and/or files that are left not deleted.
Since:
1.1

getSize

public int getSize()
            throws java.io.IOException
Gets the number of files and/or directories in this directory depending whether or not the programmer has specified to ommit files and/or directories in that calculation using setOmmitFiles(boolean) or setOmmitDirectories(boolean).

Returns:
Returns the number of files and/or directories in this directory depending upon whether files and/or directories have been ommitted from that calculation. This method returns zero if this objects directory has been deleted.
Throws:
java.io.IOException - Thrown if there is a problem accessing the directory (this may be due to system access permission restrictions).
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.1

setOmmitFiles

public void setOmmitFiles(boolean b)
When set to true, then when using certain methods, files contained in this objects represented directory are ommitted in certain calculations.

Parameters:
b - boolean parameter to control whether or not files are ommitted with the use of certain methods.
Since:
1.1
See Also:
getNext(), hasMore(), reset(), getSize()

setOmmitDirectories

public void setOmmitDirectories(boolean b)
When set to true, then when using certain methods, directories contained in this objects represented directory are ommitted in certain calculations.

Parameters:
b - boolean parameter to control whether or not files are ommitted with the use of certain methods.
Since:
1.1
See Also:
getNext(), hasMore(), reset(), getSize()

getFile

public XloadFile getFile(java.lang.String fileName)
                  throws java.io.IOException
Returns a file represented as an XloadFile object if one exists in the directory represented by this object. The XloadFile object returned will represent the correct type of file on the file system for example if the file requested is a then the appropriate XloadFile instance will be returned altenatively an ordinary file will be represented.

Parameters:
fileName - Name of the file requested.
Returns:
An appropriate XloadFile instance if a file with the correct fileName exists or null if it does not exist.
Throws:
java.io.IOException - Thrown if there is a problem accessing the directory (this may be due to system access permission restrictions).
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.
XloadNullArgumentException - Thrown if the parameter fileName is null
Since:
1.1

getDirectory

public XloadDirectory getDirectory(java.lang.String dirName)
                            throws java.io.IOException
Returns a directory represented as an XloadDirectory object if one exists in the directory represented by this object.

Parameters:
dirName - Name of the directory requested.
Returns:
An appropriate XloadDirectory instance if a directory with the correct dirName exists or null if it does not exist.
Throws:
java.io.IOException - Thrown if there is a problem accessing this objects directory (this may be due to system access permission restrictions).
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.1

getName

public java.lang.String getName()
Returns the name of this directory on the file system.

Returns:
Returns the name of this objects represented directory or null if it does not exist.
Throws:
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.1

sortBy

public void sortBy(int sortBy,
                   boolean ascending)
Sets the 'sort by' algorithm for when any iteration is performed on this object using the hasMore() and associated methods.

Parameters:
sortBy - Parameter stating algorithm type. Allowable input parameters are:
1 - directory items are ordered alphabetically by their name.
2 - directory items are ordered by their size (directories for the purpose of size calculations are given a value of zero).
3 - directory items are ordered by their last modified date.
ascending - States in which order to sort the directory items, ascending(true) or descending(false).
Throws:
XloadIncorrectSortByCodeException - Thrown if an incorrect sort by code number is chosen.
Since:
1.1
See Also:
hasMore(), getNext(), reset()

sortBy

public void sortBy(int sortBy)
Convenience method performing exactly the same function as sortBy(int sortBy, boolean ascending) with the ascending parameter set to true.

Parameters:
sortBy - Parameter stating algorithm type. Allowable input parameters are:
1 - directory items are ordered alphabetically by their name.
2 - directory items are ordered by their size (directories for the purpose of size calculations are given a value of zero).
3 - directory items are ordered by their last modified date.
Throws:
XloadIncorrectSortByCodeException - Thrown if an incorrect sort by code number is chosen.
Since:
1.1
See Also:
sortBy(int, boolean), hasMore(), getNext(), reset()

hasMore

public boolean hasMore()
                throws java.io.IOException
Indicates whether or not there are any more existing directory items in this objects directory. This method works in conjunction with the getNext() method which retrieves the next element in the list and the reset() method which resets the list back to the beginning. The order of the list will depend upon the settings given by using the sortBy(int, boolean) and sortBy(int) methods. The default ordering of directory items is determined by the underlying operating system and no guarantees can be made. What is contained in the list will depend upon the settings used in the setOmmitFiles(boolean) and setOmmitDirectories(boolean) methods (e.g. if setOmmitFiles(true) is called then the list only contains directories).

If, while iterating through the list, the contents of this objects directory (or any settings) are altered in some way then this alteration will not be shown until the reset() has been called and a new list is created from the underlying directory contents. This method will not however display any fail-fast behaviour as is associated with the iterator interface if modifications do occur.

Returns:
true if there are anymore directory items in the list, false otherwise.
Throws:
java.io.IOException - Thrown if there is a problem accessing this objects directory (this may be due to system access permission restrictions).
java.lang.SecurityException - Thrown if there is a problem accessing files and/or directories on the file system with regard to permissions set by the SecurityManager.
Since:
1.1
See Also:
getNext(), reset()

reset

public void reset()
Resets the iteration list cursor provided by this class back to the beginning of the list for all directory items within this objects directory. This allows the programmer to iterate over all directory items more than once (as the cursor is always at the beginning of the list when this object is created). When this method is called, any changes or different settings will be taken into account when iterating over the list the next time.

Throws:
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
See Also:
hasMore(), getNext()

getNext

public XloadDirectoryItem getNext()
Returns the next directory item in sequence depending upon the settings provided by the sortBy(int, boolean), sortBy(int), setOmmitFiles(boolean) and setOmmitDirectories(boolean) methods. (see hasMore() for further information).

Returns:
Returns the next directory item as an XloadDirectoryItem object in sequence or null if at any stage the returned underlying directory or file has been deleted. This method will return the correct type of file (i.e. if the file is a file deployment or not).
Throws:
java.util.NoSuchElementException - Thrown if this method is used in an inappropriate location (i.e. outside the confines of an hasMore() loop or if there are no more directory items to return when this method is called.
java.lang.SecurityException - Thrown if there is a problem accessing the directory item (directory or file) on the file system with regard to permissions set by the SecurityManager.
Since:
1.1
See Also:
hasMore(), reset()

fileExists

public boolean fileExists(java.lang.String fileName)
Determines whether or not a file exists within this objects directory or not.

Parameters:
fileName - The name of the file to check existance for.
Returns:
Returns true if the file exists in this objects directory, false otherwise.
Throws:
XloadNullArgumentException - Thrown if fileName 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

directoryExists

public boolean directoryExists(java.lang.String direct)
Determines whether or not a directory exists within this objects directory or not.

Parameters:
direct - The name of the directory to check existence for.
Returns:
Returns true if the file exists in this objects directory, false otherwise.
Throws:
XloadNullArgumentException - Thrown if direct 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

getDirectoryPath

public java.lang.String getDirectoryPath()
Returns the absolute directory path of this objects directory on the file system.

Returns:
Returns the absolute path of this objects directory as a String object which will be system dependant.
Throws:
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

exists

public boolean exists()
Determines whether or not this objects directory exists or not.

Specified by:
exists in interface XloadDirectoryItem
Returns:
Returns true if this objects directory exists, false otherwise.
Throws:
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

equals

public boolean equals(java.lang.Object o)
Determines whether or not an object passed as a parameter is an XloadDirectory object and represents the same directory 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 XloadDirectory and it represents exactly the same directory on the file system as this objects represented directory such that -

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

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.1