com.aquafold.openapi.filesystem
Interface AQFileSystem

public interface AQFileSystem

Filesystem

gets information from and interacts with the filesystem.

Synopsis:

file system

Description
The file system object provides access to the underlying files and directories of the system on which the AquaScript is running. An instance of this interface can be obtained via aqua.filesystem alias.

Method Summary

void	attrib(String source, String attrName, String attrValue) Changes the permissions and/or attributes of a file or all files inside the specified directory.
void	concat(AQFileSet fileset, String file) Concatenates multiple files into a single one or displays to the console if file is not set.
void	copy(String source, String destination) Copies a single file to another file/directory or a directory to another directory.
void	copyFileSets(AQFileSet[] filesets, String destination) Copies a list of files as specified by the AQFilesSet object.
boolean	createDirectory(String directory) Creates a directory.
boolean	deleteDirectory(String directory) Delete a directory.
boolean	deleteDirectoryRecursively(String directory) Delete a directory recursively.
boolean	deleteFile(String file) Delete a single file.
void	deleteFileSets(AQFileSet[] filesets) Deletes files and directories as specified in the AQFileSet object.
int	directoryCount(String location, boolean recurse) Retrieves the number of directories under the defined directory.
long	directorySize(String location, boolean recurse) Returns the size of a directory file denoted by this location name.
boolean	exists(String source) Test whether a file or directory exists.
int	fileCount(String location, boolean recurse) Retrieves the number of files under a directory.
long	fileSize(String source) Returns the length of the file defined as the source.
void	fixCRLF(String source, String eol, String eof) Adjusts a text file or all files inside a directory to local conventions.
long	getFreeSpace(String partition) Returns the number of unallocated bytes in the partition.
long	getTotalSpace(String partition) Returns the size of the partition.
long	getUsableSpace(String partition) Returns the number of bytes available to this virtual machine on the partition.
boolean	isDirectory(String directory) Test whether the directory specified exists.
boolean	isFile(String file) Test whether the file specified exists.
boolean	isHidden(String source) Tests whether the file named by source is a hidden file.
String	lastModified(String Source) Returns the time that the file or directory denoted by source was last modified.
String[]	list(String source) Returns the files and directories defined in the source.
void	move(String source, String destination) Moves a single file to a new file or a directory to a new directory.
void	moveFileSets(AQFileSet[] filesets, String destination) Move files as specified in the AQFileSet object to a new location.
AQFileSet	newFileSet() Returns a new instance of FileSet.
void	rename(String source, String destination) Renames a file or a directory.
void	renameExtensions(String source, String from, String to) Renames the file extensions in the source directory.
void	replace(String directory, String token, String value) Replaces the occurrence of a given string (token) with another string (value) in a file or all files inside a directory.
void	replaceRegExp(String directory, String expression, String substitution) Replaces the occurrence of a given regular expression with a substitution pattern in a file or all files inside a directory.
String[]	scan(AQFileSet fileset) Scans a directory as defined in a fileset and returns a list of files.
String[]	scan(String directory) Scans a directory and return a list of files, including the subdirectories.
void	sync(String source, String destination) Synchronize a local target directory with files and subdirectories as defined in the source directory.
void	touch(String file, String modificationTime) Changes the modification time of a file and possibly creates it at the same time.

Method Detail

attrib

void attrib(String source,
            String attrName,
            String attrValue)
            throws Exception

Changes the permissions and/or attributes of a file or all files inside the specified directory. Currently, it has effect only under Windows. Please note: if file or directory not defined, no errors will be provided

Valid attrNames are: archive, hidden, readonly and system.
Valid attrValues are: true and false. Any value other then true will clear the attribute.

Parameters:

source - The file or directory to perform the task.

attrName - The attribute to be changed. The valid attributes are "archive", "hidden", "readonly" and "system".

attrValue - "true" or "false", any value other then "true" will clear the attribute.

Throws:

Exception - on error

concat

void concat(AQFileSet fileset,
            String file)
            throws Exception

Concatenates multiple files into a single one or displays to the console if file is not set.

Parameters:

fileset - A list of files, as defined in the AQFileSet object, to perform the task; required.

