org.eclipse.rse.core.subsystems
Interface IConnectorService

All Superinterfaces:

IPropertySetContainer, IRSEModelObject, org.eclipse.rse.core.persistance.IRSEPersistableContainer

All Known Implementing Classes:

AbstractConnectorService

public interface IConnectorService

extends IRSEModelObject

This is the interface implemented by ConnectorService (formerly System) objects.

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: user ID, 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 via subclasses of AbstractConnectorServiceManager which are returned by another getter method in SubSystem.

Method Summary

void	addCommunicationsListener(ICommunicationsListener listener) Register a communications listener
void	clearPasswordCache() Clear internal password cache.
void	clearPasswordCache(boolean clearDiskCache) Clear internal password cache.
void	clearUserIdCache() Clear internal userId cache.
void	connect(IProgressMonitor monitor) Attempt to connect to the remote system.
void	deregisterSubSystem(ISubSystem ss) Deregister the subsystem
void	disconnect(IProgressMonitor monitor) Disconnect from the remote system
String	getHomeDirectory() Return the home directory of the remote system for the current user, if available.
IHost	getHost() Return the host
String	getHostName() Return the host name for the connection this system's subsystem is associated with
String	getHostType() Return the system type for this connection.
String	getName() Return the name of this connector service
int	getPort() Return the port for this connector
ISubSystem	getPrimarySubSystem() Return the subsystem object this system is associated with
IServerLauncherProperties	getRemoteServerLauncherProperties() Returns the value of the 'Remote Server Launcher' containment reference.
ISubSystem[]	getSubSystems() Return all the subsystems that use this service
String	getTempDirectory() Return the temp directory of the remote system for the current user, if available.
String	getUserId() Return the userId for this system's subsystem we are associated with
String	getVersionReleaseModification() Return the version, release, modification of the remote system, if connected, if applicable and if available.
boolean	hasRemoteServerLauncherProperties()
boolean	inheritConnectionUserPassword() Return true if this system can inherit the uid and password of other ISystems in this connection
boolean	isConnected() Return true if currently connected.
boolean	isPasswordCached() Return true if password is currently cached.
boolean	isPasswordCached(boolean onDisk) Return true if password is currently cached.
boolean	isSuppressSignonPrompt() Returns the suppressSignonPrompt flag.
boolean	isUsingSSL()
void	notifyConnection() Notifies all listeners of a connection through a communications event
void	notifyDisconnection() Notifies all listeners of a disconnection through a communications event
void	notifyError() Notifies all listeners of an error through a communications event
void	promptForPassword(boolean forcePrompt) Return the password for this system's subsystem we are associated with.
void	registerSubSystem(ISubSystem ss) Set the subsystem, when its not known at constructor time
void	removeCommunicationsListener(ICommunicationsListener listener) Remove a communications listener
boolean	requiresPassword() If a password is supported this is used to determine if the password is required.
boolean	requiresUserId() Report if this connector service requires a user id.
void	reset() Reset after some fundamental change, such as a hostname change.
void	setHost(IHost host)
void	setIsUsingSSL(boolean flag)
void	setPassword(String matchingUserId, String password) Set the password if you got it from somewhere
void	setPassword(String matchingUserId, String password, boolean persist) Set the password if you got it from somewhere
void	setPort(int port) Set the port for this connector
void	setRemoteServerLauncherProperties(IServerLauncherProperties value) Sets the value of the 'Remote Server Launcher' containment reference
void	setSuppressSignonPrompt(boolean suppressSignonPrompt) Sets the suppressSignonPrompt flag.
void	setUserId(String userId) Set the user id for this connector
boolean	shareUserPasswordWithConnection()
boolean	supportsPassword() Can be used to determine if a password field is present on a login dialog for this connector service.
boolean	supportsRemoteServerLaunching()
boolean	supportsServerLaunchProperties() Tell us if this subsystem factory supports server launch properties, which allow the user to configure how the server-side code for these subsystems are started.
boolean	supportsUserId() Report if this connector service can use a user identifier.

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

getDescription

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.persistance.IRSEPersistableContainer

commit, isDirty, setDirty, setWasRestored, wasRestored

Method Detail

getPrimarySubSystem

public ISubSystem getPrimarySubSystem()

Return the subsystem object this system is associated with

getSubSystems

public ISubSystem[] getSubSystems()

Return all the subsystems that use this service

Returns:

the subsystems that use this service

registerSubSystem

public void registerSubSystem(ISubSystem ss)

Set the subsystem, when its not known at constructor time

deregisterSubSystem

public void deregisterSubSystem(ISubSystem ss)

Deregister the subsystem

Parameters:

ss -

isConnected

public boolean isConnected()

Return true if currently connected.

connect

public void connect(IProgressMonitor monitor)
             throws Exception

Attempt to connect to the remote system.

Throws:

Exception

disconnect

public void disconnect(IProgressMonitor monitor)
                throws Exception

Disconnect from the remote system

Throws:

Exception

notifyDisconnection

public void notifyDisconnection()

Notifies all listeners of a disconnection through a communications event

notifyConnection

public void notifyConnection()

Notifies all listeners of a connection through a communications event

notifyError

public void notifyError()

Notifies all listeners of an error through a communications event

reset

public void reset()

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

getVersionReleaseModification

public String getVersionReleaseModification()

Return the version, release, modification of the remote system, if connected, if applicable and if available. Else return null.

Up to each implementer to decide if this will be cached.

getHomeDirectory

public String getHomeDirectory()

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

Up to each implementer to decide how to implement, and if this will be cached.

getTempDirectory

public String getTempDirectory()

Return the temp directory of the remote system for the current user, if available.

