Resources Module

Provides file access for workspace and file system resources. Methods accepting location objects can deal with String, URI, IFile and File instances.

Constants

Constant Description
APPEND Access modifier for append mode (4).
READ Access modifier for read mode (1).
WRITE Access modifier for write mode (2).

Method Overview

Method Description
closeFile() Close a file.
copyFile() Copies a file from location to targetLocation.
createFile() Create a new file in the workspace or the file system.
createFolder() Create a new folder in the workspace or the file system.
createProblemMarker() Create a problem marker on a file resource.
createProject() Create a new workspace project.
deleteFile() Delete a file.
deleteFolder() Delete a folder recursively.
deleteProject() Delete a project from the workspace.
fileExists() Verifies that a specific file exists.
findFiles() Return files matching a certain pattern.
getChecksum() Get an MD5 checksum over a readable resource.
getFile() Get a workspace or file system file.
getProject() Get a project instance.
getWorkspace() Get the workspace root.
importProject() Imports a project into the current workspace.
linkProject() Links a project into the current workspace.
openFile() Opens a file from the workspace or the file system.
readFile() Read data from a file.
readLine() Read a single line from a file.
readStream() Read from an InputStream into a string.
refreshResource() Refresh a given resource and all its child elements.
showFileSelectionDialog() Opens a file dialog.
showFolderSelectionDialog() Opens a dialog box which allows the user to select a container (project or folder).
unzip() Unzip a zip file to the provided target location.
writeFile() Write data to a file.
writeLine() Write a line of data to a file.
zip() Create or update a zip file with given resources.

Methods

closeFile

void closeFile(IFileHandle handle)

Close a file. Releases system resources bound by an open file.

handle
handle to be closed

copyFile

void copyFile(Object sourceLocation, Object targetLocation) throws IOException

Copies a file from location to targetLocation.

sourceLocation
file location, file handle or file instance for the source object
targetLocation
file location, file handle or file instance for the target object
IOException
problems on file access

createFile

Object createFile(Object location) throws IOException

Create a new file in the workspace or the file system.

location
file location

IFile, File or null in case of error

IOException
problems on file access

createFolder

Object createFolder(Object location) throws IOException

Create a new folder in the workspace or the file system.

location
folder location

IFolder or File instance

IOException
if this method fails. Reasons include:
  • This resource already exists in the workspace.
  • The workspace contains a resource of a different type at the same path as this resource.
  • The parent of this resource does not exist.
  • The parent of this resource is a project that is not open.
  • The parent contains a resource of a different type at the same path as this resource.
  • The parent of this resource is virtual, but this resource is not.
  • The name of this resource is not valid (according to IWorkspace.validateName).
  • The corresponding location in the local file system is occupied by a file (as opposed to a directory).
  • The corresponding location in the local file system is occupied by a folder and force is false.
  • Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

createProblemMarker

void createProblemMarker(String severity, Object location, int lineNumber, String message, [String type], [boolean permanent]) throws IOException

Create a problem marker on a file resource.

severity
one of error/warning/info
location
file resource to create marker for
lineNumber
line number to set marker on
message
message to be added to the marker
type
marker type to create, needs to match an existing typeOptional: defaults to <org.eclipse.core.resources.problemmarker>.
permanent
true for permanent markers, false for temporary markersOptional: defaults to <ru>.
IOException
when marker cannot be created

createProject

IProject createProject(String name) throws IOException

Create a new workspace project. Will create a new project if it not already exists. In case the project already exists, the existing instance will be returned.

name
name of project to create

project instance

IOException
when project creation fails

deleteFile

void deleteFile(Object location) throws IOException

Delete a file. Does nothing if location cannot be resolved to an existing file.

location
file to be deleted
IOException
on deletion errors

deleteFolder

void deleteFolder(Object location) throws IOException

Delete a folder recursively.

location
folder to be deleted
IOException
on deletion errors

deleteProject

void deleteProject(Object source) throws IOException

Delete a project from the workspace.

source
location or name of project to be deleted
IOException
on deletion errors

fileExists

boolean fileExists(Object location)

Verifies that a specific file exists.

location
file location to verify

true if file exists

findFiles

String[] findFiles(String pattern, [Object rootFolder], [boolean recursive]) throws IOException

Return files matching a certain pattern.

pattern
search pattern: use * and ? as wildcards. If the pattern starts with '^' then a regular expression can be used.
rootFolder
root folder to start your search from. null for workspace rootOptional: defaults to <rg.eclipse.ease.modules.ScriptParameter.nul>.
recursive
searches subfolders when set to trueOptional: defaults to <ru>.

An array of all matching file locations

IOException
when search fails

getChecksum

String getChecksum(Object location) throws IOException

Get an MD5 checksum over a readable resource.

location
location of resource to create checksum for

file hash as hex encoded string

IOException
when resource cannot be read

getFile

Object getFile(String location, [boolean exists]) throws FileNotFoundException

Get a workspace or file system file. Resolves relative and absolute file locations. Relative files are resolved against the current script file. If exists is false this method also returns files that do not exist yet. If true only existing instances are returned.

location
file location/path to resolve
exists
whether the resolved file needs to existOptional: defaults to <ru>.

resolved IFile or File instance

