Hi folks,
We’ve
started to write a migration guide to support environments API. This letter
contains current version of this document. In addition you can find it in DLTK
wiki http://wiki.eclipse.org/Remote_API_Migration_guide
. Feel free to ask your questions.
Best regards,
Timur
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:
a. If environment is known then IEnvironment.getFile(IPath)
method should be used
b. 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).
Example 1.
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);
Example 2.
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);