Eclipse RSE Development Guide (Galileo) - IConnectorService (RSE API Specification)

A connector service manages a live connection to a remote system, with operations for connecting and disconnecting, and storing information typically cached from a subsystem: credentials (such as a userId/password), port, etc.

The SubSystem interface includes a method, getConnectorService(), which returns an instance of an object that implements this interface for that subsystem.

A single connector service object can be unique to a subsystem instance, but it can also be shared across multiple subsystems in a single host if those subsystems share a physical connection to the remote system. This sharing is done using implementers of IConnectorServiceManager which are returned by another getter method in SubSystem.

Field Summary

Fields inherited from interface org.eclipse.rse.core.model. IRSEPersistableContainer

NO_CHILDREN

Method Summary

void acquireCredentials (boolean refresh)
          Acquire the credentials for this connector service.

void addCommunicationsListener ( ICommunicationsListener listener)
          Register a communications listener.

void clearCredentials ()
          Clears the credentials held by this service.

void clearPassword (boolean persist, boolean propagate)
          Clear password held by this service and optionally clear its persistent form.

void connect ( IProgressMonitor monitor)
          Connect to the remote system.

void deregisterSubSystem ( ISubSystem ss)
          Deregister the subsystem.

void disconnect ( IProgressMonitor monitor)
          Disconnect from the remote system.

boolean getDenyPasswordSave ()
          Retrieves the value of the "DENY_PASSWORD_SAVE" property of this connector service.

String getHomeDirectory ()


IHost getHost ()


String getHostName ()


int getPort ()


ISubSystem getPrimarySubSystem ()


IServerLauncher getRemoteServerLauncher ()


IServerLauncherProperties getRemoteServerLauncherProperties ()
          Gets the properties associated with a remote server launcher.

ISubSystem[] getSubSystems ()
          Return all the subsystems that use this connector service

String getTempDirectory ()


String getUserId ()


String getVersionReleaseModification ()


boolean hasPassword (boolean persistent)


boolean hasRemoteServerLauncherProperties ()


boolean inheritsCredentials ()
          Returns true if this system can inherit the credentials of from the other connector services in this host.

boolean isConnected ()


boolean isServerLaunchTypeEnabled ( ISubSystem subsystem, ServerLaunchType serverLaunchType)
          This methods returns the enablement state of a server launch type.

boolean isSuppressed ()


boolean isUsingSSL ()


void registerSubSystem ( ISubSystem ss)
          Adds a subsystem to this connector service.

void removeCommunicationsListener ( ICommunicationsListener listener)
          Remove a communications listener.

void removePassword ()
          Causes the persisted password known to this connector service, if any, to be forgotten.

void removeUserId ()
          Causes the persisted (default) user id known to this connector service, if any, to be forgotten.

boolean requiresPassword ()
          Test if this connector service requires a password.

boolean requiresUserId ()
          Test if this connector service requires a user id.

void reset ()
          Reset after some fundamental change, such as a hostname change.

void savePassword ()
          Causes the password known to this connector service, if any, to be persisted.

void saveUserId ()
          Causes the user id known to the connector service, if any, to be persisted.

int setDenyPasswordSave (boolean deny)
          Sets the attribute for this connector service instance that denies a password to be saved.

void setHost ( IHost host)
          Sets the host used by this connector service.

void setIsUsingSSL (boolean flag)


void setPassword ( String matchingUserId, String password, boolean persist, boolean propagate)
          Sets the password used by this connector service.

void setPort (int port)
          Set the port for this connector.

void setRemoteServerLauncherProperties ( IServerLauncherProperties value)
          Set the properties for the remote server launcher This is an object containing properties used to launch a remote server that communicates with this client.

void setSuppressed (boolean suppress)
          Suppresses the acquisition of a credentials by the connector service.

void setUserId ( String userId)
          Set the user id this connector service will use when establishing its connection.

boolean sharesCredentials ()
          Return true if this system can share it's credentials with other connector services in this host.

boolean supportsPassword ()
          Determines if this connector service understand the concept of a password.

boolean supportsRemoteServerLaunching ()


boolean supportsServerLaunchProperties ()


boolean supportsUserId ()
          Reports if this connector service can use a user identifier.

Methods inherited from interface org.eclipse.rse.core.model. IRSEModelObject

getDescription, getName

Methods inherited from interface org.eclipse.rse.core.model. IPropertySetContainer

addPropertySet, addPropertySets, createPropertySet, createPropertySet, getPropertySet, getPropertySets, removePropertySet

Methods inherited from interface org.eclipse.rse.core.model. IRSEPersistableContainer

commit, getPersistableChildren, getPersistableParent, isDirty, isTainted, setDirty, setTainted, setWasRestored, wasRestored

Method Detail

getPrimarySubSystem


