Package org.talend.transform.runtime.api

# Interface RuntimeEngine

public interface RuntimeEngine
The interface that controls the runtime of the ODT. This interface allows you to locate a MapRuntime object which can then be executed.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`CONTENT_FILE`
TDM file located in `TDM_FOLDER`, which list all the project archive names which contain TDM materials (structure, map etc)
`static final String`
`CONTENT_FILE_PATH`
TDM file path located in runtime jar, which list all the project archive names which contain TDM materials (structure, map etc)
`static final int`
`DEFAULT_CACHE_TIMEOUT`
`static final String`
`LOG_ALL`
Full debug logging.
`static final String`
`LOG_DEST_CONSOLE`
Log destination console.
`static final String`
`LOG_FREQUENT`
Logs per transformation execution (message).
`static final String`
`LOG_INFREQUENT`
Logs warnings and higher as well as certain startup and shutdown events.
`static final String`
`LOG_PROJECT_MISS`
Log events related to not being able to find a project archive.
`static final String`
`TDM_FOLDER`
TDM Folder name which appear in runtime jar, and contains all materials to run a map.

## Method Summary

Modifier and Type
Method
Description
`String`
`addProjectArchive(File projectArchiveFile)`
Adds the project contained in the specified archive file (zip file) to the workspace.
`void`
`addProjectDevLink(String project)`
Adds the specified project which exists in a development workspace pointed to by the `ODT_DEV_WORKSPACE` system property (which may be a file path or `file` URL).
`Set<String>`
`addProjectsFromClasspath()`
Add all projects contained in classpath under __tdm/ folder into the workspace.
`String`
`addProjectUri(URI projectArchiveUri)`
Adds the project contained in the specified archive to the workspace.
`void`
`addSampleData(String path, Object sampleData, String encoding)`
Adds a sample data object to a project.
`void`
`close()`
Close the runtime.
`boolean`
`deleteProject(String projectName)`
Removes the specified project from the workspace.
`Set<String>`
`getAvailableRepNames()`
Get a list of available Representation names.
`int`
`getCachingTimeout()`
Get the value that an item is allowed in the lookup cache in seconds.
`String`
`getCurrentProjectName()`
Returns the name of the current project, if there is a current project.
`String`
`getExecutionStatusMap()`
Returns the path of the map set to process the `ExecutionStatus`.
`MapExecutionContext`
`getMapExecutionContext()`
Returns a map execution context which is optionally used when executing a map.
`MapRuntime`
`getMapRuntime(String path)`
Returns the MapRuntime associated with the specified map path.
`MapRuntime`
`getMatchingMapRuntime(String path, Set<String> projects)`
If path is absolute, check this path is valid against projects that have been installed previously by addProjectsFromClasspath().
`InputStream`
`getObjectStream(String path)`
Used to read an object from a project.
`long[]`
`getStructRecordSizes(String path)`
Calculates the minimum and maximum size of a structure's record (in bytes).
`StructRuntime`
`getStructRuntime(String path, String sourceRepName, String resultRepName)`
Returns the StructRuntime associated with the specified structure path and input/output representations.
`int`
`getThreadCountCurrent()`
Returns the number of concurrently execution threads for maps.
`int`
`getThreadCountHighWater()`
Returns the highest number of threads devoted to concurrent map execution that has so far occurred.
`int`
`getThreadCountMax()`
Returns the maximum number of threads available for map execution.
`void`
`initRuntimeApi(int options)`
For internal use only.
`boolean`
`isCaching()`
Returns true if functions that read external values like DatabaseLookup and GetBytesUrl should cache their results.
`boolean`
`isClosed()`
For internal use only.
`boolean`
`isProjectLoaded(String projectName)`
Returns true if the project is exists in the workspace.
`void`
`setCaching(boolean cache)`
Set to true if functions that read external values like DatabaseLookup and GetBytesUrl should cache their results.
`void`
`setCachingTimeout(int seconds)`
Set the value that an item is allowed in the lookup cache in seconds.
`void`
`setCurrentProject(String projectName)`
Sets the current project in the runtime to the specified project name.
`void`
`setExecutionStatusMap(String path)`
Sets the map that is to be executed to process the `ExecutionStatus` from all maps run with this runtime.
`void`
`setLogging(String content, String dest)`
Turns on logging according to the the specified logging properties.
`void`
`setThreadCountMax(int count)`
Sets the maximum number of threads for this runtime devoted to concurrent execution of maps.
`void`
`shutdownRuntimeApi()`
For internal use only.