file - The location and name of the file; required.

Throws:

Exception - on error

copy

void copy(String source,
          String destination)
          throws Exception

Copies a single file to another file/directory or a directory to another directory. If a file with the same name exists in the destination, it will be overwritten. If source is a directory, then all files and sub directories within source will be copied.

Parameters:

source - The file to be copied; required.

destination - The location of where the file will be copied; required.

Throws:

Exception - on error

copyFileSets

void copyFileSets(AQFileSet[] filesets,
                  String destination)
                  throws Exception

Copies a list of files as specified by the AQFilesSet object. Use the AQFileSet object to define the source directory and the file pattern to copy.

Parameters:

filesets - A list of files, as defined in the AQFileSet object, to perform the task; required.

destination - The directory where the files will be copied; required.

Throws:

Exception - on error

deleteFile

boolean deleteFile(String file)
                   throws Exception

Delete a single file.

Parameters:

file - The name of the file to be deleted; required.

Returns:

true if deletion is successful; false otherwise.

Throws:

Exception - on error

deleteDirectory

boolean deleteDirectory(String directory)
                        throws Exception

Delete a directory. Directory will be removed only if there are no underlying files or sub directories.

Parameters:

directory - The name of the directory to be deleted; required.

Returns:

true if deletion is successful; false otherwise.

Throws:

Exception - on error

deleteDirectoryRecursively

boolean deleteDirectoryRecursively(String directory)

Delete a directory recursively. If there are any subdirectories or files under the directory specified, they will be removed.

Parameters:

directory - The name of the directory to be deleted; required.

Returns:

true if deletion is successful; false otherwise

deleteFileSets

void deleteFileSets(AQFileSet[] filesets)
                    throws Exception

Deletes files and directories as specified in the AQFileSet object. This method supports wild cards.

Parameters:

filesets - A list of files, as defined in the AQFileSet object, to perform the task; required.

Throws:

Exception - on error

exists

boolean exists(String source)
               throws Exception

Test whether a file or directory exists.

Parameters:

source - The file or directory; required.

Returns:

Returns true if a file or directory denoted exists on the file system; false otherwise.

Throws:

Exception

fileSize

long fileSize(String source)
              throws Exception

Returns the length of the file defined as the source. The return value is unspecified if this file name denotes a directory.

Parameters:

source - The file; required.

Returns:

The length, in bytes, of the file denoted by this abstract pathname, or 0L if the file does not exist. Some operating systems may return 0L for pathnames denoting system-dependent entities such as devices or pipes.

Throws:

Exception - on error

fixCRLF

void fixCRLF(String source,
             String eol,
             String eof)
             throws Exception

Adjusts a text file or all files inside a directory to local conventions.

Parameters:

source - The file or directory to perform the task; required.

eol - Specifies how end-of-line (EOL) characters are to be handled. The EOL characters are CR, LF and the pair CRLF. Valid values for this property are:

• "asis": leave EOL characters alone
• "cr": convert all EOLs to a single CR
• "lf": convert all EOLs to a single LF
• "crlf": convert all EOLs to the pair CRLF
• "mac": convert all EOLs to a single CR
• "unix": convert all EOLs to a single LF
• "dos": convert all EOLs to the pair CRLF
• null: This is the default value. This iss based on the platform on which you are running this function.

Any values other then the ones specified above will be treated as null.

eof - Specifies how DOS end of file (control-Z) characters are to be handled. Valid values for this property are:

• "add": ensure that there is an EOF character at the end of the file
• "asis": leave EOF characters alone
• "remove": remove any EOF character found at the end
• null: This is the default value. This is based on the platform on which you are running this task. For Unix platforms, the default is remove. For DOS based systems (including Windows), the default is asis.

Any values other then the ones specified above will be treated as null.

Throws:

Exception - on error

getTotalSpace

long getTotalSpace(String partition)
                   throws Exception

Returns the size of the partition.

Parameters:

partition - The name of the partition; required.

Throws:

Exception

getFreeSpace

long getFreeSpace(String partition)
                  throws Exception

Returns the number of unallocated bytes in the partition.