ISubSystem getPrimarySubSystem()

Returns:: the primary subsystem object this connector service is associated with. This is usually the subsystem that first established this connector service.

getSubSystems


ISubSystem[] getSubSystems()

Return all the subsystems that use this connector service

Returns:: the subsystems that use this service

registerSubSystem

void registerSubSystem(
ISubSystem ss)

Adds a subsystem to this connector service. Does nothing if the subsystem is already known to this connector service.

Parameters:: ss - a subsystem that is using this connector service.

deregisterSubSystem

void deregisterSubSystem(
ISubSystem ss)

Deregister the subsystem. Does nothing if the subsystem is not present.

Parameters:: ss - the subsystem to remove from this connector service.

isConnected

boolean isConnected()

Returns:: true if currently connected.

connect

void connect(
IProgressMonitor monitor)
             throws 
Exception

Connect to the remote system.

Parameters:: monitor - a monitor for tracking the progress and canceling a connect operation.
Throws:: OperationCanceledException - if the connect was cancelled by the user; Exception - if there is a failure connecting. Typically, this will be a SystemMessageException.
Since:: org.eclipse.rse.core 3.0 throws OperationCanceledException instead of InterruptedException

disconnect

void disconnect(
IProgressMonitor monitor)
                throws 
Exception

Disconnect from the remote system.

Parameters:: monitor - a monitor for tracking the progress and canceling a disconnect operation.
Throws:: Exception - an exception of the disconnect fails. Typically, this will be a SystemMessageException.

reset

void reset()

Reset after some fundamental change, such as a hostname change. Clear any memory of the current connection.

getVersionReleaseModification


String getVersionReleaseModification()

Returns:: the version, release, modification of the remote system, if connected, if applicable, and if available. Return null if this information is not available.

getHomeDirectory


String getHomeDirectory()

Returns:: the home directory of the remote system for the current user, if available.

getTempDirectory


String getTempDirectory()

Returns:: the temporary directory of the remote system for the current user, if available.

setHost

void setHost(
IHost host)

Sets the host used by this connector service.

Parameters:: host - the host to be used for this connector service

getHost


IHost getHost()

Returns:: the host used by this connector service.

getHostName


String getHostName()

Returns:: the host name for the connection associated with this connector service.

getPort

int getPort()

Returns:: the port for this connector service. Usually only used for IP based connections.

setPort

void setPort(int port)

Set the port for this connector. Usually only used by IP based connections.

Parameters:: port - the IP port used by this connector service.

isUsingSSL

boolean isUsingSSL()

Returns:: true if this connector service will attempt to use SSL when establishing its connection.

setIsUsingSSL

void setIsUsingSSL(boolean flag)

Parameters:: flag - true if the connector service should attempt to use SSL when establishing the connection.

supportsUserId

boolean supportsUserId()

Reports if this connector service can use a user identifier. Typically used to indicate if a login dialog needs to be presented when connecting.

Returns:: true if and only if the connector service can use a user id.

supportsPassword

boolean supportsPassword()

Determines if this connector service understand the concept of a password.

Returns:: true if the connector service can use a password, false if a password is irrelevant.

getUserId


String getUserId()

Returns:: the user id that will be used by this connector when establishing its connection.

setUserId

void setUserId(
String userId)

Set the user id this connector service will use when establishing its connection.

Parameters:: userId - the user id string for this connector service.

saveUserId

void saveUserId()

Causes the user id known to the connector service, if any, to be persisted.

removeUserId

void removeUserId()

Causes the persisted (default) user id known to this connector service, if any, to be forgotten.

setPassword

void setPassword(
String matchingUserId,
                 
String password,
                 boolean persist,
                 boolean propagate)

Sets the password used by this connector service. Can be used if the connector service acquires a password by some external means.

Parameters:: matchingUserId - The user id to be associated with this password.; password - the password; persist - true if the password is to be persisted for later use.; propagate - true if this password should be propagated to related connector services.

savePassword

void savePassword()

Causes the password known to this connector service, if any, to be persisted.

removePassword

void removePassword()

Causes the persisted password known to this connector service, if any, to be forgotten.

clearPassword

void clearPassword(boolean persist,
                   boolean propagate)

Clear password held by this service and optionally clear its persistent form. Called when user uses the property dialog to change his userId.

Parameters:: persist - if true, clears the persistent form of the password; propagate - true if this password should be cleared in related connector services.

hasPassword

boolean hasPassword(boolean persistent)

Parameters:: persistent - also check for the persistent form of the password.
Returns:: true if a password is currently known to this connector service.

inheritsCredentials

boolean inheritsCredentials()

Returns true if this system can inherit the credentials of from the other connector services in this host.

Returns:: true if it can inherit the credentials, false otherwise

