Remote Systems
v6.4.1

com.ibm.etools.systems.subsystems.impl
Class AbstractSystem

java.lang.Object
  extended bycom.ibm.etools.systems.subsystems.impl.AbstractSystem
All Implemented Interfaces:
ISystem, ISystemUserIdConstants
Direct Known Subclasses:
LocalSystem, UniversalSystem

public abstract class AbstractSystem
extends Object
implements ISystem, ISystemUserIdConstants

This is a base class to make it easier to create system classes.

An ISystem object is returned from a subsystem object via getSystem(), and it is used to represent the live connection to a particular subsystem.

All this could have been done in the subsystem object, but that would clutter it up too much.

You must override/implement

You should override:

See Also:
AbstractSystemManager

Field Summary
protected  Object connectResult
          The result of calling connect in the server launcher object, in the connect method
static String copyright
           
protected  Object launchResult
          The result of calling launch in the server launcher object, in the connect method
protected  Shell shell
           
 
Fields inherited from interface com.ibm.etools.systems.core.ISystemUserIdConstants
USERID_LOCATION_CONNECTION, USERID_LOCATION_DEFAULT_OVERALL, USERID_LOCATION_DEFAULT_SYSTEMTYPE, USERID_LOCATION_NOTSET, USERID_LOCATION_SUBSYSTEM
 
Constructor Summary
AbstractSystem()
          Constructor when we don't have the subsystem.
AbstractSystem(SubSystem subsystem)
          Constructor when we have the subsystem.
 
Method Summary
 void addCommunicationsListener(ICommunicationsListener listener)
          Fully implemented, no need to override.
protected  void clearCommunicationListeners()
          Private - used internally.
 void clearPasswordCache()
          Useful utility method.
 void clearPasswordCache(boolean onDisk)
          Useful utility method.
protected  void clearPasswordForOtherSystemsInConnection(String uid, boolean fromDisk)
           
 void clearUserIdCache()
          Useful utility method.
 void connect(IProgressMonitor monitor)
          Abstract - you must override, unless subsystem.getParentSubSystemFactory().supportsServerLaunchProperties returns true Attempt to connect to the remote system.
 void disconnect()
          Abstract - you must override, unless subsystem.getParentSubSystemFactory().supportsServerLaunchProperties returns true Disconnect from the remote system.
protected  void enableServerLaunchType(SubSystem subsystem, ServerLaunchType serverLaunchType, boolean enable)
          Call this method to identify specific server launch types that are not to be permitted.
protected  void fireCommunicationsEvent(int eventType)
          Private - used internally.
protected  boolean forcePasswordToUpperCase()
          Useful utility method.
protected  int getCommunicationListenerCount()
          Private - used internally.
protected  int getConnectPort()
          Return the port to use for connecting to the remote server, once it is running.
 String getHomeDirectory()
          Not implemented, you should override if possible.
 String getHostName()
          Useful utility method.
protected  String getLocalUserId()
          Useful utility method.
protected  SystemSignonInformation getPasswordInformation()
          Useful utility method.
protected  ISystemPasswordPromptDialog getPasswordPromptDialog(Shell shell)
          A default implementation is supplied, but can be overridden if desired.
 ISystemValidator getPasswordValidator()
          Useful utility method.
 int getPort()
          Useful utility method.
 SubSystem getPrimarySubSystem()
           
 IServerLauncher getRemoteServerLauncher()
          Return the remote server launcher, which implements IServerLauncher.
 ISignonValidator getSignonValidator()
          Optionally overridable, not implemented by default.
 SubSystem getSubSystem()
          Useful utility method.
 String getSystemType()
          Useful utility method.
 String getTempDirectory()
          Not implemented, you should override if possible.
 String getUserId()
          Useful utility method.
 ISystemValidator getUserIdValidator()
          Useful utility method.
 String getVersionReleaseModification()
          Not implemented, you should override if possible.
 boolean inheritConnectionUserPassword()
          Return true if this system can inherit the uid and password of other ISystems in this connection
 boolean isConnected()
          Abstract - you must override unless subsystem.getParentSubSystemFactory().supportsServerLaunchProperties returns true Return true if currently connected.
protected  boolean isEnabledServerLaunchType(SubSystem subsystem, ServerLaunchType serverLaunchType)
          This methods returns the enablement state per server launch type.
 boolean isPasswordCached()
          Useful utility method.
 boolean isPasswordCached(boolean onDisk)
          Useful utility method.
 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)
          Method used internally, and available externally.
 void removeCommunicationsListener(ICommunicationsListener listener)
          Fully implemented, no need to override.
 void reset()
          Optionally override if you add any instance variables.
 void setPassword(String matchingUserId, String password)
          Useful utility method.
 void setPassword(String matchingUserId, String password, boolean persist)
          Useful utility method.