FileNotFoundException
when file does not exist and exists is true
getFile("workspace://my project/some folder/file.txt")
to get the file.txt resource from the workspace
getFile("project://some folder/file.txt")
to get the file.txt resource as a project relative path

getProject

IProject getProject(String name)

Get a project instance.

name
project name

project or null

getWorkspace

IWorkspaceRoot getWorkspace()

Get the workspace root.

workspace root

importProject

IProject importProject(Object location) throws IOException

Imports a project into the current workspace. The project needs to be available on the file system and needs to be unpacked. Zipped projects cannot be imported.

location
location of project folder (needs to contain .project file)

project instance, throws otherwise

IOException
on any import errors

linkProject

IProject linkProject(Object location) throws IOException

Links a project into the current workspace. Does not copy resources to the workspace.

location
location of project folder (needs to contain .project file)

linked project, throws otherwise

IOException
when project location cannot be read/linked

openFile

IFileHandle openFile(Object location, [int mode], [boolean autoClose]) throws IOException

Opens a file from the workspace or the file system. If the file does not exist and we open it for writing, the file is created automatically.

location
file location
mode
one of READ, WRITE, APPENDOptional: defaults to <1>.
autoClose
automatically close resource when script engine is terminatedOptional: defaults to <ru>.

file handle instance to be used for file modification commands

IOException
problems on file access

readFile

String readFile(Object location, [int bytes]) throws IOException

Read data from a file. To repeatedly read from a file retrieve a IFileHandle first using openFile() and use the handle for location.

location
file location, file handle or file instance
bytes
amount of bytes to read (-1 for whole file)Optional: defaults to <-1>.

file data or null if EOF is reached

IOException
problems on file access

readLine

String readLine(Object location) throws IOException

Read a single line from a file. To repeatedly read from a file retrieve a IFileHandle first using openFile() and use the handle for location.

location
file location, file handle or file instance

line of text or null if EOF is reached

IOException
problems on file access

readStream

String readStream(InputStream input) throws IOException

Read from an InputStream into a string. Consumes an InputStream and stores all available data in a string. Usually a stream is only readable once.

input
input stream to read from

string content of stream.

IOException
on read error on the stream

refreshResource

void refreshResource(Object resource) throws IOException

Refresh a given resource and all its child elements.

resource
IFile, IFolder, IProject or workspace root to update
IOException
if this method fails. Reasons include:
  • Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.
refreshResource(getProject("my project"))
to update the project and all its subfolders

showFileSelectionDialog

String showFileSelectionDialog([Object rootFolder], [int type], [String title], [String message]) throws IOException

Opens a file dialog. Depending on the rootFolder a workspace dialog or a file system dialog will be used. If the folder cannot be located, the workspace root folder is used by default. When type is set to WRITE or APPEND a save dialog will be shown instead of the default open dialog.

rootFolder
root folder path to useOptional: defaults to <rg.eclipse.ease.modules.ScriptParameter.nul>.
type
dialog type to use (WRITE/ APPEND for save dialog, READ for open dialog)Optional: defaults to <0>.
title
dialog titleOptional: defaults to <null>.
message
dialog messageOptional: defaults to <null>.

full path to selected file either as absolute file system path or as absolute workspace URI. Returns null when the dialog is cancelled by the user.

IOException
when root folder cannot be found

showFolderSelectionDialog

String showFolderSelectionDialog([Object rootFolder], [String title], [String message]) throws IOException

Opens a dialog box which allows the user to select a container (project or folder). Workspace paths will always display the workspace as root object.

rootFolder
root folder to display: for workspace paths this will set the default selectionOptional: defaults to <rg.eclipse.ease.modules.ScriptParameter.nul>.
title
dialog titleOptional: defaults to <null>.
message
dialog messageOptional: defaults to <null>.

full path to selected folder either as absolute file system path or as absolute workspace URI. Returns null when the dialog is cancelled by the user.

IOException
when root folder cannot be found

unzip

Object unzip(Object zipLocation, Object targetLocation) throws IOException

Unzip a zip file to the provided target location.

zipLocation
zip file to unzip
targetLocation
folder to unzip to

target location reference

IOException
when zip file cannot be unzipped

writeFile

IFileHandle writeFile(Object location, Object data, [int mode], [boolean autoClose]) throws IOException

Write data to a file. Files that do not exist yet will be created automatically. After the write operation the file remains open. It needs to be closed explicitly using the closeFile() command.

location
file location
data
data to be written
mode
write mode (WRITE/APPEND)Optional: defaults to <2>.
autoClose
automatically close resource when script engine is terminatedOptional: defaults to <ru>.

file handle to continue write operations

IOException
problems on file access

writeLine

IFileHandle writeLine(Object location, String data, [int mode], [boolean autoClose]) throws IOException

Write a line of data to a file. Files that do not exist yet will be created automatically. After the write operation the file remains open. It needs to be closed explicitly using the closeFile() command.

location
file location
data
data to be written
mode
write mode (WRITE/APPEND)Optional: defaults to <2>.
autoClose
automatically close resource when script engine is terminatedOptional: defaults to <ru>.

file handle to continue write operations

IOException
problems on file access

zip

Object zip(Object sourceLocation, Object zipLocation) throws IOException

Create or update a zip file with given resources.

sourceLocation
source folder/file to zip
zipLocation
zip file to use

zip file reference

IOException
when zip file cannot be created/appended