PTP/designs/remote/API

This page provides a brief overview of the PTP remote services API. The purpose of this API is to provide a programming interface to remote services that is agnostic to the actual remote services implementation. Current implementation supported are RSE and Remote Tools (light-weight ssh layer that is part of PTP). It also provides an implementation for the local system (where Eclipse is run).

Types of Services

The API is divided into two types of remote services: UI and non-UI. UI services are for activities such as file browsing that require use of the UI. Non-UI services are purely programmatic. The non-UI services can be used independently of the UI services.

Remote Services Plugins

The remote services are divided into two plugins. These plugins should have no dependencies other than the platform.

• org.eclipse.ptp.remote.core
• org.eclipse.ptp.remote.ui

Remote service providers are adapted to these interfaces using a set of adapter plugins. There are currently two implementations.

1. RSE
   • org.eclipse.ptp.remote.rse.core
   • org.eclipse.ptp.remote.rse.ui
2. Remote Tools
   • org.eclipse.ptp.remote.remotetools.core
   • org.eclipse.ptp.remote.remotetools.ui

These plugins are dependent on the remote services implementations, but are optional for the remote services API. The API will automatically detect the installed plugins.

Core API

PTPRemoteCorePlugin

The PTPRemoteCorePlugin provides the main entry point for accessing remote services. Typically usage is to call getAllRemoteServices() to retrieve all the known service providers and allow the user to select from the list (or auto select). Once an IRemoteServices object has been obtained, it can be used to access all the remaining remote functionality.

public IRemoteServices[] getAllRemoteServices() 

Retrieve all the known remote service providers.

public IRemoteServices getRemoteServices(URI uri) 

Retrieve the remote service provider associated with a URI.

public IRemoteConnection getConnection(URI uri) 

Retrieve a remote connection associated with a URI.

IRemoteServices

The IRemoteServices interface is the main entry point into the remote functionality. From here it is possible to gain access to three types of remote services: connection, file, and process. Connection services are for managing connections to the remote system. File services are for copying and manipulating files remotely. Process services are for launching processes on the remote system.

public IRemoteConnectionManager getConnectionManager() 

Get the connection manager for the remote service provider.

public IRemoteFileManager getFileManager(IRemoteConnection conn)  

Get the file manager for the remote service provider.

public IRemoteProcessBuilder getProcessBuilder(IRemoteConnection conn, List<String>command)  

Get the process builder for the remote service provider. The process builder can be used to invoke the command specified by the argument list.

public IRemoteProcessBuilder getProcessBuilder(IRemoteConnection conn, String... command)  

Get the process builder for the remote service provider. The process builder can be used to invoke the command specified by the argument strings.

IRemoteConnectionManager

The IRemoteConnectionManager interface is for managing connections to remote systems. This is a container for the remote connection that is actually managed by the remote service provider, so the name of the connection is only meaningful in the context of the remote provider. Both currently supported remote providers use names to identify connections, and this name is the same one that can be used to look up the connection. Since creating a new connection typically requires interaction with the user, this facility is provided in the remote UI services API.

public IRemoteConnection getConnection(String name) 

Retrieve a connection using the connection name. A connection name is a string that identifies the connection for the remote service provider.

public IRemoteConnection[] getConnections() 

Retrieve all the connections that are known by the remote service provider.

public void removeConnection(IRemoteConnection connection) 

Remove the remote connection.

IRemoteConnection

The IRemoteConnection interface is for managing a connection to a single remote host. A connection must be established (open) before any other operations are permitted. Connections are passed to other services in order to carry out operations on the remote host.

public void close() 

Close the remote connection

public void forwardLocalPort(int localPort, String fwdAddress, int fwdPort)  

Forward a local port to a remote port on a remote host.

public void forwardRemotePort(int remotePort, String fwdAddress, int fwdPort) 

Forward a remote port to a port on different host.

public int forwardLocalPort(String fwdAddress, int fwdPort, IProgressMonitor monitor)  

Forward a local port to a remote port on remote host.

public int forwardRemotePort(String fwdAddress, int fwdPort, IProgressMonitor monitor) 

Forward a remote port to a port on a remote host. The remote port is chosen dynamically and returned by the method.

public String getAddress() 

Get the implementation dependent address for this connection (usually the IP address or FQDN).

public String getName() 

Get a unique name for this connection.

public String getUsername() 

Get the username for this connection.

public boolean isOpen() 

Test if the connection is open. A connection must be open before any operations can be performed.

public void open(IProgressMonitor monitor)  

Open the connection. Must be called before the connection can be used.

public void setAddress(String address) 

Set the implementation dependent address for this connection.

public void setUsername(String username) 

Set the username for this connection.

public boolean supportsTCPPortForwarding() 

Test if this connection supports forwarding of TCP connections.

IRemoteFileManager

