Difference between revisions of "PTP/designs/remote/API"

Revision as of 15:26, 22 April 2009

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:

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

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

public void close();

/** * Forward local port localPort to remote port fwdPort on remote machine fwdAddress. If this * IRemoteConnection is not to fwdAddress, the port will be routed via the connection machine to * fwdAddress. * * @param localPort local port to forward * @param remoteAddress address of remote machine * @param remotePort remote port on remote machine * @throws RemoteConnectionException */ public void forwardLocalPort(int localPort, String fwdAddress, int fwdPort) throws RemoteConnectionException;

/** * Forward remote port remotePort to port fwdPort on machine fwdAddress. When a connection is made to remotePort * on the remote machine, it is forwarded via this IRemoteConnection to fwdPort on machine fwdAddress. * * @param remotePort remote port to forward * @param fwdAddress address of recipient machine * @param fwdPort port on recipient machine * @throws RemoteConnectionException */ public void forwardRemotePort(int remotePort, String fwdAddress, int fwdPort) throws RemoteConnectionException;

/** * Forward a local port to remote port fwdPort on remote machine fwdAddress. The local port is chosen * dynamically and returned by the method. If this IRemoteConnection is not to fwdAddress, the port will * be routed via the connection machine to fwdAddress. * * @param fwdAddress * @param fwdPort * @param monitor * @return local port number * @throws RemoteConnectionException */ public int forwardLocalPort(String fwdAddress, int fwdPort, IProgressMonitor monitor) throws RemoteConnectionException;

/** * Forward a remote port to port fwdPort on remote machine fwdAddress. The remote port is chosen * dynamically and returned by the method. When a connection is made to this port * on the remote machine, it is forwarded via this IRemoteConnection to fwdPort on machine fwdAddress. * * If fwdAddress is the empty string ("") then the fwdPort will be bound to any address on * all interfaces. Note that this requires enabling the GatewayPort sshd option on some systems. * * @param fwdAddress * @param fwdPort * @param monitor * @return remote port number * @throws RemoteConnectionException */ public int forwardRemotePort(String fwdAddress, int fwdPort, IProgressMonitor monitor) throws RemoteConnectionException;

/** * Gets the implementation dependent address for this connection * * return address */ public String getAddress();

/** * Get unique name for this connection. * * @return connection name */ public String getName();

/** * Gets the username for this connection * * return username */ public String getUsername();

/** * Test if the connection is open. * * @return true if connection is open. */ public boolean isOpen();

/** * Open the connection. Must be called before the connection can be used. * * @param monitor the progress monitor to use for reporting progress to the user. It is the caller's responsibility

    *                to call done() on the given monitor. Accepts null, indicating that no progress should be
    *                reported and that the operation cannot be cancelled.

* @throws RemoteConnectionException */ public void open(IProgressMonitor monitor) throws RemoteConnectionException;

/** * Set the address for this connection * * @param address */ public void setAddress(String address);

/** * Set the username for this connection * * @param username */ public void setUsername(String username);

/** * Test if this connection supports forwarding of TCP connections * * @return true if TCP port forwarding is supported */ public boolean supportsTCPPortForwarding();

Remote UI Services

public IRemoteUIServices getRemoteUIServices(IRemoteServices services) 

Retrieve the remote UI services associated with the service provider.