org.eclipse.ease.modules.platform

## Class ResourcesModule

- java.lang.Object
- - org.eclipse.ease.modules.AbstractScriptModule
  - - org.eclipse.ease.modules.platform.ResourcesModule

All Implemented Interfaces:
  IScriptModule

    public class ResourcesModule
    extends AbstractScriptModule

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

### Field Summary

Fields
`static int` `APPEND` Access modifier for append mode (4).
`static String` `MODULE_ID` Module identifier.
`static int` `READ` Access modifier for read mode (1).
`static int` `WRITE` Access modifier for write mode (2).

### Constructor Summary

Constructors
Constructor and Description
`ResourcesModule()`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`static void` `closeFile(IFileHandle handle)` Close a file.
`void` `copyFile(Object sourceLocation, Object targetLocation)` Copies a file from location to targetLocation.
`Object` `createFile(Object location)` Create a new file in the workspace or the file system.
`Object` `createFolder(Object location)` Create a new folder in the workspace or the file system.
`void` `createProblemMarker(String severity, Object location, int lineNumber, String message, String type, boolean permanent)` Create a problem marker on a file resource.
`static IProject` `createProject(String name)` Create a new workspace project.
`void` `deleteFile(Object source)` Delete a file from the workspace or local file system.
`void` `deleteFolder(Object source)` Delete a folder from the workspace or local file system.
`void` `deleteProject(Object source)` Delete a project from the workspace.
`boolean` `fileExists(Object location)` Verifies that a specific file exists.
`Object[]` `findFiles(String pattern, Object rootFolder, boolean recursive)` Return files matching a certain pattern.
`Object` `getFile(String location, boolean exists)` Get a workspace or file system file.
`static IProject` `getProject(String name)` Get a project instance.
`static IWorkspaceRoot` `getWorkspace()` Get the workspace root.
`boolean` `linkProject(String location)` Links a project into the current workspace.
`IFileHandle` `openFile(Object location, int mode)` Opens a file from the workspace or the file system.
`String` `readFile(Object location, int bytes)` Read data from a file.
`String` `readLine(Object location)` Read a single line from a file.
`String` `readStream(InputStream input)` Read from an InputStream into a string.
`void` `refreshResource(IResource resource)` Refresh a given resource and all its child elements.
`String` `showFileSelectionDialog(Object rootFolder, int type, String title, String message)` Opens a file dialog.
`String` `showFolderSelectionDialog(Object rootFolder, String title, String message)` Opens a dialog box which allows the user to select a container (project or folder).
`IFileHandle` `writeFile(Object location, Object data, int mode)` Write data to a file.
`IFileHandle` `writeLine(Object location, String data, int mode)` Write a line of data to a file.

### Methods inherited from class org.eclipse.ease.modules.AbstractScriptModule

`getScriptEngine, initialize`

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### MODULE_ID

    public static final String MODULE_ID

Module identifier.

See Also:
  Constant Field Values

#### READ

    public static final int READ

Access modifier for read mode (1).

See Also:
  Constant Field Values

#### WRITE

    public static final int WRITE

Access modifier for write mode (2).

See Also:
  Constant Field Values

#### APPEND

    public static final int APPEND

Access modifier for append mode (4).

See Also:
  Constant Field Values

### Constructor Detail

#### ResourcesModule

    public ResourcesModule()

### Method Detail

#### getWorkspace

    public static IWorkspaceRoot getWorkspace()

Get the workspace root.

Returns:
  workspace root

#### getProject

    public static IProject getProject(String name)

Get a project instance.

Parameters:
  `name` - project name
Returns:
  project or `null`