## Field Details

### DEFAULT_CACHE_TIMEOUT

static final int DEFAULT_CACHE_TIMEOUT

See Also:
  - Constant Field Values

### LOG_INFREQUENT

static final String LOG_INFREQUENT
Logs warnings and higher as well as certain startup and shutdown events. For `setLogging(String, String)`.

See Also:
  - Constant Field Values

### LOG_FREQUENT

static final String LOG_FREQUENT
Logs per transformation execution (message). For `setLogging(String, String)`.

See Also:
  - Constant Field Values

### LOG_PROJECT_MISS

static final String LOG_PROJECT_MISS
Log events related to not being able to find a project archive. Used for diagnostic purposes For `setLogging(String, String)`.

See Also:
  - Constant Field Values

### LOG_ALL

static final String LOG_ALL
Full debug logging. Quite a lot of output. For `setLogging(String, String)`.

See Also:
  - Constant Field Values

### LOG_DEST_CONSOLE

static final String LOG_DEST_CONSOLE
Log destination console. For `setLogging(String, String)`.

See Also:
  - Constant Field Values

### TDM_FOLDER

static final String TDM_FOLDER
TDM Folder name which appear in runtime jar, and contains all materials to run a map.

See Also:
  - Constant Field Values

### CONTENT_FILE

static final String CONTENT_FILE
TDM file located in `TDM_FOLDER`, which list all the project archive names which contain TDM materials (structure, map etc)

See Also:
  - Constant Field Values

### CONTENT_FILE_PATH

static final String CONTENT_FILE_PATH
TDM file path located in runtime jar, which list all the project archive names which contain TDM materials (structure, map etc)

See Also:
  - `TDM_FOLDER`
  - `CONTENT_FILE`
  - Constant Field Values

## Method Details

### setCurrentProject

void setCurrentProject(String projectName)
Sets the current project in the runtime to the specified project name. This is used to allow the project name not to be specified when calling `getMapRuntime(String)`

Parameters:
  `projectName` - the name of the project

### getCurrentProjectName

String getCurrentProjectName()
Returns the name of the current project, if there is a current project.

Returns:
  the project name, null if no current project.

### addProjectArchive

String addProjectArchive(File projectArchiveFile) throws IOException, ZipException
Adds the project contained in the specified archive file (zip file) to the workspace. Does not copy the objects from the archive in into the workspace, but references the objects directly from the archive file.

Parameters:
  `projectArchiveFile` - A File object that refers to the project archive zip file.
Returns:
  the project name
Throws:
  `IOException`
  `ZipException`

### addProjectUri

String addProjectUri(URI projectArchiveUri) throws IOException, ZipException, URISyntaxException
Adds the project contained in the specified archive to the workspace. Does not copy the objects from the archive in into the workspace, but references the objects directly from the archive.

Parameters:
  `projectArchiveUri` - the URI that specifies the location of the project archive (zip file).

  In addition to the `file` URL scheme some special schemes are supported as described below. No other schemes are presently supported.

  The `classpath` scheme accesses a project zip file that is specified on the classpath. Note that in an OSGi environment this should not be used since the classpath is associated with a specific bundle. For OSGi, use the `platform` scheme below to get the archive from the desired bundle.

  The `platform` scheme can be used to access projects in OSGi bundles. To access an object in a bundle, specify `platform:/plugin/<bundleId>/<path/to/object>` , where `<bundleId>` is the name of the bundle, and `</path/to/object>` is the path to the archive object (the zip file as stored in the bundle) within the specified bundle. The `platform` scheme is identical to the Eclipse `platform` scheme and uses the Eclipse runtime mechanism to resolve it.

Throws:
  `IOException`
  `ZipException`
  `URISyntaxException`

### addProjectsFromClasspath

Set<String> addProjectsFromClasspath() throws IOException, ZipException, URISyntaxException
Add all projects contained in classpath under __tdm/ folder into the workspace. Scan the classpath to look for __TDM/.content file, parse it and for each projects archives names, it will call addProjectURI(__tdm/<project archive name>).

Returns:
  list of projects archives names which have been added to the workspace or empty list if no project has been added or no __tdm/.content file have been discovered.
Throws:
  `IOException`
  `ZipException`
  `URISyntaxException`
