Remote Systems
v6.4.1

com.ibm.etools.systems.subsystems
Interface ISystem

All Known Implementing Classes:
AbstractSystem

public interface ISystem

This is the interface implemented by System objects.

A system object 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. Any information in a System object is thrown out when the workbench goes down... it is not modelled for persistence.

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

A single system object can be unique to a subsystem (which is always unique for a particular tool to a particular connection). It can also be shared across multiple subsystems in a single connection if those subsystems share their physical connection to the remote system. This sharing is done via subclasses of AbstractSystemManager which are returned via another getter method in SubSystem.


Field Summary
static String copyright
           
 
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 disconnect()
          Disconnect from the remote system
 String getHomeDirectory()
          Return the home directory of the remote system for the current user, if available.
 String getHostName()
          Return the host name for the connection this system's subsystem is associated with
 int getPort()
          Return the port for this subsystem
 SubSystem getSubSystem()
          Return the subsystem object this system is associated with
 String getSystemType()
          Return the system type for this connection.
 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 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.
 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(Shell shell, boolean forcePrompt)
          Return the password for this system's subsystem we are associated with.
 void removeCommunicationsListener(ICommunicationsListener listener)
          Remove a communications listener
 void reset()
          Reset after some fundamental change, such as a hostname change.
 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 setSubSystem(SubSystem ss)
          Set the subsystem, when its not known at constructor time
 void setSuppressSignonPrompt(boolean suppressSignonPrompt)
          Sets the suppressSignonPrompt flag.
 boolean shareUserPasswordWithConnection()
           
 

Field Detail

copyright

public static final String copyright
See Also:
Constant Field Values
Method Detail

getSubSystem

public SubSystem getSubSystem()
Return the subsystem object this system is associated with


setSubSystem

public void setSubSystem(SubSystem ss)
Set the subsystem, when its not known at constructor time


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()
                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.


getSystemType

public String getSystemType()
Return the system type for this connection.


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 subsystem


getUserId

public String getUserId()
Return the userId for this system's subsystem we are associated with


promptForPassword

public void promptForPassword(Shell shell,
                              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:
shell - parent for the prompt dialog if needed. Can be null if know password exists.
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 -

Remote Systems
v6.4.1

Copyright © 2005 IBM Corp. All Rights Reserved.

Note: This documentation is for part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.