Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

PTP/designs/remote/API

< PTP‎ | designs‎ | remote
Revision as of 09:39, 23 April 2009 by G.watson.computer.org (Talk | contribs) (Remote UI Services)

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

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.

Remote UI Services

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, editing, 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.

Back to the top