org.eclipse.ptp.remote.core
Interface IRemoteConnection

public interface IRemoteConnection

Abstraction of a connection to a remote system. Clients should use the set methods to provide information on the remote system, then call the {open(IProgressMonitor) method. Once the connection is completed, call the close() method to terminate the connection.

Field Summary

static java.lang.String	FILE_SEPARATOR_PROPERTY
static java.lang.String	LINE_SEPARATOR_PROPERTY
static java.lang.String	OS_ARCH_PROPERTY
static java.lang.String	OS_NAME_PROPERTY
static java.lang.String	OS_VERSION_PROPERTY
static java.lang.String	PATH_SEPARATOR_PROPERTY
static java.lang.String	USER_HOME_PROPERTY

Method Summary

void	addConnectionChangeListener(IRemoteConnectionChangeListener listener) Register a listener that will be notified when this connection's status changes.
void	close() Close the connection.
void	forwardLocalPort(int localPort, java.lang.String fwdAddress, int fwdPort) Forward local port localPort to remote port fwdPort on remote machine fwdAddress.
int	forwardLocalPort(java.lang.String fwdAddress, int fwdPort, IProgressMonitor monitor) Forward a local port to remote port fwdPort on remote machine fwdAddress.
void	forwardRemotePort(int remotePort, java.lang.String fwdAddress, int fwdPort) Forward remote port remotePort to port fwdPort on machine fwdAddress.
int	forwardRemotePort(java.lang.String fwdAddress, int fwdPort, IProgressMonitor monitor) Forward a remote port to port fwdPort on remote machine fwdAddress.
java.lang.String	getAddress() Gets the implementation dependent address for this connection return address
java.util.Map<java.lang.String,java.lang.String>	getAttributes() Get the implementation specific attributes for the connection.
java.util.Map<java.lang.String,java.lang.String>	getEnv() Returns an unmodifiable string map view of the remote environment.
java.lang.String	getEnv(java.lang.String name) Returns the value of an environment variable.
java.lang.String	getName() Get unique name for this connection.
int	getPort() Gets the port for this connection.
java.lang.String	getProperty(java.lang.String key) Gets the remote system property indicated by the specified key.
IRemoteServices	getRemoteServices() Get the remote services provider for this connection.
java.lang.String	getUsername() Gets the username for this connection return username
java.lang.String	getWorkingDirectory() Get the working directory.
boolean	isOpen() Test if the connection is open.
void	open(IProgressMonitor monitor) Open the connection.
void	open(IUserAuthenticator authenticator, IProgressMonitor monitor) Open the connection.
void	removeConnectionChangeListener(IRemoteConnectionChangeListener listener) Remove a listener that will be notified when this connection's status changes.
void	removeLocalPortForwarding(int port) Remove the local port forwarding associated with the given port.
void	removeRemotePortForwarding(int port) Remove the remote port forwarding associated with the given port.
void	setAddress(java.lang.String address) Set the address for this connection
void	setAttribute(java.lang.String key, java.lang.String value) Set an implementation dependent attribute for the connection.
void	setName(java.lang.String name) Set the name for this connection
void	setPassword(java.lang.String password) Set the password for this connection
void	setPort(int port) Set the port used for this connection.
void	setUsername(java.lang.String username) Set the username for this connection
void	setWorkingDirectory(java.lang.String path) Set the working directory.
boolean	supportsTCPPortForwarding() Test if this connection supports forwarding of TCP connections

Field Detail

OS_NAME_PROPERTY

static final java.lang.String OS_NAME_PROPERTY

See Also:

Constant Field Values

OS_VERSION_PROPERTY

static final java.lang.String OS_VERSION_PROPERTY

See Also:

Constant Field Values

OS_ARCH_PROPERTY

static final java.lang.String OS_ARCH_PROPERTY

See Also:

Constant Field Values

FILE_SEPARATOR_PROPERTY

static final java.lang.String FILE_SEPARATOR_PROPERTY

Since:

6.0

See Also:

Constant Field Values

PATH_SEPARATOR_PROPERTY

static final java.lang.String PATH_SEPARATOR_PROPERTY

Since:

6.0

See Also:

Constant Field Values

LINE_SEPARATOR_PROPERTY

static final java.lang.String LINE_SEPARATOR_PROPERTY

Since:

6.0

See Also:

Constant Field Values

USER_HOME_PROPERTY

static final java.lang.String USER_HOME_PROPERTY

Since:

4.0

See Also:

Constant Field Values

Method Detail

addConnectionChangeListener

void addConnectionChangeListener(IRemoteConnectionChangeListener listener)

Register a listener that will be notified when this connection's status changes.

Parameters:

listener -

close

void close()

Close the connection. Must be called to terminate the connection.

forwardLocalPort

void forwardLocalPort(int localPort,
                      java.lang.String fwdAddress,
                      int fwdPort)
                      throws RemoteConnectionException

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.

Parameters:

localPort - local port to forward

fwdAddress - address of remote machine

fwdPort - remote port on remote machine

Throws:

RemoteConnectionException

forwardLocalPort

int forwardLocalPort(java.lang.String fwdAddress,
                     int fwdPort,
                     IProgressMonitor monitor)
                     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.

Parameters:

fwdAddress -

fwdPort -

monitor -

Returns:

local port number

Throws:

RemoteConnectionException

forwardRemotePort

void forwardRemotePort(int remotePort,
                       java.lang.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.

Parameters:

remotePort - remote port to forward

fwdAddress - address of recipient machine

fwdPort - port on recipient machine

Throws:

RemoteConnectionException

forwardRemotePort

int forwardRemotePort(java.lang.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.

Parameters:

fwdAddress -

fwdPort -

monitor -

Returns:

remote port number

Throws:

RemoteConnectionException

getAddress

java.lang.String getAddress()

Gets the implementation dependent address for this connection return address

getAttributes

java.util.Map<java.lang.String,java.lang.String> getAttributes()

Get the implementation specific attributes for the connection. NOTE: the attributes do not include any security related information (e.g. passwords, keys, etc.)

Returns:

a map containing the connection attribute keys and values

getEnv

java.util.Map<java.lang.String,java.lang.String> getEnv()

Returns an unmodifiable string map view of the remote environment. The connection must be open prior to calling this method.

Returns:

the remote environment

Since:

5.0

getEnv

java.lang.String getEnv(java.lang.String name)

Returns the value of an environment variable. The connection must be open prior to calling this method.

Parameters:

name - name of the environment variable

Returns:

value of the environment variable or null if the variable is not defined

getName

java.lang.String getName()

Get unique name for this connection.

Returns:

connection name

getPort

int getPort()

Gets the port for this connection. Only valid if supported by the service provider. return port number

Since:

5.0

getProperty

java.lang.String getProperty(java.lang.String key)

Gets the remote system property indicated by the specified key. The connection must be open prior to calling this method. The following keys are supported:

 os.name                        Operating system name 
 os.arch                        Operating system architecture
 os.version             Operating system version
 file.separator File separator ("/" on UNIX)
 path.separator Path separator (":" on UNIX)
 line.separator Line separator ("\n" on UNIX)
 user.home              Home directory
 

Parameters:

key - the name of the property

Returns:

the string value of the property, or null if no property has that key

getRemoteServices

IRemoteServices getRemoteServices()

Get the remote services provider for this connection.

Returns:

remote services provider

Since:

4.0

getUsername

java.lang.String getUsername()

Gets the username for this connection return username

getWorkingDirectory

java.lang.String getWorkingDirectory()

Get the working directory. Relative paths will be resolved using this path. The remote connection does not need to be open to use this method, however a default directory path, rather than the actual working directory, may be returned in this case.

Returns:

String representing the current working directory

Since:

4.0

isOpen

boolean isOpen()

Test if the connection is open.

Returns:

true if connection is open.

open

void open(IProgressMonitor monitor)
          throws RemoteConnectionException

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

Parameters:

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

open

void open(IUserAuthenticator authenticator,
          IProgressMonitor monitor)
          throws RemoteConnectionException

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

Parameters:

authenticator - authenticator to allow the caller to manage interaction with the user

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

Since:

7.0

removeConnectionChangeListener

void removeConnectionChangeListener(IRemoteConnectionChangeListener listener)

Remove a listener that will be notified when this connection's status changes.

Parameters:

listener -

removeLocalPortForwarding

void removeLocalPortForwarding(int port)
                               throws RemoteConnectionException

Remove the local port forwarding associated with the given port.

Parameters:

port - forwarded port

Throws:

RemoteConnectionException

Since:

7.0

removeRemotePortForwarding

void removeRemotePortForwarding(int port)
                                throws RemoteConnectionException

Remove the remote port forwarding associated with the given port.

Parameters:

port - forwarded port

Throws:

RemoteConnectionException

Since:

7.0

setAddress

void setAddress(java.lang.String address)

Set the address for this connection

Parameters:

address -

setAttribute

void setAttribute(java.lang.String key,
                  java.lang.String value)

Set an implementation dependent attribute for the connection. Attributes keys supported by the connection can be obtained using getAttributes()

Parameters:

key - attribute key

value - attribute value

Since:

5.0

setName

void setName(java.lang.String name)

Set the name for this connection

Parameters:

name -

setPassword

void setPassword(java.lang.String password)

Set the password for this connection

Parameters:

password -

Since:

5.0

setPort

void setPort(int port)

Set the port used for this connection. Only valid if supported by the underlying service provider.

Parameters:

port - port number for the connection

Since:

5.0

setUsername

void setUsername(java.lang.String username)

Set the username for this connection

Parameters:

username -

setWorkingDirectory

void setWorkingDirectory(java.lang.String path)

Set the working directory. Relative paths will be resolved using this path. The path must be valid and absolute for any changes to be made.

Parameters:

path - String representing the current working directory

Since:

4.0

supportsTCPPortForwarding

boolean supportsTCPPortForwarding()

Test if this connection supports forwarding of TCP connections

Returns:

true if TCP port forwarding is supported