# 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 from the workspace or local file system.
deleteFolder() | Delete a folder from the workspace or local file system.
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 Exception

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

Exception
  problems on file access

### createFile

Object createFile(Object location) throws Exception

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

location
  file location

IFile, File or `null` in case of error

Exception
  problems on file access

### createFolder

Object createFolder(Object location) throws CoreException

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

location
  folder location

IFolder, File or `null` in case of error

CoreException
  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 CoreException

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

CoreException
  when marker cannot be created

### createProject

IProject createProject(String name)

Create a new workspace project. Will create a new project if it not already exists. If creation fails, `null` is returned.

name
  name or project to create

`null` or project

### deleteFile

void deleteFile(Object source) throws CoreException

Delete a file from the workspace or local file system.

source
  file to be deleted

CoreException
  on deletion errors

### deleteFolder

void deleteFolder(Object source) throws CoreException

Delete a folder from the workspace or local file system.

source
  folder to be deleted

CoreException
  on deletion errors

### deleteProject

void deleteProject(Object source) throws CoreException

Delete a project from the workspace.

source
  project to be deleted

CoreException
  on deletion errors

### fileExists

boolean fileExists(Object location)

Verifies that a specific file exists.

location
  file location to verify

`true` if file exists

### findFiles

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

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 `true` Optional: defaults to <ru>.

An array of all matching files

### getChecksum

String getChecksum(Object location) throws NoSuchAlgorithmException, IOException

Get an MD5 checksum over a readable resource.

location
  location of resource to create checksum for

file hash as hex encoded string

NoSuchAlgorithmException
  when MD5 digest cannot be found
IOException
  when resource cannot be read

### getFile

Object getFile(String location, [boolean exists])

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

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 InvocationTargetException, InterruptedException, IOException, CoreException

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 (needs to contain .project file)

project instance, throws otherwise

InvocationTargetException
  on errors during the import
InterruptedException
  when import task got interrupted
IOException
  when project cannot be located on disk
CoreException
  when project description cannot be loaded from .project file

### linkProject

IProject linkProject(Object location) throws CoreException, IOException

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

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

linked project, throws otherwise

CoreException
  when project description cannot be loaded from .project file
IOException
  when project location cannot be read/linked

### openFile

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

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, APPEND Optional: 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

Exception
  problems on file access

### readFile

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

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

Exception
  problems on file access

### readLine

String readLine(Object location) throws Exception

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

Exception
  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 CoreException

Refresh a given resource and all its child elements.

resource
  IFile, IFolder, IProject or workspace root to update

CoreException
  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])

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, other for open dialog)Optional: defaults to <0>.
title
  dialog titleOptional: defaults to <null>.
message
  dialog messageOptional: defaults to <null>.

full path to selected file

### showFolderSelectionDialog

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

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

path to selected folder

### 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 Exception

Write data to a file. When not using an IFileHandle, previous file content will be overridden. Files that do not exist yet will be automatically created. 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

Exception
  problems on file access

### writeLine

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

Write a line of data to a file. When not using an IFileHandle, previous file content will be overridden. Files that do not exist yet will be automatically created.

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

Exception
  problems on file access

### zip

Object zip(Object sourceLocation, Object zipLocation) throws IOException, URISyntaxException

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
URISyntaxException
  when target location cannot be encoded correctly (possibly due to special characters)