Up to each implementer to decide how to implement, and if this will be cached.

getHostType

public String getHostType()

Return the system type for this connection.

getName

public String getName()

Return the name of this connector service

Specified by:

getName in interface IRSEModelObject

Returns:

the name of this connector service

setHost

public void setHost(IHost host)

getHost

public IHost getHost()

Return the host

Returns:

getHostName

public String getHostName()

Return the host name for the connection this system's subsystem is associated with

getPort

public int getPort()

Return the port for this connector

setPort

public void setPort(int port)

Set the port for this connector

Parameters:

port -

getUserId

public String getUserId()

Return the userId for this system's subsystem we are associated with

setUserId

public void setUserId(String userId)

Set the user id for this connector

Parameters:

userId -

isUsingSSL

public boolean isUsingSSL()

setIsUsingSSL

public void setIsUsingSSL(boolean flag)

promptForPassword

public void promptForPassword(boolean forcePrompt)
                       throws InterruptedException

Return the password for this system's subsystem we are associated with.

If not currently set in transient memory, prompts the user for a password.

Throws InterruptedException if user is prompted and user cancels that prompt.

Parameters:

forcePrompt - forces the prompt dialog to be displayed even if the password is currently in memory.

Throws:

InterruptedException

setPassword

public void setPassword(String matchingUserId,
                        String password)

Set the password if you got it from somewhere

setPassword

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

Set the password if you got it from somewhere

clearUserIdCache

public void clearUserIdCache()

Clear internal userId cache. Called when user uses the property dialog to change his userId.

clearPasswordCache

public void clearPasswordCache()

Clear internal password cache. Called when user uses the property dialog to change his userId.

clearPasswordCache

public void clearPasswordCache(boolean clearDiskCache)

Clear internal password cache. Called when user uses the property dialog to change his userId.

Parameters:

clearDiskCache - if true, clears the password from disk

isPasswordCached

public boolean isPasswordCached()

Return true if password is currently cached.

isPasswordCached

public boolean isPasswordCached(boolean onDisk)

Return true if password is currently cached.

inheritConnectionUserPassword

public boolean inheritConnectionUserPassword()

Return true if this system can inherit the uid and password of other ISystems in this connection

Returns:

true if it can inherit the user/password

shareUserPasswordWithConnection

public boolean shareUserPasswordWithConnection()

addCommunicationsListener

public void addCommunicationsListener(ICommunicationsListener listener)

Register a communications listener

removeCommunicationsListener

public void removeCommunicationsListener(ICommunicationsListener listener)

Remove a communications listener

isSuppressSignonPrompt

public boolean isSuppressSignonPrompt()

Returns the suppressSignonPrompt flag. If this is set to true then the user will not be prompted to signon, instead an InterruptedException will be thrown by the promptForPassword method.

Returns:

boolean

setSuppressSignonPrompt

public void setSuppressSignonPrompt(boolean suppressSignonPrompt)

Sets the suppressSignonPrompt flag. Tool writers can use this to temporarily disable the user from being prompted to signon. This would cause the promptForPassword method to throw an InterruptedException instead of prompting. The intent of this method is to allow tool writeres to prevent multiple signon prompts during a set period of time (such as a series of related communication calls) if the user cancels the first prompt. It is the callers responsability to set this value back to false when the tool no longer needs to suppress the signon prompt or all other tools sharing this connection will be affected.

Parameters:

suppressSignonPrompt -

getRemoteServerLauncherProperties

public IServerLauncherProperties getRemoteServerLauncherProperties()

Returns the value of the 'Remote Server Launcher' containment reference. It is bidirectional and its opposite is 'Parent Sub System'.

Get the remote server launcher, which may be null. This an optional object containing properties used to launch the remote server that communicates with this subsystem.

Returns:

the value of the 'Remote Server Launcher' containment reference.

See Also:

#setRemoteServerLauncher(IServerLauncherProperties), org.eclipse.rse.core.subsystems.SubsystemsPackage#getSubSystem_RemoteServerLauncher(), org.eclipse.rse.core.subsystems.IServerLauncherProperties#getParentSubSystem

setRemoteServerLauncherProperties

public void setRemoteServerLauncherProperties(IServerLauncherProperties value)

Sets the value of the 'Remote Server Launcher' containment reference. Set the remote server launcher, which is an optional object containing properties used to launch the remote server that communicates with this subsystem.

Parameters:

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

See Also:

#getRemoteServerLauncher()

hasRemoteServerLauncherProperties

public boolean hasRemoteServerLauncherProperties()

supportsRemoteServerLaunching

public boolean supportsRemoteServerLaunching()

supportsServerLaunchProperties

public boolean supportsServerLaunchProperties()

Tell us if this subsystem factory supports server launch properties, which allow the user to configure how the server-side code for these subsystems are started. There is a Server Launch Setting property page, with a pluggable composite, where users can configure these properties.

supportsUserId

public boolean supportsUserId()

Report if this connector service can use a user identifier. Returns true in default implementation. 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.

requiresUserId

public boolean requiresUserId()

Report if this connector service requires a user id. Returns true in default implementation. Typically used to indicate if a login dialog can allow an empty user id. Must be ignored if supportsUserId() is false.

Returns:

true or false to indicate if the connector service requires a user id.

supportsPassword

public boolean supportsPassword()

Can be used to determine if a password field is present on a login dialog for this connector service. The default implementation of this interface should return true.

Returns:

true if the subsystem can use a password, false if a password is irrelevant.

requiresPassword

public boolean requiresPassword()

If a password is supported this is used to determine if the password is required. Must be ignored if supportsPassword() returns false. The default implementation of this interface should return true.

Returns:

true if the connector service requires a password, false if a password may be empty.