The IRemoteFileManager interface provides remote file manipulation operations on a given connection. Using this interface, a path can be translated into an IFileStore object, and then manipulated using any of the normal EFS operations (See the EFS documentation in the Platform Plug-in Developer Guide > Programmer's Guide > Advanced resource concepts > Alternate file systems).

public IFileStore getResource(IPath path, IProgressMonitor monitor) 

Get the resource associated with a path. The platform EFS interfaces can then be used to perform operations on the file.

public IPath getWorkingDirectory() 

Get the working directory. Relative paths will be resolved using this path.

public IPath toPath(URI uri) 

Convert URI to a remote path. This path is suitable for direct file operations on the remote system.

public URI toURI(IPath path) 

Convert remote path to equivalent URI. This URI is suitable for EFS operations on the local system.

IRemoteProcessBuilder

The IRemoteProcessBuilder provides remote process operations on a given connection. This interface is intended to be a drop-in replacement for the ProcessBuilder class. See the java.lang.ProcessBuilder documentation for a description of the methods.

UI API

PTPRemoteUIPlugin

The PTPRemoteUIPlugin provides the main entry point for accessing UI functionality for remote services. Typically usage is to obtain an IRemoteServices object and then call getRemoteUIServices().

public IRemoteUIServices getRemoteUIServices(IRemoteServices services) 

Retrieve the remote UI services associated with the service provider.

IRemoteUIServices

The IRemoteUIServices interface provides two methods for accessing UI operations. This include methods for manipulating connections (creating, etc.) and for manipulating remote files.

public IRemoteUIConnectionManager getUIConnectionManager() 

Get a UI connection manager for managing connections.

public IRemoteUIFileManager getUIFileManager() 

Get a UI file manager for managing remote files.

IRemoteUIConnectionManager

The IRemoteUIConnectionManager interface is used for manipulating connections in the UI. Currently only connection creation is supported. This method will display an implementation dependent dialog for creating a new connection to a remote host and return the new connection object.

public IRemoteConnection newConnection(Shell shell) 

Create a new connection. The implementation can chose to do this in any way, but typically will use a dialog or wizard.

IRemoteUIFileManager

The IRemoteUIFileManager interface provides methods for manipulating files or directories on the remote host.

public IPath browseDirectory(Shell shell, String message, String initialPath) 

Browse for a remote directory. The return value is the path of the directory on the remote system.

public IPath browseFile(Shell shell, String message, String initialPath) 

Browse for a remote file. The return value is the path of the file on the remote system.

public IRemoteConnection getConnection() 

Get the last connection that was selected in the browser.

public void setConnection(IRemoteConnection connection) 

Set the connection to use for browsing.

public void showConnections(boolean enable) 

Show a list of available connections in the browser if possible.

Remote Servers

The remote services functionality also supports the ability to cache and launch server processes on a remote machine. This is different from just launching a remote process using IRemoteProcessBuilder, since the server process to be launched on the remote machine is supplied from a plugin in the local Eclipse installation. Although designed for java servers, it would also be possible to use this functionality to launch servers written in other languages (e.g. python), provided that support for these languages exists on the remote system.

Extension Point org.eclipse.ptp.remote.core.remoteServer

The remoteServer extension point describes the launch information necessary to provide a remotely launched server process.

id 

A unique identifier for this remote server.

name 

A human readable name for this remote server.

launchCommand 

The command used to launch the payload on the remote machine. The variable "${payload}" can be used to include the name of the payload (as specified in the "payload" attribute) in the launch command.

payload 

Server payload. This will be copied from the plugin to the working directory on the remote machine prior to launch. The payload is cached on the remote machine and only copied if it is necessary.

class 

The fully qualified name of the Java class extending org.eclipse.ptp.remote.launch.core.AbstractRemoteServerRunner

To use the extension point, create (or extend) a plugin to provide a remoteServer extension. For a java payload, the launch command will be a string like: "java -Xms64m -Xmx128m -Xss2m -jar ${payload}". The payload will be the name of a jar file, such as "rdt-server.jar". The payload is assumed to be located at the top level of the plugin.

AbstractRemoteServerRunner

The plugin must also provide a class that extends AbstractRemoteServerRunner. This class must implement the following methods:

void doFinishServer() 

called when the server process terminates

boolean doRestartServer() 

called when the server process is restarted. Should return false if the restart is to be aborted.

boolean doStartServer() 

called when the server process is started. Should return false if the startup is to be aborted.

boolean doVerifyServerRunningFromStderr(String output) 

called once for each line of stderr from the server. Implementers can use this to determine when the server has successfully started. Returning true will change the server state to running.

boolean doVerifyServerRunningFromStdout(String output) 

called once for each line of stdout from the server. Implementers can use this to determine when the server has successfully started. Returning true will change the server state to running.

Server Startup

The first step in starting a server is to call RemoteServerManager#getServer(id, connection) to obtain the server runner class, where id is the id of the server specified in the extension, and connection is an IRemoteConnection to a remote system.

Once the server instance has been obtained, calling startServer(IProgressMonitor monitor) on this class will launch the server. The payload will be copied and cached on the remote machine if necessary, then the launch command will be invoked. The startServer method will return true if the launch is successful (one of the doVerifyServerRunning methods returns true).

Only one server with a given id will be launched using a particular IRemoteConnection. Calling getServer using the same id and connection will return the same server instance and calling startServer will have no effect.

Building A Server Plugin

The server payload must exist at the root level of the plugin that provides the extension. It is up to the build process to copy the server payload from wherever it is built to the plugin during the build process. The plugin itself can be jarred when installed, the server knows how to extract the payload from a jar file.

For java servers (launched using the -jar argument), the jar file must be built using the jar-in-jar class loader. This is done by extracting the jar-in-jar-loader.zip from the JDT UI plugin, then unzipping this file into the root of the plugin. Then, when the plugin is jarred, a manifest is created that specifies a Main-Class as org.eclipse.jdt.internal.jarinjarloader.JarRsrcLoader and an Rsrc-Main-Class as the class containing the main entry point. Rsrc-Class-Path can then be used to specify a class path within the jar file. The org.eclipse.ptp.rdt.core.remotejars plugin has a build.xml that gives an example of how to do this (see the prepare.remote.jar and jar.remote targets).