The returned number of unallocated bytes is a hint, but not a guarantee, that it is possible to use most or any of these bytes. The number of unallocated bytes is most likely to be accurate immediately after this call. It is likely to be made inaccurate by any external I/O operations including those made on the system outside of this virtual machine. This method makes no guarantee that write operations to this file system will succeed.

Parameters:

partition - The name of the partition; required.

Throws:

Exception - on error

getUsableSpace

long getUsableSpace(String partition)
                    throws Exception

Returns the number of bytes available to this virtual machine on the partition. When possible, this method checks for write permissions and other operating system restrictions and will therefore usually provide a more accurate estimate of how much new data can actually be written than getFreeSpace().

The returned number of available bytes is a hint, but not a guarantee, that it is possible to use most or any of these bytes. The number of unallocated bytes is most likely to be accurate immediately after this call. It is likely to be made inaccurate by any external I/O operations including those made on the system outside of this virtual machine. This method makes no guarantee that write operations to this file system will succeed.

Parameters:

partition - The name of the partition; required.

Throws:

Exception

isDirectory

boolean isDirectory(String directory)
                    throws Exception

Test whether the directory specified exists.

Parameters:

directory - The name of the directory; required.

Returns:

Returns true if and only if the directory denoted exists; false otherwise.

Throws:

Exception - on error

isFile

boolean isFile(String file)
               throws Exception

Test whether the file specified exists.

Parameters:

file - The name of the file; required.

Returns:

Returns true if and only if the file denoted exists and is a normal file; false otherwise.

Throws:

Exception - on error

isHidden

boolean isHidden(String source)
                 throws Exception

Tests whether the file named by source is a hidden file. The exact definition of hidden is system-dependent. On UNIX systems, a file is considered to be hidden if its name begins with a period character ('.'). On Microsoft Windows systems, a file is considered to be hidden if it has been marked as such in the filesystem.

Parameters:

source - The name of the file; required.

Returns:

True if and only if the file denoted by source is hidden according to the conventions of the underlying platform.

Throws:

Exception - on error

lastModified

String lastModified(String Source)
                    throws Exception

Returns the time that the file or directory denoted by source was last modified.

Parameters:

Source - The file name or the directory name; required.

Returns:

String A string value representing the time the file was last modified, display in default time zone with the given system locale. or null if the file does not exist or if an I/O error occurs

Throws:

Exception - on error

list

String[] list(String source)
              throws Exception

Returns the files and directories defined in the source.

If source does not denote a directory, then this method returns null. Otherwise an array of strings is returned, one for each file or directory in the directory. Names denoting the directory itself and the directory's parent directory are not included in the result. Each string is a file name rather than a complete path. This will not include files in the subdirectories under the source.

There is no guarantee that the name strings in the resulting array will appear in any specific order; they are not, in particular, guaranteed to appear in alphabetical order.

Parameters:

source - The directory; required.

Returns:

An array of String, if the source is a directory, otherwise null.

Throws:

Exception - on error

createDirectory

boolean createDirectory(String directory)
                        throws Exception

Creates a directory. Non-existent parent directories are created, when necessary.

Parameters:

directory - The directory to create; required.

Returns:

True if the operation succeeds.

Throws:

Exception - on error

newFileSet

AQFileSet newFileSet()

Returns a new instance of FileSet.

Returns:

AQFileSet

move

void move(String source,
          String destination)
          throws Exception

Moves a single file to a new file or a directory to a new directory. The destination file or directory is overwritten if it exists.

Parameters:

source - The file or directory to be moved; required.

destination - The destination file or directory; required.

Throws:

Exception - on error

moveFileSets

void moveFileSets(AQFileSet[] filesets,
                  String destination)
                  throws Exception

Move files as specified in the AQFileSet object to a new location.

Parameters:

filesets - A list of files to be moved as defined in the AQFileSet object; required.

destination - The destination directory; required.

Throws:

Exception - on error

rename

void rename(String source,
            String destination)
            throws Exception

Renames a file or a directory.

Parameters:

source - The location and name of the file or directory to be renamed; required.

destination - The new name of the file or directory; required.

Throws:

Exception - on error, if destination exists