sharesCredentials

boolean sharesCredentials()

Return true if this system can share it's credentials with other connector services in this host.

Returns:: true if it can share the credentials

clearCredentials

void clearCredentials()

Clears the credentials held by this service. Should be called if there is a change to any part of the credentials expected by any using subsystem.

acquireCredentials

void acquireCredentials(boolean refresh)
                        throws 
OperationCanceledException

Acquire the credentials for this connector service. Acquisition may be temporarily suppressed by using the setSuppressed(boolean).

Implementations may retain a remembered credentials or use this to acquire the credentials using some implementation defined means.

Parameters:: refresh - if true will force the connector service to discard any remembered value and reacquire the credentials.
Throws:: OperationCanceledException - if acquisition of the credentials is cancelled or is being suppressed.
Since:: org.eclipse.rse.core 3.0 throws OperationCanceledException instead of InterruptedException

isSuppressed

boolean isSuppressed()

Returns:: true if the acquisition of credentials is being suppressed.

setSuppressed

void setSuppressed(boolean suppress)

Suppresses the acquisition of a credentials by the connector service. Causes acquireCredentials(boolean) to immediately throw an InterruptedException.

The intent is to allow tool writers to prevent multiple attempts to acquire credentials during a set period of time. It is the responsibility of the caller to set this value back to false when the tool no longer needs to suppress acquisition credentials.

Parameters:: suppress - true if acquisition is to be suppressed. false if acquisition is to be allowed.

addCommunicationsListener

void addCommunicationsListener(
ICommunicationsListener listener)

Parameters:: listener - a listener for the communications event.

removeCommunicationsListener

void removeCommunicationsListener(
ICommunicationsListener listener)

Remove a communications listener.

Parameters:: listener - a listener for the communications event.

isServerLaunchTypeEnabled

boolean isServerLaunchTypeEnabled(
ISubSystem subsystem,
                                  
ServerLaunchType serverLaunchType)

This methods returns the enablement state of a server launch type. If RemoteServerLauncher.enableServerLaunchType(ServerLaunchType, boolean) has not been called for this server launch type, then it is enabled by default.

Parameters:: subsystem - the subystem for which this may be enabled.; serverLaunchType - the type to check for enabledment.
Returns:: true if the connector service supports server launching and this launch type is enabled.
See Also:: ServerLaunchType

getRemoteServerLauncherProperties


IServerLauncherProperties getRemoteServerLauncherProperties()

Gets the properties associated with a remote server launcher. These may be null. This an optional object containing properties used to launch the remote server that communicates with this client.

Returns:: the properties of the server launcher

setRemoteServerLauncherProperties

void setRemoteServerLauncherProperties(
IServerLauncherProperties value)

Set the properties for the remote server launcher This is an object containing properties used to launch a remote server that communicates with this client.

Parameters:: value - the new value of the 'Remote Server Launcher' containment reference.

hasRemoteServerLauncherProperties

boolean hasRemoteServerLauncherProperties()

Returns:: true if the connector service has server launcher properties.

supportsServerLaunchProperties

boolean supportsServerLaunchProperties()

Returns:: true if the connector service supports the concept of remote server launch properties. This will always return false supportsRemoteServerLaunching() is false.

supportsRemoteServerLaunching

boolean supportsRemoteServerLaunching()

Returns:: true if the connector service supports the concept of remote server launching.

getRemoteServerLauncher


IServerLauncher getRemoteServerLauncher()

Returns:: the server launcher. Will be null unless supportsRemoteServerLaunching() is true.

requiresPassword

boolean requiresPassword()

Test if this connector service requires a password.

Returns:: true if this connector service supports passwords and requires a password to connect to its target system.

requiresUserId

boolean requiresUserId()

Test if this connector service requires a user id.

Returns:: true if this connector service understands the concept of a user id and requires one to connect to its target system.

setDenyPasswordSave

int setDenyPasswordSave(boolean deny)

Sets the attribute for this connector service instance that denies a password to be saved. If the attribute has never been set it defaults to false. If set to true, it will clear any saved passwords for this system and not allow any further passwords to be stored. This property of a system is persistent from session to session, but is not sharable.

Parameters:: deny - If true, forget any saved passwords and do not allow any others to be saved. If false, allow passwords to be saved in the keyring.
Returns:: the number of saved passwords removed by this operation. This will always be zero if "deny" is false.
Since:: org.eclipse.rse.core 3.0

getDenyPasswordSave

boolean getDenyPasswordSave()

Retrieves the value of the "DENY_PASSWORD_SAVE" property of this connector service. If the value has never been set, this will return false.

Returns:: true if password saving is denied.
Since:: org.eclipse.rse.core 3.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

RSE
Release 3.0

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.rse.core.subsystems Interface IConnectorService