View source for PTP/designs/remote/API

This page provides a brief overview of the 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. Currently the only implementation supported is JSch, but support for RSE and Remote Tools (light-weight ssh layer that is part of PTP) are available in PTP. An implementation for the local system (where Eclipse is run) is also provided.

The API is generic enough so that it is possible to use it for all remote *or* local operations. This is useful for situations where both a remote and local mode should be provided, but the programmer wants to avoid two separate code paths.

== 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.

* <code>org.eclipse.remote.core</code>
* <code>org.eclipse.remote.ui</code>

Remote service implementations provide the actual remote functionality using a particular remote protocol. These are supplied as a set of adapter plugins. There is currently one implementation using JSch.

* <code>org.eclipse.remote.jsch.core</code>
* <code>org.eclipse.remote.jsch.ui</code>

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 Services ==

The remote services package provides a set of core services for manipulating remote resources. These are described in more detail below.

=== RemoteServices class ===

The <code>RemoteServices</code> class provides the main entry point for accessing remote services. Typically usage is to call getRemoteServices() passing either an ID or a URI to retrieve the remote services implementation. The ID can be obtained using the UI services described below. Once an IRemoteServices object has been obtained, it can be used to access all the remaining remote functionality.

; <code>public IRemoteServices getRemoteServices(String id)</code> : Retrieve the remote service provider associated with id.

; <code>public IRemoteServices getRemoteServices(URI uri)</code> : Retrieve the remote service provider associated with a URI.

; <code>public IRemoteConnection getLocalServices()</code> : Retrieve the local services.

=== IRemoteServices ===

The <code>IRemoteServices</code> interface is the main entry point into the remote functionality. From here it is possible to gain access to the connection manager, and to obtain information about the service capabilities.

; <code>public IRemoteConnectionManager getConnectionManager()</code> : Get the connection manager for the remote service provider.
	
; <code>public int getCapabilities()</code>  : Get the capabilities of the remote service provider. This includes information about whether it is possible to create new connections, and what types of functionality the remote services provides. See the <code>IRemoteServices</code> class for a list of the capabilities.
	
=== IRemoteConnectionManager ===

The <code>IRemoteConnectionManager</code> interface is for managing connections to remote systems. Since creating a new connection can require user interaction, there is also functionality in the UI services to help with this.

; <code>public IRemoteConnection getConnection(String name)</code> : Retrieve a connection using the connection name. A connection name is a string that identifies the connection for the remote service provider.

; <code>public List<IRemoteConnection> getConnections()</code> : Retrieve all the connections that are known by the remote service provider.
	
; <code>public IRemoteConnectionWorkingCopy newConnection(String name)</code> : Create a new connection with name 'name'.

; <code>public void removeConnection(IRemoteConnection connection)</code> : Remove the remote connection.

=== IRemoteConnection ===

The <code>IRemoteConnection</code> 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. Connections are read-only objects. In order to change the attributes of a connection, a working copy must be created (see <code>IRemoteConnectionWorkingCopy</code> below).

; <code>public void close()</code> : Close the remote connection
	
; <code>public void forwardLocalPort(int localPort, String fwdAddress, int fwdPort) </code> : Forward a local port to a remote port on a remote host. 

; <code>public void forwardRemotePort(int remotePort, String fwdAddress, int fwdPort)</code> : Forward a remote port to a port on different host.
 
; <code>public int forwardLocalPort(String fwdAddress, int fwdPort, IProgressMonitor monitor) </code> : Forward a local port to a remote port on remote host.
	
; <code>public int forwardRemotePort(String fwdAddress, int fwdPort, IProgressMonitor monitor)</code> : Forward a remote port to a port on a remote host. The remote port is chosen  dynamically and returned by the method.

; <code>public String getAddress()</code> : Get the implementation dependent address for this connection (usually the IP address or FQDN).
	
; <code>public String getName()</code> : Get a unique name for this connection.

; <code>public IRemoteFileManager getFileManager()</code>  : Get the file manager for the remote connection. The file manager can be used to manipulate files on the remote system.
	
; <code>public IRemoteProcessBuilder getProcessBuilder(List<String>command)</code>  : Get the process builder for the remote connection. The process builder can be used to invoke the command specified by the argument list.
	
; <code>public IRemoteProcessBuilder getProcessBuilder(String... command)</code>  : Get the process builder for the remote connection. The process builder can be used to invoke the command specified by the argument strings.

; <code>public String getUsername()</code> : Get the username for this connection.
	
; <code>public IRemoteConnectionWorkingCopy getWorkingCopy() </code> :  Get a working copy of the connection. Must be used to modify any connection attributes.

; <code>public boolean isOpen()</code> : Test if the connection is open. A connection must be open before any operations can be performed.

; <code>public void open(IProgressMonitor monitor) </code> :  Open the connection. Must be called before the connection can be used.

; <code>public boolean supportsTCPPortForwarding()</code> : Test if this connection supports forwarding of TCP connections.

=== IRemoteConnectionWorkingCopy ===

An <code>IRemoteConnectionWorkingCopy</code> is a writeable copy of the connection. It provides additional methods for modifying the connection attributes. The <code>save()</code> method must be called to save the changes to the original connection.
	
; <code>public void setAddress(String address)</code> : Set the implementation dependent address for this connection.
	
; <code>public void setUsername(String username)</code> : Set the username for this connection.

=== IRemoteFileManager ===