renameExtensions

void renameExtensions(String source,
                      String from,
                      String to)
                      throws Exception

Renames the file extensions in the source directory.

Parameters:

source - Location of the files to be changed; required.

from - Files with this extension to be changed; required.

to - The new extension. E.g. "xls" for excel files, "txt" for text files; required

Throws:

Exception - on error

replace

void replace(String directory,
             String token,
             String value)
             throws Exception

Replaces the occurrence of a given string (token) with another string (value) in a file or all files inside a directory. The empty string "" is used if value is not specified.

Parameters:

directory - The location of the files to be changed; required.

token - The given string to be changed; required.

value - The new string value.

Throws:

Exception - on error

replaceRegExp

void replaceRegExp(String directory,
                   String expression,
                   String substitution)
                   throws Exception

Replaces the occurrence of a given regular expression with a substitution pattern in a file or all files inside a directory. This will only work for text files.

Parameters:

directory - The location of the files to be changed; required.

expression - A regular expression; required.

substitution - A substitution pattern; required.

Throws:

Exception - on error

scan

String[] scan(String directory)
              throws Exception

Scans a directory and return a list of files, including the subdirectories.

Parameters:

directory - The name of the directory to be scanned; required.

Returns:

A list of files. The list contains the absolute path of the file.

Throws:

Exception - on error

scan

String[] scan(AQFileSet fileset)
              throws Exception

Scans a directory as defined in a fileset and returns a list of files.

Parameters:

fileset - The location and file pattern as defined in the AQFileSet object; required.

Returns:

A list of files. The list contains the absolute path of the file.

Throws:

Exception - on error

sync

void sync(String source,
          String destination)
          throws Exception

Synchronize a local target directory with files and subdirectories as defined in the source directory. This method only does unidirectional synchronization.

Any file in the target directory that has not been matched by a file in the source gets removed. I.e. if you exclude a file in your sources and a file of that name is present in the target dir, it will get removed from the target. Files in the destination with the same name will be overwritten even if it has a more recent timestamp.

Parameters:

source - The location of the files to be synchronized; required.

destination - The destination directory. If the directory doesn't exist, it will be created.

Throws:

Exception - on error

touch

void touch(String file,
           String modificationTime)
           throws Exception

Changes the modification time of a file and possibly creates it at the same time. The modificationTime, if set, needs to be in the format "MM/DD/YYYY HH:MM AM or PM" or "MM/DD/YYYY HH:MM:SS AM or PM".

Parameters:

file - The file to be touched. If the file doesn't exist, it will be created.

modificationTime - The new modification time of the file. The string should be in the following format "MM/DD/YYYY HH:MM AM or PM" or "MM/DD/YYYY HH:MM:SS AM or PM".

Throws:

Exception - on error

fileCount

int fileCount(String location,
              boolean recurse)
              throws Exception

Retrieves the number of files under a directory. If the recurse flag is set to true, it will count all files in the sub directories as well.

Parameters:

location - The location of the files to be counted; required. If location is a file, an exception will be thrown.

recurse - If recurse is true, count files in the sub directory, otherwise don't include files in the sub directory in the count; required.

Returns:

The number of files in the location specified.

Throws:

Exception - If the location is invalid or if location is not a directory.

directoryCount

int directoryCount(String location,
                   boolean recurse)
                   throws Exception

Retrieves the number of directories under the defined directory. If the recurse flag is set to true, it will count all directories in the sub directories as well.

Parameters:

location - The location of the directories to be counted; required. If location is a file, an exception will be thrown.

recurse - If recurse is true, count directories in the sub directory, otherwise don't include directories in the sub directory in the count; required.

Returns:

A count of the directories in the location specified.

Throws:

Exception - If the location is invalid or if location is not a directory.

directorySize

long directorySize(String location,
                   boolean recurse)
                   throws Exception

Returns the size of a directory file denoted by this location name.

Parameters:

location - The location of the directory; required.

recurse - If recurse is true, count files in the sub directory, otherwise don't include files in the sub directory in the count; required

Returns:

The length, in bytes, of all the files under this location depending of whether the recurse flag is set or not.

Throws:

Exception - on error