See Also:
  - `getMatchingMapRuntime(String, Set)`

### addProjectDevLink

void addProjectDevLink(String project) throws IOException
Adds the specified project which exists in a development workspace pointed to by the `ODT_DEV_WORKSPACE` system property (which may be a file path or `file` URL). This is used when executing the runtime in the context of a designer and you wish to refer to a project in your development workspace.

Throws:
  `IOException`

### isProjectLoaded

boolean isProjectLoaded(String projectName)
Returns true if the project is exists in the workspace.

Parameters:
  `projectName` - the name of the project to check
Returns:
  true if the project exists

### deleteProject

boolean deleteProject(String projectName)
Removes the specified project from the workspace.

Parameters:
  `projectName` - the name of the project to delete
Returns:
  true if the project was successfully deleted, false if not

### getMapRuntime

MapRuntime getMapRuntime(String path)
Returns the MapRuntime associated with the specified map path.

Parameters:
  `path` - If the path begins with a "/" it is absolute and the full path of the map including the project. The first segment is the project, the second is {$link ObjectTypes.MAP}, and the rest is the path to the map. Example: "/MyProject/Maps/mypath/mymap"
  If the path does not begin with a "/" it is relative and the current project is used. The path contains the path to the map after the `ObjectTypes.MAP` portion. Example: "mypath/mymap".
Returns:
  a MapRuntime

### getMatchingMapRuntime

MapRuntime getMatchingMapRuntime(String path, Set<String> projects)
If path is absolute, check this path is valid against projects that have been installed previously by addProjectsFromClasspath(). In case some installed projects where timestamped, it will replace the non timestamped project name in the path, with the correct one otherwise it will keep the path as it is. In all case, this method will call getMapRuntime with the update (or not) path.

Parameters:
  `path` - the path to the map
  `projects` -
Returns:
  a MapRuntime
See Also:
  - `addProjectsFromClasspath()`

### getStructRuntime

StructRuntime getStructRuntime(String path, String sourceRepName, String resultRepName)
Returns the StructRuntime associated with the specified structure path and input/output representations.

Note that if the Structure was previously associated with a chosen Representation then, any parameters that were set on the Representation will take effect on `StructureRuntime#run`.

The Representations are identified by their names. You can use `getAvailableRepNames()` to retrieve a list of valid names.

Parameters:
  `path` - If the path begins with a "/" it is absolute and the full path of the structure including the project. The first segment is the project, the second is {$link ObjectTypes.STRUCT}, and the rest is the path to the structure. Example: "/MyProject/Structures/mypath/mystruct"
  If the path does not begin with a "/" it is relative and the current project is used. The path contains the path to the structure after the `ObjectTypes.STRUCT` portion. Example: "mypath/mystruct".
  `sourceRepName` - the Representation of the input data.
  `resultRepName` - The representation of the output data
Returns:
  the StructRuntime that can be used to run a conversion process

### getAvailableRepNames

Set<String> getAvailableRepNames()
Get a list of available Representation names.

Returns:
  a set of Representation names that can be used to identify a specific Representation. Set is in alphabetical order

### getStructRecordSizes

long[] getStructRecordSizes(String path)
Calculates the minimum and maximum size of a structure's record (in bytes).

This only applies to Structures with the following characteristics:

- All primitive elements must have defined minimum/maximum lengths different from -1
- All arrays (of primitives or complex types) must have defined minimum and maximum Occurs different from -1
- The Structure must not be recursive

In general Structures imported from positional representations such as Cobol are eligible.

The structure's record is an element identified like this:

- The user might have explicitly identified the Record using the notion of 'row'
- If the structure is made of a root with a single unbounded child, then that child is the record
- Otherwise the root itself is the record

Parameters:
  `path` - If the path begins with a "/" it is absolute and the full path of the structure including the project. The first segment is the project, the second is {$link ObjectTypes.STRUCT}, and the rest is the path to the structure. Example: "/MyProject/Structures/mypath/mystruct"
  If the path does not begin with a "/" it is relative and the current project is used. The path contains the path to the structure after the `ObjectTypes.STRUCT` portion. Example: "mypath/mystruct".
Returns:
  an array of 2 longs, the first one at index 0 is the minimum size of the structure, the second one at index 1 is the maximum size

### getMapExecutionContext

