Added jsdoc comment based documentation
This commit is contained in:
zumbrunn
parent
ab280132bd
commit
134d1483da
1 changed files with 258 additions and 23 deletions
281
helma/File.js
281
helma/File.js
|
|
@ -6,19 +6,36 @@
|
|||
* compliance with the License. A copy of the License is available at
|
||||
* http://adele.helma.org/download/helma/license.txt
|
||||
*
|
||||
* Copyright 1998-2006 Helma Software. All Rights Reserved.
|
||||
* Copyright 1998-2007 Helma Software. All Rights Reserved.
|
||||
*
|
||||
* $RCSfile: File.js,v $
|
||||
* $Author: czv $
|
||||
* $Revision: 1.2 $
|
||||
* $Date: 2006/04/24 07:02:17 $
|
||||
* $Author: hannes $
|
||||
* $Revision: 1.3 $
|
||||
* $Date: 2006/07/25 20:07:59 $
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* @fileoverview Default properties and methods of
|
||||
* the File prototype.
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* Define the global namespace if not existing
|
||||
*/
|
||||
if (!global.helma) {
|
||||
global.helma = {};
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Constructor for File objects, providing read and
|
||||
* write access to the file system.
|
||||
* @class This class represents a local file or directory
|
||||
* @param {String} path as String, can be either absolute or relative to the helma home directory
|
||||
* @constructor
|
||||
*/
|
||||
helma.File = function(path) {
|
||||
var BufferedReader = java.io.BufferedReader;
|
||||
var File = java.io.File;
|
||||
|
|
@ -56,19 +73,43 @@ helma.File = function(path) {
|
|||
|
||||
this.lastError = null;
|
||||
|
||||
/** @ignore */
|
||||
this.toString = function() {
|
||||
return file.toString();
|
||||
};
|
||||
|
||||
/**
|
||||
* Returns the name of the file or directory represented by this File object.
|
||||
* <br /><br />
|
||||
* This is just the last name in the pathname's name sequence.
|
||||
* If the pathname's name sequence is empty, then the empty
|
||||
* string is returned.
|
||||
*
|
||||
* @returns String containing the name of the file or directory
|
||||
* @type String
|
||||
*/
|
||||
this.getName = function() {
|
||||
var name = file.getName();
|
||||
return (name == null ? "" : name);
|
||||
};
|
||||
|
||||
/**
|
||||
* Returns true if the file represented by this File object
|
||||
* is currently open.
|
||||
*
|
||||
* @returns Boolean
|
||||
* @type Boolean
|
||||
*/
|
||||
this.isOpened = function() {
|
||||
return (readerWriter != null);
|
||||
};
|
||||
|
||||
/**
|
||||
* Opens the file represented by this File object.
|
||||
*
|
||||
* @returns Boolean
|
||||
* @type Boolean
|
||||
*/
|
||||
this.open = function() {
|
||||
if (self.isOpened()) {
|
||||
setError(new IllegalStateException("File already open"));
|
||||
|
|
@ -92,16 +133,36 @@ helma.File = function(path) {
|
|||
return;
|
||||
};
|
||||
|
||||
/**
|
||||
* Tests whether the file or directory represented by this File object exists.
|
||||
*
|
||||
* @returns Boolean true if the file or directory exists; false otherwise
|
||||
* @type Boolean
|
||||
*/
|
||||
this.exists = function() {
|
||||
return file.exists();
|
||||
};
|
||||
|
||||
/**
|
||||
* Returns the pathname string of this File object's parent directory.
|
||||
*
|
||||
* @returns String containing the pathname of the parent directory
|
||||
* @type String
|
||||
*/
|
||||
this.getParent = function() {
|
||||
if (!file.getParent())
|
||||
return null;
|
||||
return new helma.File(file.getParent());
|
||||
};
|
||||
|
||||
/**
|
||||
* This methods reads characters until an end of line/file is encountered
|
||||
* then returns the string for these characters (without any end of line
|
||||
* character).
|
||||
*
|
||||
* @returns String of the next unread line in the file
|
||||
* @type String
|
||||
*/
|
||||
this.readln = function() {
|
||||
if (!self.isOpened()) {
|
||||
setError(new IllegalStateException("File not opened"));
|
||||
|
|
@ -136,6 +197,14 @@ helma.File = function(path) {
|
|||
return;
|
||||
};
|
||||
|
||||
/**
|
||||
* Appends a string to the file represented by this File object.
|
||||
*
|
||||
* @param {String} what as String, to be written to the file
|
||||
* @returns Boolean
|
||||
* @type Boolean
|
||||
* @see #writeln
|
||||
*/
|
||||
this.write = function(what) {
|
||||
if (!self.isOpened()) {
|
||||
setError(new IllegalStateException("File not opened"));
|
||||
|
|
@ -151,6 +220,15 @@ helma.File = function(path) {
|
|||
return true;
|
||||
};
|
||||
|
||||
/**
|
||||
* Appends a string with a platform specific end of
|
||||
* line to the file represented by this File object.
|
||||
*
|
||||
* @param {String} what as String, to be written to the file
|
||||
* @returns Boolean
|
||||
* @type Boolean
|
||||
* @see #write
|
||||
*/
|
||||
this.writeln = function(what) {
|
||||
if (self.write(what)) {
|
||||
readerWriter.println();
|
||||
|
|
@ -159,10 +237,27 @@ helma.File = function(path) {
|
|||
return false;
|
||||
};
|
||||
|
||||
/**
|
||||
* Tests whether this File object's pathname is absolute.
|
||||
* <br /><br />
|
||||
* The definition of absolute pathname is system dependent.
|
||||
* On UNIX systems, a pathname is absolute if its prefix is "/".
|
||||
* On Microsoft Windows systems, a pathname is absolute if its prefix
|
||||
* is a drive specifier followed by "\\", or if its prefix is "\\".
|
||||
*
|
||||
* @returns Boolean if this abstract pathname is absolute, false otherwise
|
||||
* @type Boolean
|
||||
*/
|
||||
this.isAbsolute = function() {
|
||||
return file.isAbsolute();
|
||||
};
|
||||
|
||||
/**
|
||||
* Deletes the file or directory represented by this File object.
|
||||
*
|
||||
* @returns Boolean
|
||||
* @type Boolean
|
||||
*/
|
||||
this.remove = function() {
|
||||
if (self.isOpened()) {
|
||||
setError(new IllegalStateException("An openened file cannot be removed"));
|
||||
|
|
@ -171,13 +266,14 @@ helma.File = function(path) {
|
|||
return file["delete"]();
|
||||
};
|
||||
|
||||
/*
|
||||
* will list all files within a directory
|
||||
* you may pass a RegExp Pattern to return just
|
||||
* files matching this pattern
|
||||
/**
|
||||
* List of all files within the directory represented by this File object.
|
||||
* <br /><br />
|
||||
* You may pass a RegExp Pattern to return just files matching this pattern.
|
||||
*
|
||||
* @example var xmlFiles = dir.list(/.*\.xml/);
|
||||
* @param RegExp pattern to test each file name against
|
||||
* @return Array the list of file names
|
||||
* @param {RegExp} pattern as RegExp, optional pattern to test each file name against
|
||||
* @returns Array the list of file names
|
||||
*/
|
||||
this.list = function(pattern) {
|
||||
if (self.isOpened())
|
||||
|
|
@ -196,6 +292,12 @@ helma.File = function(path) {
|
|||
return file.list();
|
||||
};
|
||||
|
||||
/**
|
||||
* Purges the content of the file represented by this File object.
|
||||
*
|
||||
* @returns Boolean
|
||||
* @type Boolean
|
||||
*/
|
||||
this.flush = function() {
|
||||
if (!self.isOpened()) {
|
||||
setError(new IllegalStateException("File not opened"));
|
||||
|
|
@ -215,6 +317,12 @@ helma.File = function(path) {
|
|||
return true;
|
||||
};
|
||||
|
||||
/**
|
||||
* Closes the file represented by this File object.
|
||||
*
|
||||
* @returns Boolean
|
||||
* @type Boolean
|
||||
*/
|
||||
this.close = function() {
|
||||
if (!self.isOpened())
|
||||
return false;
|
||||
|
|
@ -229,11 +337,26 @@ helma.File = function(path) {
|
|||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Returns the pathname string of this File object.
|
||||
* <br /><br />
|
||||
* The resulting string uses the default name-separator character
|
||||
* to separate the names in the name sequence.
|
||||
*
|
||||
* @returns String of this file's pathname
|
||||
* @type String
|
||||
*/
|
||||
this.getPath = function() {
|
||||
var path = file.getPath();
|
||||
return (path == null ? "" : path);
|
||||
};
|
||||
|
||||
/**
|
||||
* Contains the last error that occured, if any.
|
||||
* @returns String
|
||||
* @type String
|
||||
* @see #clearError
|
||||
*/
|
||||
this.error = function() {
|
||||
if (this.lastError == null) {
|
||||
return "";
|
||||
|
|
@ -246,40 +369,116 @@ helma.File = function(path) {
|
|||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Clears any error message that may otherwise be returned by the error method.
|
||||
*
|
||||
* @see #error
|
||||
*/
|
||||
this.clearError = function() {
|
||||
this.lastError = null;
|
||||
return;
|
||||
};
|
||||
|
||||
/**
|
||||
* Tests whether the application can read the file
|
||||
* represented by this File object.
|
||||
*
|
||||
* @returns Boolean true if the file exists and can be read; false otherwise
|
||||
* @type Boolean
|
||||
*/
|
||||
this.canRead = function() {
|
||||
return file.canRead();
|
||||
};
|
||||
|
||||
/**
|
||||
* Tests whether the file represented by this File object is writable.
|
||||
*
|
||||
* @returns Boolean true if the file exists and can be modified; false otherwise.
|
||||
* @type Boolean
|
||||
*/
|
||||
this.canWrite = function() {
|
||||
return file.canWrite();
|
||||
};
|
||||
|
||||
/**
|
||||
* Returns the absolute pathname string of this file.
|
||||
* <br /><br />
|
||||
* If this File object's pathname is already absolute, then the pathname
|
||||
* string is simply returned as if by the getPath() method. If this
|
||||
* abstract pathname is the empty abstract pathname then the pathname
|
||||
* string of the current user directory, which is named by the system
|
||||
* property user.dir, is returned. Otherwise this pathname is resolved
|
||||
* in a system-dependent way. On UNIX systems, a relative pathname is
|
||||
* made absolute by resolving it against the current user directory.
|
||||
* On Microsoft Windows systems, a relative pathname is made absolute
|
||||
* by resolving it against the current directory of the drive named by
|
||||
* the pathname, if any; if not, it is resolved against the current user
|
||||
* directory.
|
||||
*
|
||||
* @returns String The absolute pathname string
|
||||
* @type String
|
||||
*/
|
||||
this.getAbsolutePath = function() {
|
||||
var absolutPath = file.getAbsolutePath();
|
||||
return (absolutPath == null ? "" : absolutPath);
|
||||
};
|
||||
|
||||
/**
|
||||
* Returns the length of the file represented by this File object.
|
||||
* <br /><br />
|
||||
* The return value is unspecified if this pathname denotes a directory.
|
||||
*
|
||||
* @returns Number The length, in bytes, of the file, or 0L if the file does not exist
|
||||
* @type Number
|
||||
*/
|
||||
this.getLength = function() {
|
||||
return file.length();
|
||||
};
|
||||
|
||||
/**
|
||||
* Tests whether the file represented by this File object is a directory.
|
||||
*
|
||||
* @returns Boolean true if this File object is a directory and exists; false otherwise
|
||||
* @type Boolean
|
||||
*/
|
||||
this.isDirectory = function() {
|
||||
return file.isDirectory();
|
||||
};
|
||||
|
||||
/**
|
||||
* Tests whether the file represented by this File object is a normal file.
|
||||
* <br /><br />
|
||||
* A file is normal if it is not a directory and, in addition, satisfies
|
||||
* other system-dependent criteria. Any non-directory file created by a
|
||||
* Java application is guaranteed to be a normal file.
|
||||
*
|
||||
* @returns Boolean true if this File object is a normal file and exists; false otherwise
|
||||
* @type Boolean
|
||||
*/
|
||||
this.isFile = function() {
|
||||
return file.isFile();
|
||||
};
|
||||
|
||||
/**
|
||||
* Returns the time when the file represented by this File object was last modified.
|
||||
* <br /><br />
|
||||
* A number representing the time the file was last modified,
|
||||
* measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970),
|
||||
* or 0L if the file does not exist or if an I/O error occurs.
|
||||
*
|
||||
* @returns Number in milliseconds since 00:00:00 GMT, January 1, 1970
|
||||
* @type Number
|
||||
*/
|
||||
this.lastModified = function() {
|
||||
return file.lastModified();
|
||||
};
|
||||
|
||||
/**
|
||||
* Creates the directory represented by this File object.
|
||||
*
|
||||
* @returns Boolean true if the directory was created; false otherwise
|
||||
* @type Boolean
|
||||
*/
|
||||
this.makeDirectory = function() {
|
||||
if (self.isOpened())
|
||||
return false;
|
||||
|
|
@ -287,6 +486,18 @@ helma.File = function(path) {
|
|||
return (file.exists() || file.mkdirs());
|
||||
};
|
||||
|
||||
/**
|
||||
* Renames the file represented by this File object.
|
||||
* <br /><br />
|
||||
* Whether or not this method can move a file from one
|
||||
* filesystem to another is platform-dependent. The return
|
||||
* value should always be checked to make sure that the
|
||||
* rename operation was successful.
|
||||
*
|
||||
* @param {String} toFile as String, new pathname for the named file
|
||||
* @returns true if the renaming succeeded; false otherwise
|
||||
* @type Boolean
|
||||
*/
|
||||
this.renameTo = function(toFile) {
|
||||
if (toFile == null) {
|
||||
setError(new IllegalArgumentException("Uninitialized target File object"));
|
||||
|
|
@ -303,6 +514,13 @@ helma.File = function(path) {
|
|||
return file.renameTo(new java.io.File(toFile.getAbsolutePath()));
|
||||
};
|
||||
|
||||
/**
|
||||
* Returns true if the file represented by this File object
|
||||
* has been read entirely and the end of file has been reached.
|
||||
*
|
||||
* @returns Boolean
|
||||
* @type Boolean
|
||||
*/
|
||||
this.eof = function() {
|
||||
if (!self.isOpened()) {
|
||||
setError(new IllegalStateException("File not opened"));
|
||||
|
|
@ -327,6 +545,13 @@ helma.File = function(path) {
|
|||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* This methods reads the rest of the file and returns an
|
||||
* array with a slot for each line of the file.
|
||||
*
|
||||
* @returns Array of the remaining unread lines in the file
|
||||
* @type Array
|
||||
*/
|
||||
this.readAll = function() {
|
||||
// Open the file for readAll
|
||||
if (self.isOpened()) {
|
||||
|
|
@ -367,9 +592,14 @@ helma.File = function(path) {
|
|||
}
|
||||
};
|
||||
|
||||
// DANGER! DANGER! HIGH VOLTAGE!
|
||||
// this method removes a directory recursively
|
||||
// without any warning or precautious measures
|
||||
|
||||
/**
|
||||
* This method removes a directory recursively .
|
||||
* <br /><br />
|
||||
* DANGER! DANGER! HIGH VOLTAGE!
|
||||
* The directory is deleted recursively without
|
||||
* any warning or precautious measures.
|
||||
*/
|
||||
this.removeDirectory = function() {
|
||||
if (!file.isDirectory())
|
||||
return false;
|
||||
|
|
@ -386,10 +616,11 @@ helma.File = function(path) {
|
|||
};
|
||||
|
||||
/**
|
||||
* recursivly lists all files below a given directory
|
||||
* Recursivly lists all files below a given directory
|
||||
* you may pass a RegExp Pattern to return just
|
||||
* files matching this pattern
|
||||
* @param RegExp pattern to test each file name against
|
||||
* files matching this pattern.
|
||||
*
|
||||
* @param {RegExp} pattern as RegExp, to test each file name against
|
||||
* @returns Array the list of absolute file paths
|
||||
*/
|
||||
this.listRecursive = function(pattern) {
|
||||
|
|
@ -411,8 +642,9 @@ helma.File = function(path) {
|
|||
}
|
||||
|
||||
/**
|
||||
* function makes a copy of a file over partitions
|
||||
* @param StringOrFile full path of the new file
|
||||
* Makes a copy of a file over partitions.
|
||||
*
|
||||
* @param {String|helma.File} dest as a File object or the String of full path of the new file
|
||||
*/
|
||||
this.hardCopy = function(dest) {
|
||||
var inStream = new java.io.BufferedInputStream(
|
||||
|
|
@ -435,9 +667,10 @@ helma.File = function(path) {
|
|||
}
|
||||
|
||||
/**
|
||||
* function moves a file to a new destination directory
|
||||
* @param String full path of the new file
|
||||
* @return Boolean true in case file could be moved, false otherwise
|
||||
* Moves a file to a new destination directory.
|
||||
*
|
||||
* @param {String} dest as String, the full path of the new file
|
||||
* @returns Boolean true in case file could be moved, false otherwise
|
||||
*/
|
||||
this.move = function(dest) {
|
||||
// instead of using the standard File method renameTo()
|
||||
|
|
@ -450,8 +683,9 @@ helma.File = function(path) {
|
|||
}
|
||||
|
||||
/**
|
||||
* returns file as ByteArray
|
||||
* useful for passing it to a function instead of an request object
|
||||
* Returns file as ByteArray.
|
||||
* <br /><br />
|
||||
* Useful for passing it to a function instead of an request object.
|
||||
*/
|
||||
this.toByteArray = function() {
|
||||
if (!this.exists())
|
||||
|
|
@ -477,6 +711,7 @@ helma.File = function(path) {
|
|||
}
|
||||
|
||||
|
||||
/** @ignore */
|
||||
helma.File.toString = function() {
|
||||
return "[helma.File]";
|
||||
};
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue