JSFile

Overview

The JSFile is an IScriptObject representation of a file, supporting local, remote, and web contexts. It provides functionalities to manipulate files, such as checking read/write permissions, creating or deleting files, and managing file properties like size, type, and last modified date. Operations on directories are also supported, allowing directory creation and listing of contents.

Methods Summarized

Type	Name	Summary
Boolean	canRead()	Returns true if the file exists and is readable (has access to it) - works on remote files too.
Boolean	canWrite()	Returns true if the file exists and can be modified - works on remote files too.
JSFile	convertToRemote(fileName)	Return a new JSFile instance that contains a remote file with the content of current JSFile.
Boolean	createNewFile()	Creates the file on disk if needed.
Boolean	deleteFile()	Deletes the file from the disk if possible.
Boolean	exists()	Returns true if the file/directory exists on the filesystem - works on remote files too.
JSFile	getAbsoluteFile()	Returns a JSFile instance that corresponds to the absolute form of this pathname - works on remote files too.
String	getAbsolutePath()	Returns a String representation of the absolute form of this pathname - works on remote files too.
Array	getBytes()	Gets the contents (bytes) for the file data.
String	getContentType()	Returns the contenttype of this file, like for example 'application/pdf' - works on remote files too.
String	getName()	Returns the name of the file.
String	getParent()	Returns the String representation of the path of the parent of this file - works on remote files too.
JSFile	getParentFile()	Returns a JSFile instance that corresponds to the parent of this file - works on remote files too.
String	getPath()	Returns a String holding the path to the file - works on remote files too.
String	getRemoteUrl()	Get a url from file that can be used to download the file in a browser.
Boolean	isAbsolute()	Returns true if the path is absolute.
Boolean	isDirectory()	Returns true if the file is a directory - works on remote files too.
Boolean	isFile()	Returns true if the file is a file and not a regular file - works on remote files too.
Boolean	isHidden()	Returns true if the file is hidden (a file system attribute) - works on remote files too.
Date	lastModified()	Returns the time/date of the last modification on the file - works on remote files too.
Array	list()	Returns an array of strings naming the files and directories located inside the file, if the file is a directory - works on remote files too.
Array	listFiles()	Returns an array of JSFiles naming the files and directories located inside the file, if the file is a directory - works on remote files too.
Boolean	mkdir()	Creates a directory on disk if possible.
Boolean	mkdirs()	Creates a directory on disk, together with all its parent directories, if possible.
Boolean	renameTo(destination)	Renames the file to a different name.
Boolean	setBytes(bytes)	Set the content of the file (local or remote) to the bytes provided Will not create a new file if one doesn't exist
Boolean	setBytes(bytes, createFile)	Set the content of the file (local or remote) to the bytes provided
Boolean	setLastModified(date)	Sets the date/time of the last modification on the file.
Boolean	setReadOnly()	Sets the readonly attribute of the file/directory.
Number	size()	Returns the size in bytes of the file.

Methods Detailed

canRead()

Returns true if the file exists and is readable (has access to it) - works on remote files too.

