Usage examples

This section shows usage examples for using the Eclipse Remote API.

The services manager can be obtained using RemoteServicesUtils (since 2.0.1) helper:

IRemoteServicesManager servicesManager = RemoteServicesUtils.getService(IRemoteServicesManager.class);

An alternative is to use the bundle's context to get the service reference:

BundleContext context = plugin.getBundle().getBundleContext();
ServiceReference ref = context.getServiceReference(IRemoteServicesManager.class);
IRemoteServicesManager servicesManager = context.getService(ref);

Once with services manager object, you obtain a connection type by its scheme ID or any URI to the remote host, as in:

IRemoteConnectionType connType;
// Get connection type by Scheme ID
connType = servicesManager.getConnectionType("ssh");
// Get connection type by URI
URI uri = URI.create("ssh://MyConnection/path/to/file");
connType = servicesManager.getConnectionType(uri);

The Telnet connection type can not be obtained by URI, instead you must use its ID:

IRemoteConnectionType connType;
connType = servicesManager.getConnectionType("org.eclipse.remote.telnet.core.connectionType");

The remote connection is obtained from connection type object by either name or an URI. For example:

IRemoteConnection connection;
// Get connection by URI
URI uri = URI.create("ssh://MyConnection/path/to/file");
connection = connType.getConnection(uri);
// Get connection by name
connection = connType.getConnection("MyConnection");

If the connection does not exist, it can be created with a connection type (IRemoteConnectionType) instance. Use the connection type object to delete it as well:

IRemoteConnectionWorkingCopy rcwc; // Writable connection working copy 
rcwc = connType.newConnection(connectionName); // Create connection of connection type
IRemoteConnectionHostService hostServices; // Fill connection information through host service
hostServices = rcwc.getService(IRemoteConnectionHostService.class); // Obtain the service from working copy instance
hostServices.setHostname(address);
hostServices.setUsername(username);
hostServices.setUsePassword(true);
hostServices.setPassword(passwd);
IRemoteConnection connection = rcwc.save(); // Finally save the working copy, then get the connection (read-only) object

connType.removeConnection(connection); // Remove connection and all resources associated with it

Connections can be opened or closed programmatically. Some operations requires the connection opened:

connection.open(monitor); // Open the connection but allow the user to cancel the progress monitor
connection.close(); // Now close it

The file service is obtained from a connection object. Remote resources can be manipulated with IFileStore:

IRemoteFileService fileService = connection.getService(IRemoteFileService.class);
// The remote connection does not need to be open to get the resource
IFileStore fs = fileService.getResource("/path/to/resource");
// But the remote connection need to be open to operate on the resource
if (fs.fetchInfo().exists()) {
    System.out.println("It exists!");
}

In the other hand, the UI file service is obtained from a connection type rather than the connection. The reason is that it allows user to select the connection in a list. It is also possible to set the connection:

IRemoteUIFileService uiFileService = conn.getConnectionType().getService(IRemoteUIFileService.class);
uiFileService.setConnection(connection); // Set default connection (optional)
uiFileService.showConnections(true); // Also show list of available connections
// The return value is the path of the directory selected on the remote system
String path = uiFileService.browseDirectory(shell, "Browse /home", "/home", IRemoteUIConstants.NONE);

Use a connection object to get its associated process service (IRemoteProcessService). Then obtain a process builder (IRemoteProcessBuilder), so that commands can be executed on remote host:

IRemoteProcessService ps = connection.getService(IRemoteProcessService.class);
IRemoteProcessBuilder pb = ps.getProcessBuilder("/bin/ls", "-l");
IRemoteProcess process = pb.start();
// Use IRemoteProcess to manage the process. Alternatively, use an adaptor to java.lang.Process
Process process2 = new RemoteProcessAdapter(process);

Use the IRemoteResource adapter to get a location URI of the project (IProject):

IRemoteResource resource = (IRemoteResource)project.getAdapter(IRemoteResource.class);
URI projectLocation = resource.getActiveLocationURI(); // Get URI to active location