The <code>IRemoteFileManager</code> 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).

; <code>public IFileStore getResource(IPath path, IProgressMonitor monitor)</code> : Get the resource associated with a path. The platform EFS interfaces can then be used to perform operations on the file.
	
; <code>public IPath getWorkingDirectory()</code> : Get the working directory. Relative paths will be resolved using this path.
	
; <code>public IPath toPath(URI uri)</code> : Convert URI to a remote path. This path is suitable for direct file operations <i>on the remote system</i>.

; <code>public URI toURI(IPath path)</code> : Convert remote path to equivalent URI. This URI is suitable for EFS operations <i>on the local system</i>.

=== IRemoteProcessBuilder ===

The <code>IRemoteProcessBuilder</code> provides remote process operations on a given connection. This interface is intended to be a drop-in replacement for the <code>ProcessBuilder</code> class. See the [http://java.sun.com/javase/6/docs/api/java/lang/ProcessBuilder.html <code>java.lang.ProcessBuilder</code>] documentation for a description of the methods.

== UI Services ==

The remote services package also provides utilities to help manipulate remote resources via the UI. In particular, it provides a main preference page (under "Remote Development > Connections") which allow connections to be created, edited, removed, opened, and closed. In addition to this preference page, a number of other utilities provided, and these are discussed in more detail below.

=== RemoteConnectionWidget === 

This UI widget can be used anywhere the user needs to select or create a connection in the UI. It extends an SWT Composite, so can be used anywhere an ordinary Composite is used.

=== RemoteDirectoryWidget ===

This UI widget provides a directory browser to allow selection of a directory on the remote system.

=== RemoteFileWidget ===

This UI widget provides a file browser to allow selection of one (or more) files on the remote system.

=== RemoteResourceBrowser ===

A dialog that provides a generic method for browsing for files or directories on the target system.

=== RemoteUIServices class ===

If other UI services are required, the <code>RemoteUIServices</code> class provides the main entry point for accessing these. Typically usage is to obtain an <code>IRemoteServices</code> object and then call <code>getRemoteUIServices()</code>. There are also a number of widgets and dialogs that can be used to access remote services.

; <code>public IRemoteUIServices getRemoteUIServices(IRemoteServices services)</code> : Retrieve the remote UI services associated with the service provider.

=== IRemoteUIServices ===

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

; <code>public IRemoteUIConnectionManager getUIConnectionManager()</code> : Get a UI connection manager for managing connections.
	
; <code>public IRemoteUIFileManager getUIFileManager()</code> : Get a UI file manager for managing remote files.

=== IRemoteUIConnectionManager ===

The <code>IRemoteUIConnectionManager</code> interface is used for manipulating connections in the UI, such as adding, editing, and opening connections. 

; <code>public IRemoteUIConnectionWizard getConnectionWizard(Shell shell)</code> : Obtain a wizard for managing connections.

; <code>public void openConnectionWithProgress(Shell shell, IRunnableContext context, IRemoteConnection connection)</code> : Open a connection using a runnable context or progress monitor. Should be used anywhere a connection is opened in the UI.

=== IRemoteUIFileManager ===

The <code>IRemoteUIFileManager</code> interface provides methods for manipulating files or directories on the remote host.

; <code>public IPath browseDirectory(Shell shell, String message, String initialPath)</code> : Browse for a remote directory. The return value is the path of the directory <i>on the remote system</i>.

; <code>public IPath browseFile(Shell shell, String message, String initialPath)</code> : Browse for a remote file. The return value is the path of the file <i>on the remote system</i>. 

; <code>public IRemoteConnection getConnection()</code> : Get the last connection that was selected in the browser.

; <code>public void setConnection(IRemoteConnection connection)</code> : Set the connection to use for browsing.

; <code>public void showConnections(boolean enable)</code> : Show a list of available connections in the browser if possible.

== Usage Examples ==

A remote services object can be obtained directly if the ID is known:

<pre>
IRemoteServices services = RemoteServices.getRemoteServices("org.eclipse.remote.JSch");
</pre>

It can also be obtained via a URI:

<pre>
IRemoteServices services = RemoteServices.getRemoteServices(new URI("ssh://user@host/path/to/resource"));
</pre>

Once a services object has been obtained, connections can be manipulated programmatically:

<pre>
IRemoteConnectionManager connMgr = services.getConnectionManager(); // Get the connection manager
IRemoteConnectionWorkingCopy wc = connMgr.newConnection("my connection"); // Create a new connection
wc.setAddress("remote.host.com"); // Set the address (host name)
wc.setUsername("my_username"); // Set the username
wc.setPassword("secret_password"); // Set the password
IRemoteConnection connection = wc.save(); // Save the attributes
</pre>

Connections can be opened or closed programmatically:

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

Open connections can be used to manipulate remote files:

<pre>
IRemoteFileManager fileMgr = connection.getFileManager(); // Get the file manager for the connection
IFileStore file = fileMgr.getResouce("/path/to/resource"); // Get the file store representing the resource
if (file.fetchInfo().exists()) {
    System.out.println("It exists!");
}
</pre>

Remote processes can be run:

<pre>
IRemoteProcessBuilder builder = connection.getProcessBuilder("/bin/ls", "-l"); // Create an 'ls -l' command
IRemoteProcess process = builder.start();
while (!process.isCompleted()) {
    process.waitFor();
}
</pre>