Returns: Boolean True if the file exists and is readable; false otherwise (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('./big.jpg');
// or for a remote file:
// var f = plugins.convertToRemoteJSFile('/images/big.jpg');
if (f && f.exists()) {
	application.output('is absolute: ' + f.isAbsolute());
	application.output('is dir: ' + f.isDirectory());
	application.output('is file: ' + f.isFile());
	application.output('is hidden: ' + f.isHidden());
	application.output('can read: ' + f.canRead());
	application.output('can write: ' + f.canWrite());
	application.output('last modified: ' + f.lastModified());
	application.output('name: ' + f.getName());
	application.output('path: ' + f.getPath());
	application.output('absolute path: ' + f.getAbsolutePath());
	application.output('content type: ' + f.getContentType());
	application.output('size: ' + f.size());
}
else {
	application.output('File/folder not found.');
}

canWrite()

Returns true if the file exists and can be modified - works on remote files too.

Returns: Boolean True if the file exists and can be modified; false otherwise (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('./big.jpg');
// or for a remote file:
// var f = plugins.convertToRemoteJSFile('/images/big.jpg');
if (f && f.exists()) {
	application.output('is absolute: ' + f.isAbsolute());
	application.output('is dir: ' + f.isDirectory());
	application.output('is file: ' + f.isFile());
	application.output('is hidden: ' + f.isHidden());
	application.output('can read: ' + f.canRead());
	application.output('can write: ' + f.canWrite());
	application.output('last modified: ' + f.lastModified());
	application.output('name: ' + f.getName());
	application.output('path: ' + f.getPath());
	application.output('absolute path: ' + f.getAbsolutePath());
	application.output('content type: ' + f.getContentType());
	application.output('size: ' + f.size());
}
else {
	application.output('File/folder not found.');
}

convertToRemote(fileName)

Return a new JSFile instance that contains a remote file with the content of current JSFile.

Parameters

• String fileName ;

Returns: JSFile A new JSFile instance representing a remote file with the content of the current JSFile.

createNewFile()

Creates the file on disk if needed. Returns true if the file (name) did not already exists and had to be created - for remote, use the streamFilesToServer to stream a file.

Returns: Boolean True if the file was created successfully; false otherwise.

Sample

var f = plugins.file.convertToJSFile('story.txt');
if (!f.exists())
	f.createNewFile();

deleteFile()

Deletes the file from the disk if possible. Returns true if the file could be deleted. If the file is a directory, then it must be empty in order to be deleted - works on remote files too.

Returns: Boolean True if the file was successfully deleted; false otherwise. (Deprecated: Use #deleteFile() instead.)

Sample

var f = plugins.file.convertToJSFile('story.txt');
// or for a remote file:
// var f = plugins.convertToRemoteJSFile('/story.txt');
if (f && f.exists())
	f.deleteFile();

exists()

Returns true if the file/directory exists on the filesystem - works on remote files too.

Returns: Boolean True if the file or directory exists; false otherwise (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('./big.jpg');
// or for a remote file:
// var f = plugins.convertToRemoteJSFile('/images/big.jpg');
if (f && f.exists()) {
	application.output('is absolute: ' + f.isAbsolute());
	application.output('is dir: ' + f.isDirectory());
	application.output('is file: ' + f.isFile());
	application.output('is hidden: ' + f.isHidden());
	application.output('can read: ' + f.canRead());
	application.output('can write: ' + f.canWrite());
	application.output('last modified: ' + f.lastModified());
	application.output('name: ' + f.getName());
	application.output('path: ' + f.getPath());
	application.output('absolute path: ' + f.getAbsolutePath());
	application.output('content type: ' + f.getContentType());
	application.output('size: ' + f.size());
}
else {
	application.output('File/folder not found.');
}

getAbsoluteFile()

Returns a JSFile instance that corresponds to the absolute form of this pathname - works on remote files too.

Returns: JSFile A JSFile instance representing the absolute form of this file's path (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('story.txt');
// or for a remote file:
// var f = plugins.file.convertToRemoteJSFile('/story.txt');
application.output('parent folder: ' + f.getAbsoluteFile().getParent());
application.output('parent folder has ' + f.getAbsoluteFile().getParentFile().listFiles().length + ' entries');

getAbsolutePath()

Returns a String representation of the absolute form of this pathname - works on remote files too.

Returns: String The absolute path of this file (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('./big.jpg');
// or for a remote file:
// var f = plugins.convertToRemoteJSFile('/images/big.jpg');
if (f && f.exists()) {
	application.output('is absolute: ' + f.isAbsolute());
	application.output('is dir: ' + f.isDirectory());
	application.output('is file: ' + f.isFile());
	application.output('is hidden: ' + f.isHidden());
	application.output('can read: ' + f.canRead());
	application.output('can write: ' + f.canWrite());
	application.output('last modified: ' + f.lastModified());
	application.output('name: ' + f.getName());
	application.output('path: ' + f.getPath());
	application.output('absolute path: ' + f.getAbsolutePath());
	application.output('content type: ' + f.getContentType());
	application.output('size: ' + f.size());
}
else {
	application.output('File/folder not found.');
}

getBytes()

Gets the contents (bytes) for the file data.

Returns: Array The contents of the file as a byte array.

Sample

var theFile = plugins.file.showFileOpenDialog();
application.output('The file size in bytes: ' + theFile.getBytes());

getContentType()

Returns the contenttype of this file, like for example 'application/pdf' - works on remote files too.

Returns: String The content type of the file (e.g., 'application/pdf') (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('./big.jpg');
// or for a remote file:
// var f = plugins.convertToRemoteJSFile('/images/big.jpg');
if (f && f.exists()) {
	application.output('is absolute: ' + f.isAbsolute());
	application.output('is dir: ' + f.isDirectory());
	application.output('is file: ' + f.isFile());
	application.output('is hidden: ' + f.isHidden());
	application.output('can read: ' + f.canRead());
	application.output('can write: ' + f.canWrite());
	application.output('last modified: ' + f.lastModified());
	application.output('name: ' + f.getName());
	application.output('path: ' + f.getPath());
	application.output('absolute path: ' + f.getAbsolutePath());
	application.output('content type: ' + f.getContentType());
	application.output('size: ' + f.size());
}
else {
	application.output('File/folder not found.');
}

getName()

Returns the name of the file. The name consists in the last part of the file path - works on remote files too.

Returns: String The name of the file, which is the last part of the file path (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('./big.jpg');
// or for a remote file:
// var f = plugins.convertToRemoteJSFile('/images/big.jpg');
if (f && f.exists()) {
	application.output('is absolute: ' + f.isAbsolute());
	application.output('is dir: ' + f.isDirectory());
	application.output('is file: ' + f.isFile());
	application.output('is hidden: ' + f.isHidden());
	application.output('can read: ' + f.canRead());
	application.output('can write: ' + f.canWrite());
	application.output('last modified: ' + f.lastModified());
	application.output('name: ' + f.getName());
	application.output('path: ' + f.getPath());
	application.output('absolute path: ' + f.getAbsolutePath());
	application.output('content type: ' + f.getContentType());
	application.output('size: ' + f.size());
}
else {
	application.output('File/folder not found.');
}

getParent()

Returns the String representation of the path of the parent of this file - works on remote files too.

Returns: String The path of the parent directory of this file (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('story.txt');
// or for a remote file:
// var f = plugins.file.convertToRemoteJSFile('/story.txt');
application.output('parent folder: ' + f.getAbsoluteFile().getParent());
application.output('parent folder has ' + f.getAbsoluteFile().getParentFile().listFiles().length + ' entries');

getParentFile()

Returns a JSFile instance that corresponds to the parent of this file - works on remote files too.

Returns: JSFile A JSFile instance representing the parent directory of this file (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('story.txt');
// or for a remote file:
// var f = plugins.file.convertToRemoteJSFile('/story.txt');
application.output('parent folder: ' + f.getAbsoluteFile().getParent());
application.output('parent folder has ' + f.getAbsoluteFile().getParentFile().listFiles().length + ' entries');

getPath()

Returns a String holding the path to the file - works on remote files too.

Returns: String The path to the file (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('./big.jpg');
// or for a remote file:
// var f = plugins.convertToRemoteJSFile('/images/big.jpg');
if (f && f.exists()) {
	application.output('is absolute: ' + f.isAbsolute());
	application.output('is dir: ' + f.isDirectory());
	application.output('is file: ' + f.isFile());
	application.output('is hidden: ' + f.isHidden());
	application.output('can read: ' + f.canRead());
	application.output('can write: ' + f.canWrite());
	application.output('last modified: ' + f.lastModified());
	application.output('name: ' + f.getName());
	application.output('path: ' + f.getPath());
	application.output('absolute path: ' + f.getAbsolutePath());
	application.output('content type: ' + f.getContentType());
	application.output('size: ' + f.size());
}
else {
	application.output('File/folder not found.');
}

getRemoteUrl()

Get a url from file that can be used to download the file in a browser. This is a complete url with the server url that is get from application.getServerURL(). If the file is a remote file will be shared using a default folder that requires no session. If the file is a local file will be available only for current client (url contains session id)

This just returns the URL (session or static based). If you want to stream a file directly use plugin.file.streamFile where you also can give more options to browser.

Returns: String the url

isAbsolute()

Returns true if the path is absolute. The path is absolute if it starts with '/' on Unix/Linux/MacOS or has a driver letter on Windows - works on remote files too.

Returns: Boolean True if the path is absolute; false otherwise (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('./big.jpg');
// or for a remote file:
// var f = plugins.convertToRemoteJSFile('/images/big.jpg');
if (f && f.exists()) {
	application.output('is absolute: ' + f.isAbsolute());
	application.output('is dir: ' + f.isDirectory());
	application.output('is file: ' + f.isFile());
	application.output('is hidden: ' + f.isHidden());
	application.output('can read: ' + f.canRead());
	application.output('can write: ' + f.canWrite());
	application.output('last modified: ' + f.lastModified());
	application.output('name: ' + f.getName());
	application.output('path: ' + f.getPath());
	application.output('absolute path: ' + f.getAbsolutePath());
	application.output('content type: ' + f.getContentType());
	application.output('size: ' + f.size());
}
else {
	application.output('File/folder not found.');
}

isDirectory()

Returns true if the file is a directory - works on remote files too.

Returns: Boolean True if the file is a directory; false otherwise (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('./big.jpg');
// or for a remote file:
// var f = plugins.convertToRemoteJSFile('/images/big.jpg');
if (f && f.exists()) {
	application.output('is absolute: ' + f.isAbsolute());
	application.output('is dir: ' + f.isDirectory());
	application.output('is file: ' + f.isFile());
	application.output('is hidden: ' + f.isHidden());
	application.output('can read: ' + f.canRead());
	application.output('can write: ' + f.canWrite());
	application.output('last modified: ' + f.lastModified());
	application.output('name: ' + f.getName());
	application.output('path: ' + f.getPath());
	application.output('absolute path: ' + f.getAbsolutePath());
	application.output('content type: ' + f.getContentType());
	application.output('size: ' + f.size());
}
else {
	application.output('File/folder not found.');
}

isFile()

Returns true if the file is a file and not a regular file - works on remote files too.

Returns: Boolean True if the file is a regular file; false otherwise (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('./big.jpg');
// or for a remote file:
// var f = plugins.convertToRemoteJSFile('/images/big.jpg');
if (f && f.exists()) {
	application.output('is absolute: ' + f.isAbsolute());
	application.output('is dir: ' + f.isDirectory());
	application.output('is file: ' + f.isFile());
	application.output('is hidden: ' + f.isHidden());
	application.output('can read: ' + f.canRead());
	application.output('can write: ' + f.canWrite());
	application.output('last modified: ' + f.lastModified());
	application.output('name: ' + f.getName());
	application.output('path: ' + f.getPath());
	application.output('absolute path: ' + f.getAbsolutePath());
	application.output('content type: ' + f.getContentType());
	application.output('size: ' + f.size());
}
else {
	application.output('File/folder not found.');
}

isHidden()

Returns true if the file is hidden (a file system attribute) - works on remote files too.

Returns: Boolean True if the file is hidden; false otherwise (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('./big.jpg');
// or for a remote file:
// var f = plugins.convertToRemoteJSFile('/images/big.jpg');
if (f && f.exists()) {
	application.output('is absolute: ' + f.isAbsolute());
	application.output('is dir: ' + f.isDirectory());
	application.output('is file: ' + f.isFile());
	application.output('is hidden: ' + f.isHidden());
	application.output('can read: ' + f.canRead());
	application.output('can write: ' + f.canWrite());
	application.output('last modified: ' + f.lastModified());
	application.output('name: ' + f.getName());
	application.output('path: ' + f.getPath());
	application.output('absolute path: ' + f.getAbsolutePath());
	application.output('content type: ' + f.getContentType());
	application.output('size: ' + f.size());
}
else {
	application.output('File/folder not found.');
}

lastModified()

Returns the time/date of the last modification on the file - works on remote files too.

Returns: Date The date and time of the last modification to the file (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('./big.jpg');
// or for a remote file:
// var f = plugins.convertToRemoteJSFile('/images/big.jpg');
if (f && f.exists()) {
	application.output('is absolute: ' + f.isAbsolute());
	application.output('is dir: ' + f.isDirectory());
	application.output('is file: ' + f.isFile());
	application.output('is hidden: ' + f.isHidden());
	application.output('can read: ' + f.canRead());
	application.output('can write: ' + f.canWrite());
	application.output('last modified: ' + f.lastModified());
	application.output('name: ' + f.getName());
	application.output('path: ' + f.getPath());
	application.output('absolute path: ' + f.getAbsolutePath());
	application.output('content type: ' + f.getContentType());
	application.output('size: ' + f.size());
}
else {
	application.output('File/folder not found.');
}

list()

Returns an array of strings naming the files and directories located inside the file, if the file is a directory - works on remote files too.

Returns: Array An array of file and directory names located inside this directory (works on remote files too).

Sample

var d = plugins.file.convertToJSFile('plugins');
// or for a remote file:
// var d = plugins.convertToRemoteJSFile('/plugins');
var names = d.list();
application.output('Names:');
for (var i=0; i<names.length; i++)
	application.output(names[i]);
var files = d.listFiles();
application.output('Absolute paths:');
for (var i=0; i<files.length; i++)
	application.output(files[i].getAbsolutePath());

listFiles()

Returns an array of JSFiles naming the files and directories located inside the file, if the file is a directory - works on remote files too.

Returns: Array An array of JSFile instances representing files and directories located inside this directory (works on remote files too).

Sample

var d = plugins.file.convertToJSFile('plugins');
// or for a remote file:
// var d = plugins.convertToRemoteJSFile('/plugins');
var names = d.list();
application.output('Names:');
for (var i=0; i<names.length; i++)
	application.output(names[i]);
var files = d.listFiles();
application.output('Absolute paths:');
for (var i=0; i<files.length; i++)
	application.output(files[i].getAbsolutePath());

mkdir()

Creates a directory on disk if possible. Returns true if a new directory was created - for remote, use the streamFilesToServer to create the directory instead.

Returns: Boolean True if the directory was successfully created; false otherwise.

Sample

var f = plugins.file.convertToJSFile('one/two/three/four');
f.mkdirs(); // Create all four levels of folders in one step.
var g = plugins.file.convertToJSFile('one/two/three/four/five');
g.mkdir(); // This will work because all parent folders are already created.

mkdirs()

Creates a directory on disk, together with all its parent directories, if possible. Returns true if the hierarchy of directories is created - for remote, use the streamFilesToServer to create the directories instead.

Returns: Boolean True if the hierarchy of directories was successfully created; false otherwise.

Sample

var f = plugins.file.convertToJSFile('one/two/three/four');
f.mkdirs(); // Create all four levels of folders in one step.
var g = plugins.file.convertToJSFile('one/two/three/four/five');
g.mkdir(); // This will work because all parent folders are already created.

renameTo(destination)

Renames the file to a different name. Returns true if the file could be renamed - works on remote files too.

Parameters

• Object destination ;

Returns: Boolean True if the file was successfully renamed; false otherwise (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('story.txt');
f.renameTo('otherstory.txt');
// or for a remote file:
// var f = plugins.convertToRemoteJSFile('/story.txt');
// f.renameTo('/otherstory.txt');

setBytes(bytes)

Set the content of the file (local or remote) to the bytes provided Will not create a new file if one doesn't exist

Parameters

• Array bytes the data

Returns: Boolean true if the operation worked

Sample

var file = plugins.file.convertToJSFile('/pathTo/file.jpg');
// or for a remote file:
// var file = plugins.file.convertToRemoteJSFile('/remotePathTo/file.jpg');
var success = file.setBytes(blobDataProvider, true);

setBytes(bytes, createFile)

Set the content of the file (local or remote) to the bytes provided

Parameters

• Array bytes the data
• Boolean createFile true to create a file if it doesn't exist

Returns: Boolean true if the operation worked

Sample

var file = plugins.file.convertToJSFile('/pathTo/file.jpg');
// or for a remote file:
// var file = plugins.file.convertToRemoteJSFile('/remotePathTo/file.jpg');
var success = file.setBytes(blobDataProvider, true);

setLastModified(date)

Sets the date/time of the last modification on the file.

Parameters

• Object date ;

Returns: Boolean True if the last modification date/time was successfully set; false otherwise.

Sample

var f = plugins.file.convertToJSFile('story.txt');
f.createNewFile();
// Make the file look old.
f.setLastModified(new Date(1999, 5, 21));

setReadOnly()

Sets the readonly attribute of the file/directory. Returns true on success.

Returns: Boolean True if the readonly attribute was successfully set; false otherwise.

Sample

var f = plugins.file.convertToJSFile('invoice.txt');
plugins.file.writeTXTFile(f, 'important data that should not be changed');
f.setReadOnly();

size()

Returns the size in bytes of the file. Returns 0 if the file does not exist on disk - works on remote files too.

Returns: Number The size of the file in bytes; returns 0 if the file does not exist (works on remote files too).

Sample

var f = plugins.file.convertToJSFile('./big.jpg');
// or for a remote file:
// var f = plugins.convertToRemoteJSFile('/images/big.jpg');
if (f && f.exists()) {
	application.output('is absolute: ' + f.isAbsolute());
	application.output('is dir: ' + f.isDirectory());
	application.output('is file: ' + f.isFile());
	application.output('is hidden: ' + f.isHidden());
	application.output('can read: ' + f.canRead());
	application.output('can write: ' + f.canWrite());
	application.output('last modified: ' + f.lastModified());
	application.output('name: ' + f.getName());
	application.output('path: ' + f.getPath());
	application.output('absolute path: ' + f.getAbsolutePath());
	application.output('content type: ' + f.getContentType());
	application.output('size: ' + f.size());
}
else {
	application.output('File/folder not found.');
}

---