protected  void setPasswordInformation(SystemSignonInformation passwordInfo)
          Useful utility method.
 void setSubSystem(SubSystem ss)
          Set the subsystem, when its not known at constructor time
 void setSuppressSignonPrompt(boolean suppressSignonPrompt)
          Sets the suppressSignonPrompt flag.
 boolean shareUserPasswordWithConnection()
           
protected  void updatePasswordForOtherSystemsInConnection(String uid, String password, boolean persistPassword)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

copyright

public static final String copyright
See Also:
Constant Field Values

shell

protected Shell shell

launchResult

protected Object launchResult
The result of calling launch in the server launcher object, in the connect method


connectResult

protected Object connectResult
The result of calling connect in the server launcher object, in the connect method

Constructor Detail

AbstractSystem

public AbstractSystem()
Constructor when we don't have the subsystem. Be sure to call setSubSystem(SubSystem) after instantiation.


AbstractSystem

public AbstractSystem(SubSystem subsystem)
Constructor when we have the subsystem.

Method Detail

getVersionReleaseModification

public String getVersionReleaseModification()
Not implemented, you should override if possible.
Return the version, release, modification of the remote system, if connected, if applicable and if available. Else return null. It is up to each subsystem to decide how to interpret what is returned.
This is used to show the VRM in the property sheet, when the subsystem is selected.

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

Returns an empty string by default, override if possible

Specified by:
getVersionReleaseModification in interface ISystem

getHomeDirectory

public String getHomeDirectory()
Not implemented, you should override if possible.
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.

Returns an empty string by default, override if possible

Specified by:
getHomeDirectory in interface ISystem

getTempDirectory

public String getTempDirectory()
Not implemented, you should override if possible.
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.

Returns an empty string by default, override if possible

Specified by:
getTempDirectory in interface ISystem

setSubSystem

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

Specified by:
setSubSystem in interface ISystem

getSubSystem

public SubSystem getSubSystem()
Useful utility method. Fully implemented, do not override.
Returns the subsystem object this system is associated with.

Specified by:
getSubSystem in interface ISystem

getPrimarySubSystem

public SubSystem getPrimarySubSystem()

getSystemType

public String getSystemType()
Useful utility method. Fully implemented, do not override.
Returns the system type for this connection:
getSubSystem().getSystemConnection().getSystemType()

Specified by:
getSystemType in interface ISystem

getHostName

public String getHostName()
Useful utility method. Fully implemented, do not override.
Returns the host name for the connection this system's subsystem is associated with:
getSubSystem().getSystemConnection().getHostName()

Specified by:
getHostName in interface ISystem

getPort

public int getPort()
Useful utility method. Fully implemented, do not override.
Returns the port for this subsystem:
getSubSystem().getPort()

Specified by:
getPort in interface ISystem

getUserId

public String getUserId()
Useful utility method. Fully implemented, do not override.
Returns the user Id for this system's subsystem we are associated with. This is the same as getLocalUserId(), but first clears the local user Id cache if we are not currently connected.

Specified by:
getUserId in interface ISystem

getLocalUserId

protected String getLocalUserId()
Useful utility method. Fully implemented, do not override.
Return the userId for this systems' subsystem we are associated with. If there is no local user Id value here, then it is queried from the subsystem. However, if we are connected then the user may have termporarily changed his userId on the userId/password prompt dialog, in which that temp value is stored here in a local cache and this method will return it, versus the persistent user Id stored in the subsystem.


clearUserIdCache

public void clearUserIdCache()
Useful utility method. Fully implemented, do not override.
Clear internal userId cache. Called when user uses the property dialog to change his userId. By default, sets internal userId value to null so that on the next call to getUserId() it is requeried from subsystem. Also calls clearPasswordCache().

Specified by:
clearUserIdCache in interface ISystem

clearPasswordCache

public void clearPasswordCache()
Useful utility method. Fully implemented, do not override.
Clear internal password cache. Called when user uses the property dialog to change his userId. This method does not remove the password from the disk cache - only the memory cache.

Specified by:
clearPasswordCache in interface ISystem
See Also:
clearUserIdCache()

clearPasswordCache

public void clearPasswordCache(boolean onDisk)
Useful utility method. Fully implemented, do not override.
Clear internal password cache. Called when user uses the property dialog to change his userId.

Specified by:
clearPasswordCache in interface ISystem
Parameters:
onDisk - if this is true, clear the password from the disk cache as well
See Also:
#clearUserIdCache(boolean)

