Remote API Migration guide

Overview

In order to realize unified support of local and remote projects in DLTK we've added one major term - "environment". Environment provide an interface to access some machine's file system and allow unified execution of scripts, debuggers, etc.

Migration

Next is the short list of changes one should perform to support new environments api.

1. In former DLTK IPath object could contain workspace relative path or path in local file system. Since, we have added environments IPath can be full path including environment in addition to previous two cases. So, if path in concrete environment was device:/path then full path will be environment_id/device:/path. One can check if the IPath object contain full path, convert it to local or extract environment object by using EnvironmentPathUtils helper class.
2. External model elements (ExternalProjectFragment, ExternalScriptFolder and _ExternalSourceModule) is using IEnvironment and IFileHandle from org.eclipse.dltk.environment package to access file system. Constructors of this objects use full paths.
3. Instances of BuildpathEntry referencing external locations (external libraries and archives) should be created using full path. One can obtain full path by calling EnvironmentPathUtils.getFullPath(IEnvironment, IPath).
4. LibraryLocation class now using full paths too.
5. All occurrences of File class should be changed to IFileHandle. Usage of File should be avoided, cause it cannot be used to access remote machine. API of IFileHandle is similar to File's and have the same meaning. There are two options how IFileHandle reference can be obtained:
   1. If environment is known then IEnvironment.getFile(IPath) method should be used
   2. If full path is known, then EnvironmentPathUtils.getFile(IPath) method should be used.
6. All occurences of IResource.getLocation() returns null for remote resources and should be changed to new Path(IResource.getLocationURI().getPath()).
7. ScriptLaunchUtils is obsolete now. To launch a script IExecutionEnvironment should be used. IExecutionEnvironment can be obtained by adapting calling IEnviroment.getAdapter(IExecutionEnvironment.class).One should create a deployment object using IExecutionEnvironment.createDeployment(), then deploy scripts using IDeplyment.add() and run one using IExecutionEnvironment.exec(). After execution IDeployment.dispose() should be called.
8. To select file or folder on filesystem IEnvironmentUI.selectFile() and IEnvironmentUI.selectFolder should be used instead of DirectoryDialog and FileDialog. IEnvironmentUI can be obtained by calling IEnvironment.getAdapter(IEnvironementUI.class).

Examples

Adding external library in /opt2 to buildpath.

IEnvironment env = ...
IBuildpathEntry[] originalCP = proj.getRawBuildpath();
IBuildpathEntry[] newCP = new IBuildpathEntry[originalCP.length + 1];
System.arraycopy(originalCP, 0, newCP, 0, originalCP.length);
IPath libPath = EnvironmentPathUtils.getFullPath(env, new Path("/opt2"));
newCP[originalCP.length] = DLTKCore.newExtLibraryEntry(libPath);
IModelStatus status = BuildpathEntry.validateBuildpathEntry(proj, newCP[originalCP.length], false);

Launching a script

IEnvironment remoteEnvironment = ...;
IFileHandle scriptFile = LocalEnvironment.getInstance().getFile(new Path("/home/user/script.rb"));
IExecutionEnvironment remoteExecEnv = (IExecutionEnvironment) remoteEnvironment.getAdapter(IExecutionEnvironment.class);
IDeployment deployment = remoteExecEnv.createDeployment();
IPath deploymentPath = deployment.add(scriptFile.openInputStream(), "/script.rb");
String[] cmdLine = {"/usr/bin/ruby", deployment.getFile(deploymentPath).toOSString() };
Process process = remoteExecEnv.exec(cmdLine, null, null);

Environment provider implementation:

1. Extend org.eclipse.dltk.core.environmentProvider extension point and provide IEnvionmentProvider, IEnvironment and IFileHandle implementations
2. Provide adapter from user environment class to IExecutionEnvironment and write own implementation of IExecutionEnvironement
3. Provide adapter from user environment class to IEnvironmentUI and write own implementation of IEnvironementUI.