#### getFile

    public Object getFile(String location,
                          @ScriptParameter(defaultValue="true")
                          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.

Parameters:
  `location` - file location/path to resolve
  `exists` - whether the resolved file needs to exist
Returns:
  resolved `IFile` or `File` instance

#### createProject

    public static IProject createProject(String name)

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

Parameters:
  `name` - name or project to create
Returns:
  `null` or project

#### createFolder

    public Object createFolder(Object location)
                        throws CoreException

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

Parameters:
  `location` - folder location
Returns:
  `IFolder`, `File` or `null` in case of error
Throws:
  `CoreException`

#### createFile

    public Object createFile(Object location)
                      throws Exception

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

Parameters:
  `location` - file location
Returns:
  `IFile`, `File` or `null` in case of error
Throws:
  `Exception` - problems on file access

#### openFile

    public IFileHandle openFile(Object location,
                                @ScriptParameter(defaultValue="1")
                                int mode)
                         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.

Parameters:
  `location` - file location
  `mode` - one of , ,
Returns:
  file handle instance to be used for file modification commands
Throws:
  `Exception` - problems on file access

#### fileExists

    public boolean fileExists(Object location)

Verifies that a specific file exists.

Parameters:
  `location` - file location to verify
Returns:
  `true` if file exists

#### closeFile

    public static void closeFile(IFileHandle handle)

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

Parameters:
  `handle` - handle to be closed

#### readFile

    public String readFile(Object location,
                           @ScriptParameter(defaultValue="-1")
                           int bytes)
                    throws Exception

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

Parameters:
  `location` - file location, file handle or file instance
  `bytes` - amount of bytes to read (-1 for whole file)
Returns:
  file data or `null` if EOF is reached
Throws:
  `Exception` - problems on file access

#### copyFile

    public void copyFile(Object sourceLocation,
                         Object targetLocation)
                  throws Exception

Copies a file from location to targetLocation.

Parameters:
  `location` - file location, file handle or file instance
  `targetLocation` - file location, file handle or file instance
Throws:
  `Exception` - problems on file access

#### deleteFile

    public void deleteFile(Object source)
                    throws CoreException

Delete a file from the workspace or local file system.

Parameters:
  `source` - file to be deleted
Throws:
  `CoreException` - on deletion errors

#### deleteFolder

    public void deleteFolder(Object source)
                      throws CoreException

Delete a folder from the workspace or local file system.

Parameters:
  `source` - folder to be deleted
Throws:
  `CoreException` - on deletion errors

#### deleteProject

    public void deleteProject(Object source)
                       throws CoreException

Delete a project from the workspace.

Parameters:
  `source` - project to be deleted
Throws:
  `CoreException` - on deletion errors

#### readLine

    public String readLine(Object location)
                    throws Exception

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

Parameters:
  `location` - file location, file handle or file instance
Returns:
  line of text or `null` if EOF is reached
Throws:
  `Exception` - problems on file access

#### writeFile

    public IFileHandle writeFile(Object location,
                                 Object data,
                                 @ScriptParameter(defaultValue="2")
                                 int mode)
                          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 command

Parameters:
  `location` - file location
  `data` - data to be written
  `mode` - write mode (/)
Returns:
  file handle to continue write operations
Throws:
  `Exception` - problems on file access

#### writeLine

    public IFileHandle writeLine(Object location,
                                 String data,
                                 @ScriptParameter(defaultValue="2")
                                 int mode)
                          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.

Parameters:
  `location` - file location
  `data` - data to be written
  `mode` - write mode (/)
Returns:
  file handle to continue write operations
Throws:
  `Exception` - problems on file access

#### showFileSelectionDialog

    public String showFileSelectionDialog(@ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                          Object rootFolder,
                                          @ScriptParameter(defaultValue="0")
                                          int type,
                                          @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                          String title,
                                          @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                          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 or a save dialog will be shown instead of the default open dialog.

Parameters:
  `rootFolder` - root folder path to use
  `type` - dialog type to use (/ for save dialog, other for open dialog)
  `title` - dialog title
  `message` - dialog message
Returns:
  full path to selected file

#### showFolderSelectionDialog

    public String showFolderSelectionDialog(@ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                            Object rootFolder,
                                            @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                            String title,
                                            @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                                            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.

Parameters:
  `rootFolder` - root folder to display: for workspace paths this will set the default selection
  `title` - dialog title
  `message` - dialog message
Returns:
  path to selected folder

#### findFiles

    public Object[] findFiles(String pattern,
                              @ScriptParameter(defaultValue="org.eclipse.ease.modules.ScriptParameter.null")
                              Object rootFolder,
                              @ScriptParameter(defaultValue="true")
                              boolean recursive)

Return files matching a certain pattern.

Parameters:
  `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 root
  `recursive` - searches subfolders when set to `true`
Returns:
  An array of all matching files

#### linkProject

    public boolean linkProject(String location)

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

Parameters:
  `location` - location of project (needs to contain .project file)
Returns:
  link result

#### refreshResource

    public void refreshResource(IResource resource)
                         throws CoreException

Refresh a given resource and all its child elements.

Parameters:
  `resource` - `IFile`, `IFolder`, `IProject` or workspace root to update
Throws:
  `CoreException` - if this method fails. Reasons include:
  - Resource changes are disallowed during certain types of resource change event notification. See `IResourceChangeEvent` for more details.

#### readStream

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

Parameters:
  `input` - input stream to read from
Returns:
  string content of stream.
Throws:
  `IOException` - on read error on the stream

#### createProblemMarker

    public void createProblemMarker(String severity,
                                    Object location,
                                    int lineNumber,
                                    String message,
                                    @ScriptParameter(defaultValue="org.eclipse.core.resources.problemmarker")
                                    String type,
                                    @ScriptParameter(defaultValue="true")
                                    boolean permanent)
                             throws CoreException

Create a problem marker on a file resource.

Parameters:
  `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 type
  `permanent` - `true` for permanent markers, `false` for temporary markers
Throws:
  `CoreException` - when marker cannot be created