isPasswordCached

public boolean isPasswordCached(boolean onDisk)
Useful utility method. Fully implemented, do not override.
Return true if password is currently cached.

Specified by:
isPasswordCached in interface ISystem

isPasswordCached

public boolean isPasswordCached()
Useful utility method. Fully implemented, do not override.
Return true if password is currently cached.

Specified by:
isPasswordCached in interface ISystem

inheritConnectionUserPassword

public boolean inheritConnectionUserPassword()
Return true if this system can inherit the uid and password of other ISystems in this connection

Specified by:
inheritConnectionUserPassword in interface ISystem
Returns:
true if it can inherit the user/password

shareUserPasswordWithConnection

public boolean shareUserPasswordWithConnection()
Specified by:
shareUserPasswordWithConnection in interface ISystem

promptForPassword

public final void promptForPassword(Shell shell,
                                    boolean forcePrompt)
                             throws InterruptedException
Method used internally, and available externally. Fully implemented, do not override.
Return the password for this system's subsystem we are associated with.

The search order for the password is as follows:

  1. First check if the password is in transient memory and that it is still valid.
  2. If password not found in transient memory then check password on disk and verify that it is still valid.
  3. If a valid password is not found in transient memory or on disk then prompt the user.
Throws InterruptedException if user is prompted and user cancels that prompt.

Specified by:
promptForPassword in interface ISystem
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

clearPasswordForOtherSystemsInConnection

protected void clearPasswordForOtherSystemsInConnection(String uid,
                                                        boolean fromDisk)

updatePasswordForOtherSystemsInConnection

protected void updatePasswordForOtherSystemsInConnection(String uid,
                                                         String password,
                                                         boolean persistPassword)

getPasswordPromptDialog

protected final ISystemPasswordPromptDialog getPasswordPromptDialog(Shell shell)
A default implementation is supplied, but can be overridden if desired.
Instantiates and returns the dialog to prompt for the userId.

By default returns an instance of SystemPasswordPromptDialog. Calls forcePasswordToUpperCase() to decide whether the user Id and password should be folded to uppercase.

Calls getUserIdValidator() and getPasswordValidator() to set the validators. These return null by default by you can override them.

Before calling open() on the dialog, the getPassword(Shell) method that calls this will call setSystemInput(this).

After return, it will call wasCancelled() and getUserId(), getIsUserIdChanged(), getIsUserIdChangePermanent() and getPassword().

Returns:
An instance of a dialog class that implements the ISystemPasswordPromptDialog interface

getPasswordInformation

protected SystemSignonInformation getPasswordInformation()
Useful utility method. Fully implemented, no need to override.
Return the password information for this system's subsystem we are associated with. This is transient. Assumes it has been set already. The password stored in SystemSignonInformation is encrypted.


setPasswordInformation

protected void setPasswordInformation(SystemSignonInformation passwordInfo)
Useful utility method. Fully implemented, no need to override.
Sets the password information for this system's subsystem.


setPassword

public void setPassword(String matchingUserId,
                        String password,
                        boolean persist)
Useful utility method. Fully implemented, no need to override.
Set the password if you got it from somewhere

Specified by:
setPassword in interface ISystem

setPassword

public void setPassword(String matchingUserId,
                        String password)
Useful utility method. Fully implemented, no need to override.
Set the password if you got it from somewhere

Specified by:
setPassword in interface ISystem

forcePasswordToUpperCase

protected boolean forcePasswordToUpperCase()
Useful utility method. Fully implemented, no need to override.
Should passwords be folded to uppercase? By default, returns:
getSubSystem().forceUserIdToUpperCase()


getUserIdValidator

public ISystemValidator getUserIdValidator()
Useful utility method. Fully implemented, no need to override.
Get the userId input validator to use in the password dialog prompt.

By default, returns

getSubSystem().getParentSubSystemFactory().getUserIdValidator()


getPasswordValidator

public ISystemValidator getPasswordValidator()
Useful utility method. Fully implemented, no need to override.
Get the password input validator to use in the password dialog prompt.

By default, returns:

getSubSystem().getParentSubSystemFactory().getPasswordValidator()


getSignonValidator

public ISignonValidator getSignonValidator()
Optionally overridable, not implemented by default.
Get the signon validator to use in the password dialog prompt. By default, returns null.


isConnected

public boolean isConnected()
Abstract - you must override unless subsystem.getParentSubSystemFactory().supportsServerLaunchProperties returns true

Return true if currently connected.
If the subsystem supports server launch, the default behaviour here is to see if there is a server launcher created in a previous call to connect, and if so, to test it by calling IServerLauncher.isConnected().