MapExecutionContext getMapExecutionContext()
Returns a map execution context which is optionally used when executing a map. Use the map execution context if you need to specify certain parameters for the map execution.

Returns:
  a MapExecutionContext

### setExecutionStatusMap

void setExecutionStatusMap(String path)
Sets the map that is to be executed to process the `ExecutionStatus` from all maps run with this runtime. This may be overridden either in the `MapRuntime` or `MapExecutionContext`.

Parameters:
  `path` - the path of the map to process the execution status. Follows the same path rules as getMapRuntime().

### getExecutionStatusMap

String getExecutionStatusMap()
Returns the path of the map set to process the `ExecutionStatus`. @see setExecutionStatusMap().

Returns:
  the path of the map

### getObjectStream

InputStream getObjectStream(String path)
Used to read an object from a project. This is typically used to get the contents of sample data objects (documents), but can be used to directly access any object (map, structure, etc).

Parameters:
  `path` - the fully qualified path of the object, for example /MyProject/Sample Data/MyStructure/MySampleDoc.xml. In general, you will need to add the ".xml" extension to the name of the object as it appears in the designer, as the objects are stored with that extension.
Returns:
  an InputStream, which must be closed after it is read.

### addSampleData

void addSampleData(String path, Object sampleData, String encoding) throws IOException, URISyntaxException
Adds a sample data object to a project. Note that the `ODT_DEV_WORKSPACE` System property must be set to be a the file path or a `file` URL of the workspace where the sample data is to be added.

Parameters:
  `path` - the fully qualified path of the sample data object, for example /MyProject/Sample Data/MyStructure/MySampleDoc.xml. The convention for the paths for the sample data is they are in the Sample Data folder and underneath that is the path to the structure (from the Structures folder).
  `sampleData` - the sample data, which could be a Java object (this will be serialized using XStream), a byte array which will be stored as binary data, or a String which will be stored as a text file.
  `encoding` - used only if the sampleData is a String, specifies the encoding used to write the String. If null, the current platform encoding is used.
Throws:
  `IOException`
  `URISyntaxException`

### setThreadCountMax

void setThreadCountMax(int count)
Sets the maximum number of threads for this runtime devoted to concurrent execution of maps. If a greater number of map executions is requested, they are queued until threads become available.

Parameters:
  `count` - the map number of threads

### getThreadCountMax

int getThreadCountMax()
Returns the maximum number of threads available for map execution.

Returns:
  the max number of threads.

### getThreadCountHighWater

int getThreadCountHighWater()
Returns the highest number of threads devoted to concurrent map execution that has so far occurred.

Returns:
  the high water number of threads.

### getThreadCountCurrent

int getThreadCountCurrent()
Returns the number of concurrently execution threads for maps.

Returns:
  the current number of threads executing maps.

### setLogging

void setLogging(String content, String dest)
Turns on logging according to the the specified logging properties. The property files are in the com.oaklandsw.transform.runtime/logprops folder. Some of the commonly used properties are defined as constants in this interface.

Parameters:
  `content` - the property file identifying the content to be logged, null if logging is to be turned off. See `LOG_FREQUENT`, `LOG_INFREQUENT`, and `LOG_ALL`.
  `dest` - the property file identifying the destination of the logging, null if logging is to be turned off. See `LOG_DEST_CONSOLE`.

### close

void close()
Close the runtime.

### setCaching

void setCaching(boolean cache)
Set to true if functions that read external values like DatabaseLookup and GetBytesUrl should cache their results.

Parameters:
  `cache` -

### isCaching

boolean isCaching()
Returns true if functions that read external values like DatabaseLookup and GetBytesUrl should cache their results.

Returns:
  true if caching is enabled.

### setCachingTimeout

void setCachingTimeout(int seconds)
Set the value that an item is allowed in the lookup cache in seconds. Zero means it's allowed forever.

Parameters:
  `seconds` -

### getCachingTimeout

int getCachingTimeout()
Get the value that an item is allowed in the lookup cache in seconds. Zero means it's allowed forever.

Returns:
  the number of seconds

### initRuntimeApi

void initRuntimeApi(int options)
For internal use only. Do not use this method as it's subject to change in a future release.

### isClosed

boolean isClosed()
For internal use only. Do not use this method as it's subject to change in a future release.

### shutdownRuntimeApi

void shutdownRuntimeApi()
For internal use only. If the RuntimeEngine is no more referenced, this method will completely close it and shutdown eclipse