This is called, by default, from the isConnected method of the subsystem.

Specified by:
isConnected in interface ISystem

connect

public void connect(IProgressMonitor monitor)
             throws Exception
Abstract - you must override, unless subsystem.getParentSubSystemFactory().supportsServerLaunchProperties returns true

Attempt to connect to the remote system.
If the subsystem supports server launch, the default behaviour here is to get the remote server launcher via getRemoteServerLauncher(), and if IServerLauncher.isLaunched() returns false, to call IServerLauncher.launch(IProgressMonitor).

This is called, by default, from the connect(...) methods of the subsystem.

Specified by:
connect in interface ISystem
Throws:
Exception

getConnectPort

protected int getConnectPort()
Return the port to use for connecting to the remote server, once it is running. By default, this is the subsystem's port property, via getPort(). Override if appropriate.
This is called by the default implementation of connect(IProgressMonitor), if subsystem.getParentSubSystemFactory().supportsServerLaunchProperties() is true.


disconnect

public void disconnect()
                throws Exception
Abstract - you must override, unless subsystem.getParentSubSystemFactory().supportsServerLaunchProperties returns true

Disconnect from the remote system.
If the subsystem supports server launch, the default behaviour here is to use the same remote server launcher created in connect(), and call IServerLauncher.disconnect().

This is called, by default, from the disConnect(..) method of the subsystem.

Specified by:
disconnect in interface ISystem
Throws:
Exception

getRemoteServerLauncher

public IServerLauncher getRemoteServerLauncher()
Return the remote server launcher, which implements IServerLauncher. This is called by the default implementation of connect() and disconnect(), if subsystem.getParentSubSystemFactory().supportsServerLaunchProperties returns true.

This returns null be default!


reset

public void reset()
Optionally override if you add any instance variables.
The following is called whenever a system is redefined or disconnected. Each subsystem needs to be informed so it can clear out any expansions, etc. By default it does nothing. Override if you have an internal object that must be nulled out.

Specified by:
reset in interface ISystem

addCommunicationsListener

public void addCommunicationsListener(ICommunicationsListener listener)
Fully implemented, no need to override.

Specified by:
addCommunicationsListener in interface ISystem
See Also:
ISystem.addCommunicationsListener(ICommunicationsListener)

removeCommunicationsListener

public void removeCommunicationsListener(ICommunicationsListener listener)
Fully implemented, no need to override.

Specified by:
removeCommunicationsListener in interface ISystem
See Also:
ISystem.removeCommunicationsListener(ICommunicationsListener)

fireCommunicationsEvent

protected void fireCommunicationsEvent(int eventType)
Private - used internally.
Helper method for firing communication events


getCommunicationListenerCount

protected int getCommunicationListenerCount()
Private - used internally.
Returns the count of active communication listeners (i.e. excludes passive listeners.)


clearCommunicationListeners

protected void clearCommunicationListeners()
Private - used internally.


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.

Specified by:
isSuppressSignonPrompt in interface ISystem
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.

Specified by:
setSuppressSignonPrompt in interface ISystem
Parameters:
suppressSignonPrompt -

enableServerLaunchType

protected void enableServerLaunchType(SubSystem subsystem,
                                      ServerLaunchType serverLaunchType,
                                      boolean enable)
Call this method to identify specific server launch types that are not to be permitted.

You normally do not call this! Rather, your subsystem factory class will override SubSystemFactoryImpl.supportsServerLaunchType(ServerLaunchType). However, this method is needed by ISVs that re-use IBM-supplied subsystem factories, and merely supply their own ISystem object via the "systemClass" attribute of the subsystemfactory extension point.

See Also:
ServerLaunchType

isEnabledServerLaunchType

protected boolean isEnabledServerLaunchType(SubSystem subsystem,
                                            ServerLaunchType serverLaunchType)
This methods returns the enablement state per server launch type. If #enableServerLaunchType(ServerLaunchType,boolean) has not been called for this server launch type, then it is enabled by default.

See Also:
ServerLaunchType

notifyDisconnection

public void notifyDisconnection()
Description copied from interface: ISystem
Notifies all listeners of a disconnection through a communications event

Specified by:
notifyDisconnection in interface ISystem

notifyConnection

public void notifyConnection()
Description copied from interface: ISystem
Notifies all listeners of a connection through a communications event

Specified by:
notifyConnection in interface ISystem

notifyError

public void notifyError()
Description copied from interface: ISystem
Notifies all listeners of an error through a communications event

Specified by:
notifyError in interface ISystem

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.