[168977][api][refactor] - stage 3.7

javadoc and minor cleanup

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/AbstractConnectorService.java

@@ -25,34 +25,17 @@ import org.eclipse.rse.core.model.IHost;
 import org.eclipse.rse.core.model.RSEModelObject;
 
 /**
- * This is a base class to make it easier to create connector service classes.
+ * This is a base class to make it easier to create connector services.
  * <p>
  * An {@link org.eclipse.rse.core.subsystems.IConnectorService} object
  * is returned from a subsystem object via getConnectorService(), and
- * it is used to represent the live connection to a particular subsystem.
+ * it is used to maintain the connection to a particular set of subsystems.
  * <p>
- * You must override/implement
+ * This class implements the protocol for much of the 
- * <ul>
+ * standard bookkeeping for connector services including
- * <li>isConnected
+ * server launchers (if none are required), event handling,
- * <li>internalConnect
+ * hosts, ports, addresses, descriptions, and registered subsystems.
- * <li>internalDisconnect
+ * Subclasses must concern themselves with actually authenticating and connecting.
- * <li>getCredentialsProvider
- * </ul>
- * You should override:
- * <ul>
- * <li>reset 
- * <li>getVersionReleaseModification
- * <li>getHomeDirectory
- * <li>getTempDirectory
- * </ul>
- * You can override:
- * <ul>
- * <li>supportsUserId
- * <li>requiresUserId
- * <li>supportsPassword
- * <li>requiresPassword
- * </ul>
- * 
  */ 
 public abstract class AbstractConnectorService extends RSEModelObject implements IConnectorService {
 
@@ -66,14 +49,15 @@ public abstract class AbstractConnectorService extends RSEModelObject implements
 	private boolean _usingSSL;
 
 	/**
-	 * The result of calling launch in the server launcher object, in the connect method  
+	 * Construct a new connector service. This should be called during the construction
+	 * of any subclasses.
+	 * @param name The name of the connector service.
+	 * @param description A description of the connector service.
+	 * @param host The host associated with this connector service. A host may have multiple
+	 * connector services.
+	 * @param port The port associated with this connector service if this connector service
+	 * is IP based. If not IP based this can be used for some other purpose.
 	 */
-	protected Object launchResult;
-	/**
-	 * The result of calling connect in the server launcher object, in the connect method
-	 */
-	protected Object connectResult;
-
 	public AbstractConnectorService(String name, String description, IHost host, int port) {
 		_name = name;
 		_description = description;
@@ -81,6 +65,9 @@ public abstract class AbstractConnectorService extends RSEModelObject implements
 		_port = port;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#isServerLaunchTypeEnabled(org.eclipse.rse.core.subsystems.ISubSystem, org.eclipse.rse.core.subsystems.ServerLaunchType)
+	 */
 	public final boolean isServerLaunchTypeEnabled(ISubSystem subsystem, ServerLaunchType serverLaunchType) {
 		IServerLauncher sl = getRemoteServerLauncher();
 		if (sl instanceof RemoteServerLauncher) {
@@ -90,22 +77,43 @@ public abstract class AbstractConnectorService extends RSEModelObject implements
 			return subsystem.getSubSystemConfiguration().supportsServerLaunchType(serverLaunchType);
 	}
 	
+	/**
+	 * @return null, may be overriden
+	 * @see IConnectorService#getRemoteServerLauncher()
+	 */
 	public IServerLauncher getRemoteServerLauncher() {
 		return null;
 	}
 
+	/**
+	 * @return false, may be overriden
+	 * @see IConnectorService#supportsRemoteServerLaunching()
+	 */
 	public boolean supportsRemoteServerLaunching() {
 		return false;
 	}
 
+	/**
+	 * @return false, may be overriden
+	 * @see IConnectorService#supportsServerLaunchProperties()
+	 */
 	public boolean supportsServerLaunchProperties() {
 		return false;
 	}
 	
+	/**
+	 * @return null, may be overriden
+	 * @see IConnectorService#getRemoteServerLauncherProperties()
+	 */
 	public IServerLauncherProperties getRemoteServerLauncherProperties() {
 		return null;
 	}
 
+	/**
+	 * Do nothing, may be overriden
+	 * @param newRemoteServerLauncher the server launcher properties
+	 * @see IConnectorService#setRemoteServerLauncherProperties(IServerLauncherProperties)
+	 */
 	public void setRemoteServerLauncherProperties(IServerLauncherProperties newRemoteServerLauncher) {
 	}
 
@@ -113,9 +121,8 @@ public abstract class AbstractConnectorService extends RSEModelObject implements
 		return getRemoteServerLauncherProperties() != null;
 	}
 
-	/**
+	/* (non-Javadoc)
-	 * <i>Fully implemented, no need to override.</i><br>
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#addCommunicationsListener(org.eclipse.rse.core.subsystems.ICommunicationsListener)
-	 * @see IConnectorService#addCommunicationsListener(ICommunicationsListener)
 	 */
 	public final void addCommunicationsListener(ICommunicationsListener listener) {
 		if (!commListeners.contains(listener)) {
@@ -123,9 +130,8 @@ public abstract class AbstractConnectorService extends RSEModelObject implements
 		}
 	}
 
-	/**
+	/* (non-Javadoc)
-	 * <i>Fully implemented, no need to override.</i><br>
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#removeCommunicationsListener(org.eclipse.rse.core.subsystems.ICommunicationsListener)
-	 * @see IConnectorService#removeCommunicationsListener(ICommunicationsListener)
 	 */
 	public final void removeCommunicationsListener(ICommunicationsListener listener) {
 		commListeners.remove(listener);		
@@ -143,25 +149,37 @@ public abstract class AbstractConnectorService extends RSEModelObject implements
 		}							
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getHost()
+	 */
 	public final IHost getHost() {
 		return _host;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setHost(org.eclipse.rse.core.model.IHost)
+	 */
 	public final void setHost(IHost host) {
 		_host = host;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.RSEModelObject#getDescription()
+	 */
 	public final String getDescription() {
 		return _description;
 	}
 
-	/**
+	/* (non-Javadoc)
-	 * 
+	 * @see org.eclipse.rse.core.model.IRSEModelObject#getName()
 	 */
 	public final String getName() {
 		return _name;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setPort(int)
+	 */
 	public final void setPort(int port) {
 		if (port != _port)
 		{
@@ -170,10 +188,16 @@ public abstract class AbstractConnectorService extends RSEModelObject implements
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getPort()
+	 */
 	public final int getPort() {
 		return _port;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getPrimarySubSystem()
+	 */
 	public final ISubSystem getPrimarySubSystem() {
 		if (_primarySubSystem == null)
 		{
@@ -190,8 +214,8 @@ public abstract class AbstractConnectorService extends RSEModelObject implements
 		return _primarySubSystem;
 	}
 
-	/**
+	/* (non-Javadoc)
-	 * Set the subsystem, when its not known at constructor time
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#registerSubSystem(org.eclipse.rse.core.subsystems.ISubSystem)
 	 */
 	public final void registerSubSystem(ISubSystem ss) {
 		if (!_registeredSubSystems.contains(ss))
@@ -200,56 +224,52 @@ public abstract class AbstractConnectorService extends RSEModelObject implements
 		}   	
 	}
 
-	/**
+	/* (non-Javadoc)
-	 * Removes the subsystem from teh list
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#deregisterSubSystem(org.eclipse.rse.core.subsystems.ISubSystem)
-	 * @param ss
 	 */
 	public final void deregisterSubSystem(ISubSystem ss) {
 		_registeredSubSystems.remove(ss);
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.IRSEPersistableContainer#commit()
+	 */
 	public final boolean commit() {
 		return RSECorePlugin.getThePersistenceManager().commit(getHost());
 	}
 
-	/**
+	/* (non-Javadoc)
-	 * <i>Useful utility method. Fully implemented, do not override.</i><br>
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getHostType()
-	 * Returns the system type for this connection:<br> <code>getSubSystem().getSystemConnection().getSystemType()</code>
 	 */
 	public final String getHostType() {
 		return getHost().getSystemType();
 	}
 
-	/**
+	/* (non-Javadoc)
-	 * <i>Useful utility method. Fully implemented, do not override.</i><br>
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getHostName()
-	 * Returns the host name for the connection this system's subsystem is associated with:</br>
-	 * <code>getSubSystem().getSystemConnection().getHostName()</code>
 	 */
 	public final String getHostName() {
 		return getHost().getHostName();
 	}
 
-	/**
+	/* (non-Javadoc)
-	 * Return the version, release, modification of the remote system,
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getVersionReleaseModification()
-	 * 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 implementation returns the empty string.
-	 * <p>
-	 * This is used to show the VRM in the property sheet 
-	 * when the subsystem is selected.
-	 * <p>
-	 * Up to each implementer to decide if this will be cached.
-	 * <p>
-	 * @return an empty string
 	 */
 	public String getVersionReleaseModification() {
 		return ""; //$NON-NLS-1$
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getSubSystems()
+	 */
 	public final ISubSystem[] getSubSystems() {
 		return (ISubSystem[])_registeredSubSystems.toArray(new ISubSystem[_registeredSubSystems.size()]);
 	}
 
+	/**
+	 * Initialize any subsystems just after connecting to the host.
+	 * @param monitor a progress monitor to report progress of initialization.
+	 */
 	protected final void intializeSubSystems(IProgressMonitor monitor) {
 		for (int i = 0; i < _registeredSubSystems.size(); i++)
 		{
@@ -258,6 +278,10 @@ public abstract class AbstractConnectorService extends RSEModelObject implements
 		}
 	}
 
+	/**
+	 * Uninitialize any subsystem just after disconnecting from the host.
+	 * @param monitor a progress monitor used to track uninitialization progress.
+	 */
 	protected final void unintializeSubSystems(IProgressMonitor monitor) {
 		for (int i = 0; i < _registeredSubSystems.size(); i++)
 		{
@@ -266,23 +290,44 @@ public abstract class AbstractConnectorService extends RSEModelObject implements
 		}
 	}
 
+	/**
+	 * Send the event to notify listeners of a disconnection.
+	 * Used by the framework and should
+	 * usually not be invoked by concrete subclasses.
+	 */
 	protected final void notifyDisconnection() {
 		 // Fire comm event to signal state changed
 		if (!isConnected()) fireCommunicationsEvent(CommunicationsEvent.AFTER_DISCONNECT);
 	}
 
+	/**
+	 * Send the event to notify listeners of a connection.
+	 * Used by the framework and should
+	 * usually not be invoked by concrete subclasses.
+	 */
 	protected final void notifyConnection() {
 		if (isConnected()) fireCommunicationsEvent(CommunicationsEvent.AFTER_CONNECT);
 	}
 
+	/**
+	 * Send the event to notify listeners of a connection establishment error.
+	 * Used by the framework and should
+	 * usually not be invoked by concrete subclasses.
+	 */
 	protected final void notifyError() {
 		fireCommunicationsEvent(CommunicationsEvent.CONNECTION_ERROR);
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#isUsingSSL()
+	 */
 	public final boolean isUsingSSL() {
 		return _usingSSL;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setIsUsingSSL(boolean)
+	 */
 	public final void setIsUsingSSL(boolean flag) {
 		if (_usingSSL != flag)
 		{
@@ -292,10 +337,10 @@ public abstract class AbstractConnectorService extends RSEModelObject implements
 	}
 
 	/**
-	 * Return the temp directory of the remote system for the current user,
+	 * Returns the temp directory of the remote system for the current user,
 	 * if available. This implementation returns the empty string.
-	 * Up to each implementer to decide how to implement, and if this will be cached.
 	 * @return an empty string
+	 * @see IConnectorService#getTempDirectory()
 	 */
 	public String getTempDirectory() {
 		return ""; //$NON-NLS-1$
@@ -304,71 +349,111 @@ public abstract class AbstractConnectorService extends RSEModelObject implements
 	/**
 	 * Returns the home directory of the remote system for the current user,
 	 * if available. This implementation returns the empty string.
-	 * Up to each implementer to decide how to implement, and if this will be cached.
 	 * @return an empty string
+	 * @see IConnectorService#getHomeDirectory()
 	 */
 	public String getHomeDirectory() {
 		return ""; //$NON-NLS-1$
 	}
 
 	/**
-	 * <i>Optionally override if you add any instance variables.</i><br>
+	 * Reset the connector service state if a connector service is redefined
-	 * The following is called whenever a system is redefined or disconnected.
+	 * or disconnected.
-	 * Each subsystem needs to be informed so it can clear out any expansions, etc.
+	 * Each subsystem needs to be informed so it can clear out any expansions.
-	 * By default it does nothing.
+	 * This implementation does nothing.
-	 * Override if you have an internal object that must be nulled out.
+	 * Implementations should override and call {@link #reset()} 
-	 * If overridden you should call super.reset();
+	 * if there is internal state to reset.
+	 * @see IConnectorService#reset()
 	 */
 	public void reset() {
 	}
 
 	/**
-	 * Return the port to use for connecting to the remote server, once it is running.
+	 * This implementation returns the connector service's port property.
-	 * By default, this is the subsystem's port property, via {@link #getPort()}.
 	 * Override if appropriate. 
-	 * <br> This is called by the default implementation of {@link #connect(IProgressMonitor)}, if
+	 * <br> This is called by the default implementation of
-	 * subsystem.getParentSubSystemConfiguration().supportsServerLaunchProperties() is true.
+	 * {@link #connect(IProgressMonitor)}, 
+	 * if #supportsServerLaunchProperties() is true.
+	 * @return the port used for connecting to the target
 	 */
 	protected int getConnectPort() {
 		return getPort();
 	}
 
 	/**
-	 * This connection method wrappers the others (internal connect) so that registered subsystems 
+	 * Connects to the target system.
-	 * can be notified and initialized after a connect
+	 * Calls {@link #internalConnect(IProgressMonitor)}
-	 * Previous implementations that overrode this method should now change
+	 * @param monitor a monitor for progress monitoring and cancelation.
-	 * their connect() method to internalConnect()
+	 * @throws Exception if the connect fails
 	 */
 	public final void connect(IProgressMonitor monitor) throws Exception {
+		preConnect();
 		internalConnect(monitor);
 		intializeSubSystems(monitor);
+		postConnect();
 	}
 
 	/**
-	 * Disconnects from the remote system.
+	 * Disconnects from the target system.
-	 * <p>
+	 * Calls {@link #internalDisconnect(IProgressMonitor)}
-	 * You must override
+	 * and {@link #postDisconnect()}
-	 * if <code>subsystem.getParentSubSystemConfiguration().supportsServerLaunchProperties</code> 
+	 * @throws Exception if the disconnect fails 
-	 * returns false.
-	 * <p>
-	 * If the subsystem supports server launch
-	 * the default behavior is to use the same remote server
-	 * launcher created in <code>connect()</code> and call <code>disconnect()</code>.
-	 * <p>
-	 * This is called, by default, from the <code>disconnect()</code>
-	 * method of the subsystem.
-	 * @see IServerLauncher#disconnect()
 	 */
 	public final void disconnect(IProgressMonitor monitor) throws Exception {
+		preDisconnect();
 		internalDisconnect(monitor);
 		unintializeSubSystems(monitor);
 		postDisconnect();
 	}
 
+	/**
+	 * Performs the actual connection to the target system.
+	 * @param monitor for cancelation and progress reporting
+	 * @throws Exception if connection does not succeed
+	 */
 	protected abstract void internalConnect(IProgressMonitor monitor) throws Exception;
 
+	/**
+	 * Performs the actual disconnection from the target system.
+	 * @param monitor for cancelation and progress reporting
+	 * @throws Exception if disconnection does not succeed
+	 */
 	protected abstract void internalDisconnect(IProgressMonitor monitor) throws Exception;
 
-	protected abstract void postDisconnect();
+	/**
-		
+	 * Performs any cleanup required after disconnecting.
+	 * This implementation does nothing.
+	 * May be overridden.
+	 * If overridden, invoke via super.
+	 */
+	protected void postDisconnect() {
+	}
+	
+	/**
+	 * Performs any tasks required immediately prior to disconnecting.
+	 * This implementation does nothing.
+	 * May be overridden.
+	 * If overridden, invoke via super.
+	 */
+	protected void preDisconnect() {
+	}
+	
+	/**
+	 * Performs any tasks required immediately prior to connecting.
+	 * This implementation does nothing.
+	 * May be overridden.
+	 * If overridden, invoke via super.
+	 */
+	protected void preConnect() {
+	}
+	
+	/**
+	 * Performs any tasks required immediately after connecting.
+	 * This implementation does nothing.
+	 * May be overridden.
+	 * If overridden, invoke via super.
+	 */
+	protected void postConnect() {
+	}
+
 }

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/AbstractDelegatingConnectorService.java

@@ -21,13 +21,25 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 {
 
 	protected IHost _host;
+
+	/**
+	 * Creates a new delegating connector service for a particular host.
+	 * Should be invoked from the constructor for any concrete subclasses.
+	 * @param host The host associated with this connector service.
+	 */
 	public AbstractDelegatingConnectorService(IHost host)
 	{
 		_host = host;
 	}
 	
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IDelegatingConnectorService#getRealConnectorService()
+	 */
 	public abstract IConnectorService getRealConnectorService();
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#addCommunicationsListener(org.eclipse.rse.core.subsystems.ICommunicationsListener)
+	 */
 	public void addCommunicationsListener(ICommunicationsListener listener) 
 	{
 		IConnectorService conServ = getRealConnectorService();
@@ -37,6 +49,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 	
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.IPropertySetContainer#addPropertySet(org.eclipse.rse.core.model.IPropertySet)
+	 */
 	public boolean addPropertySet(IPropertySet set) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -46,6 +61,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.IPropertySetContainer#addPropertySets(org.eclipse.rse.core.model.IPropertySet[])
+	 */
 	public boolean addPropertySets(IPropertySet[] sets) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -55,6 +73,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#clearPassword(boolean, boolean)
+	 */
 	public void clearPassword(boolean clearDiskCache, boolean propagate) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -63,6 +84,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#clearCredentials()
+	 */
 	public void clearCredentials() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -71,6 +95,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.IRSEPersistableContainer#commit()
+	 */
 	public boolean commit() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -80,6 +107,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#connect(org.eclipse.core.runtime.IProgressMonitor)
+	 */
 	public void connect(IProgressMonitor monitor) throws Exception {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -88,6 +118,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.IPropertySetContainer#createPropertySet(java.lang.String)
+	 */
 	public IPropertySet createPropertySet(String name) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -97,6 +130,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.IPropertySetContainer#createPropertySet(java.lang.String, java.lang.String)
+	 */
 	public IPropertySet createPropertySet(String name, String description) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -106,6 +142,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#deregisterSubSystem(org.eclipse.rse.core.subsystems.ISubSystem)
+	 */
 	public void deregisterSubSystem(ISubSystem ss) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -114,6 +153,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#disconnect(org.eclipse.core.runtime.IProgressMonitor)
+	 */
 	public void disconnect(IProgressMonitor monitor) throws Exception {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -122,6 +164,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.IRSEModelObject#getDescription()
+	 */
 	public String getDescription() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -131,6 +176,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getHomeDirectory()
+	 */
 	public String getHomeDirectory() 
 	{
 		IConnectorService conServ = getRealConnectorService();
@@ -141,11 +189,17 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getHost()
+	 */
 	public IHost getHost() 
 	{
 		return _host;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getHostName()
+	 */
 	public String getHostName() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -155,6 +209,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getHostType()
+	 */
 	public String getHostType() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -164,6 +221,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.IRSEModelObject#getName()
+	 */
 	public String getName() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -173,6 +233,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getPort()
+	 */
 	public int getPort() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -182,6 +245,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return 0;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getPrimarySubSystem()
+	 */
 	public ISubSystem getPrimarySubSystem() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -191,6 +257,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.IPropertySetContainer#getPropertySet(java.lang.String)
+	 */
 	public IPropertySet getPropertySet(String name) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -200,6 +269,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.IPropertySetContainer#getPropertySets()
+	 */
 	public IPropertySet[] getPropertySets() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -209,6 +281,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getRemoteServerLauncher()
+	 */
 	public IServerLauncher getRemoteServerLauncher() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -218,6 +293,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getRemoteServerLauncherProperties()
+	 */
 	public IServerLauncherProperties getRemoteServerLauncherProperties() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -227,6 +305,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getSubSystems()
+	 */
 	public ISubSystem[] getSubSystems() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -236,6 +317,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getTempDirectory()
+	 */
 	public String getTempDirectory() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -245,6 +329,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getUserId()
+	 */
 	public String getUserId() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -254,6 +341,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getVersionReleaseModification()
+	 */
 	public String getVersionReleaseModification() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -263,6 +353,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return null;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#hasPassword(boolean)
+	 */
 	public boolean hasPassword(boolean onDisk) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -272,6 +365,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#hasRemoteServerLauncherProperties()
+	 */
 	public boolean hasRemoteServerLauncherProperties() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -281,6 +377,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#inheritsCredentials()
+	 */
 	public boolean inheritsCredentials() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -290,6 +389,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#isConnected()
+	 */
 	public boolean isConnected() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -299,6 +401,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.IRSEPersistableContainer#isDirty()
+	 */
 	public boolean isDirty() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -308,6 +413,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#isServerLaunchTypeEnabled(org.eclipse.rse.core.subsystems.ISubSystem, org.eclipse.rse.core.subsystems.ServerLaunchType)
+	 */
 	public boolean isServerLaunchTypeEnabled(ISubSystem subsystem,
 			ServerLaunchType serverLaunchType) {
 		IConnectorService conServ = getRealConnectorService();
@@ -318,6 +426,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#isSuppressed()
+	 */
 	public boolean isSuppressed() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -327,6 +438,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#isUsingSSL()
+	 */
 	public boolean isUsingSSL() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -336,6 +450,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#acquireCredentials(boolean)
+	 */
 	public void acquireCredentials(boolean forcePrompt)
 			throws InterruptedException {
 		IConnectorService conServ = getRealConnectorService();
@@ -345,6 +462,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#registerSubSystem(org.eclipse.rse.core.subsystems.ISubSystem)
+	 */
 	public void registerSubSystem(ISubSystem ss) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -353,6 +473,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#removeCommunicationsListener(org.eclipse.rse.core.subsystems.ICommunicationsListener)
+	 */
 	public void removeCommunicationsListener(ICommunicationsListener listener) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -361,6 +484,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.IPropertySetContainer#removePropertySet(java.lang.String)
+	 */
 	public boolean removePropertySet(String name) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -370,6 +496,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#reset()
+	 */
 	public void reset() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -378,6 +507,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.IRSEPersistableContainer#setDirty(boolean)
+	 */
 	public void setDirty(boolean flag) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -386,6 +518,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setHost(org.eclipse.rse.core.model.IHost)
+	 */
 	public void setHost(IHost host) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -394,6 +529,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setIsUsingSSL(boolean)
+	 */
 	public void setIsUsingSSL(boolean flag) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -402,6 +540,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setPassword(java.lang.String, java.lang.String, boolean, boolean)
+	 */
 	public void setPassword(String matchingUserId, String password,
 			boolean persist, boolean propagate) {
 		IConnectorService conServ = getRealConnectorService();
@@ -411,6 +552,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setPort(int)
+	 */
 	public void setPort(int port) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -419,6 +563,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setRemoteServerLauncherProperties(org.eclipse.rse.core.subsystems.IServerLauncherProperties)
+	 */
 	public void setRemoteServerLauncherProperties(
 			IServerLauncherProperties value) {
 		IConnectorService conServ = getRealConnectorService();
@@ -428,6 +575,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setSuppressed(boolean)
+	 */
 	public void setSuppressed(boolean suppressSignonPrompt) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -436,6 +586,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setUserId(java.lang.String)
+	 */
 	public void setUserId(String userId) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -444,6 +597,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.IRSEPersistableContainer#setWasRestored(boolean)
+	 */
 	public void setWasRestored(boolean flag) {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -452,6 +608,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#sharesCredentials()
+	 */
 	public boolean sharesCredentials() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -461,6 +620,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#supportsPassword()
+	 */
 	public boolean supportsPassword() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -470,6 +632,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#supportsRemoteServerLaunching()
+	 */
 	public boolean supportsRemoteServerLaunching() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -479,6 +644,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#supportsServerLaunchProperties()
+	 */
 	public boolean supportsServerLaunchProperties() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -489,6 +657,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 	}
 
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#supportsUserId()
+	 */
 	public boolean supportsUserId() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -498,6 +669,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 	
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#saveUserId()
+	 */
 	public void saveUserId() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -506,6 +680,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 	
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#removeUserId()
+	 */
 	public void removeUserId() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -514,6 +691,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#savePassword()
+	 */
 	public void savePassword() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -522,6 +702,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#removePassword()
+	 */
 	public void removePassword() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -530,6 +713,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		}
 	}
 	
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.model.IRSEPersistableContainer#wasRestored()
+	 */
 	public boolean wasRestored() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -539,6 +725,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 	
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#requiresPassword()
+	 */
 	public boolean requiresPassword() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)
@@ -548,6 +737,9 @@ public abstract class AbstractDelegatingConnectorService implements IDelegatingC
 		return false;
 	}
 	
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#requiresUserId()
+	 */
 	public boolean requiresUserId() {
 		IConnectorService conServ = getRealConnectorService();
 		if (conServ != null)

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/AuthenticatingConnectorService.java

@@ -10,24 +10,43 @@ import org.eclipse.rse.core.model.IHost;
 import org.eclipse.rse.core.model.ISystemRegistry;
 import org.eclipse.rse.core.model.SystemSignonInformation;
 
+/**
+ * An authenticating connector service understands the concept of credentials
+ * (see {@link ICredentials})
+ * and possibly the concepts of user id and password. It contains a 
+ * credentials provider ({@link ICredentialsProvider}) and provides a 
+ * framework under which authentication can take place during connections.
+ */
 public abstract class AuthenticatingConnectorService extends AbstractConnectorService {
 	
 	protected ICredentialsProvider credentialsProvider = null;
 
+	/**
+	 * Constructs an authenticating connector service.
+	 * @param name The name of the connector service
+	 * @param description The description of the connector service
+	 * @param host The host associated with this connector service
+	 * @param port The port this connector service will use when connecting if it uses IP.
+	 */
 	public AuthenticatingConnectorService(String name, String description, IHost host, int port) {
 		super(name, description, host, port);
 	}
 
 	/**
-	 * <i>Useful utility method. Fully implemented, do not override.</i><br>
+	 * Obtains the user id, if it understand the concept of user id, from
-	 * Returns the active userId if we are connected.
+	 * its credentials provider.
-	 * If not it returns the userId for the primary subsystem ignoring the 
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getUserId()
-	 * cached userId.
+	 * @return the user id or null if not available or not supported.
 	 */
 	public final String getUserId() {
 		return credentialsProvider.getUserId();
 	}
 
+	/**
+	 * Sets the default user id for use by the credentials provider.
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setUserId(java.lang.String)
+	 * @param newId the id to be used by the credentials provider.
+	 */
 	public final void setUserId(String newId) {
 		String oldUserId = credentialsProvider.getUserId();
 		if (oldUserId == null || oldUserId.equals(newId)) {
@@ -37,22 +56,23 @@ public abstract class AuthenticatingConnectorService extends AbstractConnectorSe
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#saveUserId()
+	 */
 	public final void saveUserId() {
 		String userId = credentialsProvider.getUserId();
 		updateDefaultUserId(getPrimarySubSystem(), userId);
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#removeUserId()
+	 */
 	public final void removeUserId() {
 		updateDefaultUserId(getPrimarySubSystem(), null);
 	}
 
-	/**
+	/* (non-Javadoc)
-	 * <i>Useful utility method. Fully implemented, do not override.</i><br>
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#clearPassword(boolean, boolean)
-	 * Clear internal password cache. Called when user uses the property dialog to 
-	 * change his userId.  
-	 * 
-	 * @param persist if this is true, clear the password from the disk cache as well
-	 * @see #clearCredentials()
 	 */
 	public final void clearPassword(boolean persist, boolean propagate) {
 		credentialsProvider.clearPassword();
@@ -65,17 +85,12 @@ public abstract class AuthenticatingConnectorService extends AbstractConnectorSe
 		}
 	}
 
-	/**
+	/* (non-Javadoc)
-	 * <i>Useful utility method. Fully implemented, do not override.</i><br>
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#hasPassword(boolean)
-	 * Return true if password is currently saved either here or in its persisted
-	 * form.
-	 * @param onDisk true if the check should be made for a persisted form as well, 
-	 * false if the check should be made for a password in memory only.
-	 * @return true if the password is known, false otherwise.
 	 */
 	public final boolean hasPassword(boolean onDisk) {
-		SystemSignonInformation signonInformation = getSignonInformation();
+		ICredentials credentials = credentialsProvider.getCredentials();
-		boolean cached = (signonInformation != null && signonInformation.getPassword() != null);
+		boolean cached = (credentials != null && credentials.getPassword() != null);
 		if (!cached && onDisk) {
 			String systemType = getHostType();
 			String hostName = getHostName();
@@ -87,14 +102,8 @@ public abstract class AuthenticatingConnectorService extends AbstractConnectorSe
 		return cached;
 	}
 
-	/**
+	/* (non-Javadoc)
-	 * <i>Useful utility method. Fully implemented, no need to override.</i><br>
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setPassword(java.lang.String, java.lang.String, boolean, boolean)
-	 * Set the password if you got it from somewhere
-	 * @param userId the user for which to set the password
-	 * @param password the password to set for this userId
-	 * @param persist true if the password is to be persisted, 
-	 * false if its persistent form is to be removed.
-	 * @param propagate if the password should be propagated to related connector services.
 	 */
 	public final void setPassword(String userId, String password, boolean persist, boolean propagate) {
 		if (getPrimarySubSystem().forceUserIdToUpperCase()) {
@@ -115,6 +124,9 @@ public abstract class AuthenticatingConnectorService extends AbstractConnectorSe
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#savePassword()
+	 */
 	public final void savePassword() {
 		ICredentials credentials = credentialsProvider.getCredentials();
 		if (credentials instanceof SystemSignonInformation) {
@@ -123,6 +135,9 @@ public abstract class AuthenticatingConnectorService extends AbstractConnectorSe
 		}
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#removePassword()
+	 */
 	public final void removePassword() {
 		String systemType = getHostType();
 		String hostName = getHostName();
@@ -130,47 +145,45 @@ public abstract class AuthenticatingConnectorService extends AbstractConnectorSe
 		PasswordPersistenceManager.getInstance().remove(systemType, hostName, userId);
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.AbstractConnectorService#postDisconnect()
+	 */
 	protected final void postDisconnect() {
 		clearPassword(false, true);
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#isSuppressed()
+	 */
 	public final boolean isSuppressed() {
 		return credentialsProvider.isSuppressed();
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setSuppressed(boolean)
+	 */
 	public final void setSuppressed(boolean suppressed) {
 		credentialsProvider.setSuppressed(suppressed);
 	}
 
+	/**
+	 * Acquires the credentials by delegating the request to the 
+	 * credentials provider.
+	 * @param reacquire if true will cause the credentials to be reobtained if necessary.
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#acquireCredentials(boolean)
+	 */
 	public final void acquireCredentials(boolean reacquire) throws InterruptedException {
 		credentialsProvider.acquireCredentials(reacquire);
 	}
 
-	/**
+	/* (non-Javadoc)
-	 * <i>Useful utility method. Fully implemented, do not override.</i><br>
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#clearCredentials()
-	 * Clear internal userId. 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 clears the password.
 	 */
 	public final void clearCredentials() {
 		credentialsProvider.clearCredentials();
 		setDirty(true);
 	}
 
-	/**
-	 * <i>Useful utility method. Fully implemented, no need to override.</i><br>
-	 * @return the password information for the primary subsystem of this
-	 * connector service. Assumes it has been set by the subsystem at the 
-	 * time the subsystem acquires the connector service.
-	 */
-	protected final SystemSignonInformation getSignonInformation() {
-		SystemSignonInformation result = null;
-		ICredentials credentials = credentialsProvider.getCredentials();
-		result = (SystemSignonInformation) credentials;
-		return result;
-	}
-
 	private void updatePasswordForOtherSystemsInConnection(String uid, String password, boolean persist) {
 		IHost connection = getPrimarySubSystem().getHost();
 		ISystemRegistry registry = RSECorePlugin.getDefault().getSystemRegistry();
@@ -239,9 +252,10 @@ public abstract class AuthenticatingConnectorService extends AbstractConnectorSe
 	/**
 	 * Returns true if this connector service can share it's credentials
 	 * with other connector services in this host.
-	 * This default implementation will always return true.
+	 * This implementation will always return true.
 	 * Override if necessary.
 	 * @return true
+	 * @see IConnectorService#sharesCredentials()
 	 */
 	public boolean sharesCredentials() {
 	    return true;
@@ -250,18 +264,29 @@ public abstract class AuthenticatingConnectorService extends AbstractConnectorSe
 	/**
 	 * Returns true if this connector service can inherit the credentials of
 	 * other connector services in this host.
-	 * This default implementation always returns true. 
+	 * This implementation always returns true. 
 	 * Override if necessary.
 	 * @return true
+	 * @see IConnectorService#inheritsCredentials()
 	 */
 	public boolean inheritsCredentials() {
 	    return true;
 	}
 
+	/**
+	 * Sets the credentials provider used by this connector service.
+	 * This should be invoked once immediately during the construction of the 
+	 * connector service.
+	 * @param credentialsProvider the credentials provider to be used
+	 * by this connector service.
+	 */
 	protected final void setCredentialsProvider(ICredentialsProvider credentialsProvider) {
 		this.credentialsProvider = credentialsProvider;
 	}
 	
+	/**
+	 * @return the credentials provider that is being used by this connector service.
+	 */
 	protected final ICredentialsProvider getCredentialsProvider() {
 		return credentialsProvider;
 	}

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/BasicConnectorService.java

@@ -18,107 +18,202 @@ package org.eclipse.rse.core.subsystems;
 import org.eclipse.rse.core.model.IHost;
 
 /**
- * This is a base class to make it easier to create connector service classes.
+ * A basic connector service is one that does not require any type of 
- * <p>
+ * authentication to connect to its target system.
- * An {@link org.eclipse.rse.core.subsystems.IConnectorService} object
+ * Since this is the case, many of the methods of
- * is returned from a subsystem object via getConnectorService(), and
+ * {@link IConnectorService} are implemented only in skeletal form.
- * it is used to represent the live connection to a particular subsystem.
- * <p>
- * You must override/implement
- * <ul>
- * <li>isConnected
- * <li>internalConnect
- * <li>internalDisconnect
- * </ul>
- * You should override:
- * <ul>
- * <li>reset 
- * <li>getVersionReleaseModification
- * <li>getHomeDirectory
- * <li>getTempDirectory
- * </ul>
- * You can override:
- * <ul>
- * <li>supportsUserId
- * <li>requiresUserId
- * <li>supportsPassword
- * <li>requiresPassword
- * </ul>
- * 
- * @see org.eclipse.rse.core.subsystems.AbstractConnectorServiceManager
  */
 public abstract class BasicConnectorService extends AbstractConnectorService {
 	
+	/**
+	 * Constructs a basic connector service.
+	 * @param name The name of the connector service
+	 * @param description The description of the connector service
+	 * @param host the host associated with this connector service
+	 * @param port the port used by this connector service, if IP based
+	 */
 	public BasicConnectorService(String name, String description, IHost host, int port) {
 		super(name, description, host, port);
 	}
 	
+	/**
+	 * Indicates if this connector service understands passwords.
+	 * This implementation always returns false.
+	 * Override if necessary.
+	 * @return false
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#supportsPassword()
+	 */
 	public boolean supportsPassword() {
 		return false;
 	}
 	
+	/**
+	 * Indicates if this connector service requires passwords.
+	 * This implementation always returns false.
+	 * Override if necessary.
+	 * @return false
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#requiresPassword()
+	 */
 	public boolean requiresPassword() {
 		return false;
 	}
 	
+	/**
+	 * Indicates if this connector service understands user ids.
+	 * This implementation always returns false.
+	 * Override if necessary.
+	 * @return false
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#supportsUserId()
+	 */
 	public boolean supportsUserId() {
 		return false;
 	}
 	
+	/**
+	 * Indicates if this connector service requires a user id.
+	 * This implementation always returns false.
+	 * Override if necessary.
+	 * @return false
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#requiresUserId()
+	 */
 	public boolean requiresUserId() {
 		return false;
 	}
 	
+	/**
+	 * Acquires credentials.
+	 * This implmentation does nothing.
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#acquireCredentials(boolean)
+	 */
 	public void acquireCredentials(boolean refresh) throws InterruptedException {
 	}
 	
+	/**
+	 * Clears credentials.
+	 * This implementation does nothing.
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#clearCredentials()
+	 */
 	public void clearCredentials() {
 	}
 	
+	/**
+	 * Clears a password.
+	 * This implementation does nothing.
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#clearPassword(boolean, boolean)
+	 */
 	public void clearPassword(boolean persist, boolean propagate) {
 	}
 	
+	/**
+	 * Gets the user id.
+	 * This implementation returns null.
+	 * @return null
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#getUserId()
+	 */
 	public String getUserId() {
 		return null;
 	}
 	
+	/**
+	 * Indicates the presence of a password.
+	 * This implementation returns false.
+	 * @param onDisk true if checking for a persistent form of a password
+	 * @return false
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#hasPassword(boolean)
+	 */
 	public boolean hasPassword(boolean onDisk) {
 		return false;
 	}
 	
+	/**
+	 * Indicates if this connector service can inherit its credentials from others.
+	 * This implementation returns false.
+	 * @return false
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#inheritsCredentials()
+	 */
 	public boolean inheritsCredentials() {
 		return false;
 	}
 	
+	/**
+	 * Indicates if this connector service is currently being suppressed.
+	 * This implementation returns false.
+	 * @return false
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#isSuppressed()
+	 */
 	public boolean isSuppressed() {
 		return false;
 	}
 	
-	protected void postDisconnect() {
+	/**
-	}
+	 * Removes the persistent form of a password.
-	
+	 * This implementation does nothing.
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#removePassword()
+	 */
 	public void removePassword() {
 	}
 	
+	/**
+	 * Removes the persistent form of the default user id.
+	 * This implementation does nothing.
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#removeUserId()
+	 */
 	public void removeUserId() {
 	}
 	
+	/**
+	 * Saves the remembered password persistently.
+	 * This implementation does nothing.
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#savePassword()
+	 */
 	public void savePassword() {
 	}
 	
+	/**
+	 * Saves the remembered user id persistently.
+	 * This implementation does nothing.
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#saveUserId()
+	 */
 	public void saveUserId() {
 	}
 	
+	/**
+	 * Sets the password for a particular user id and optionally persists it.
+	 * This implemenation does nothing.
+	 * @param matchingUserId the user id to set the password for
+	 * @param password the password to set.
+	 * @param persist true if this is to be persisted.
+	 * @param propagate true if this password should be propagated to other
+	 * connector services.
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setPassword(java.lang.String, java.lang.String, boolean, boolean)
+	 */
 	public void setPassword(String matchingUserId, String password, boolean persist, boolean propagate) {
 	}
 	
+	/**
+	 * Indicates if credentials are shared with other connector services.
+	 * This implementation returns false.
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#sharesCredentials()
+	 */
 	public boolean sharesCredentials() {
 		return false;
 	}
 
+	/**
+	 * Sets the suppressed state of this connector service.
+	 * This implementation does nothing.
+	 * @param suppress true if this connector service should be suppressed.
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setSuppressed(boolean)
+	 */
 	public void setSuppressed(boolean suppress) {
 	}
 
+	/**
+	 * Sets the user id for this connector service.
+	 * This implementation does nothing.
+	 * @param userId the user id to set for this service.
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#setUserId(java.lang.String)
+	 */
 	public void setUserId(String userId) {
 	}
 	

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/IConnectorService.java

@@ -162,23 +162,20 @@ public interface IConnectorService extends IRSEModelObject {
 
 	/**
 	 * Reports 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.
 	 * @return true if and only if the connector service can use a user id.
 	 */
 	public boolean supportsUserId();
 
 	/**
-	 * Determines if this connector service understand the concept of a
+	 * Determines if this connector service understand the concept of a password.
-	 * password.
-	 * The default implementation of this interface should return true.
 	 * @return true if the connector service can use a password, 
 	 * false if a password is irrelevant.
 	 */
 	public boolean supportsPassword();
 
 	/**
-	 * @return the userId that will be used by this connector when
+	 * @return the user id that will be used by this connector when
 	 * establishing its connection.
 	 */
 	public String getUserId();
@@ -190,8 +187,16 @@ public interface IConnectorService extends IRSEModelObject {
 	 */
 	public void setUserId(String userId);
 
+	/**
+	 * Causes the user id known to the connector service, if any, to be
+	 * persisted.
+	 */
 	public void saveUserId();
 
+	/**
+	 * Causes the persisted (default) user id known to this 
+	 * connector service, if any, to be forgotten.
+	 */
 	public void removeUserId();
 
 	/**
@@ -205,8 +210,16 @@ public interface IConnectorService extends IRSEModelObject {
 	 */
 	public void setPassword(String matchingUserId, String password, boolean persist, boolean propagate);
 	
+	/**
+	 * Causes the password known to this connector service, if any, to be 
+	 * persisted.
+	 */
 	public void savePassword();
 	
+	/**
+	 * Causes the persisted password known to this connector service, if any, to 
+	 * be forgotten.
+	 */
 	public void removePassword();
 	
 	/**
@@ -220,14 +233,14 @@ public interface IConnectorService extends IRSEModelObject {
 	public void clearPassword(boolean persist, boolean propagate);
 
 	/**
-	 * @param onDisk retrieve the persistent form of the password.
+	 * @param persistent also check for the persistent form of the password.
-	 * @return true if password is currently known to this service.
+	 * @return true if a password is currently known to this connector service.
 	 */
-	public boolean hasPassword(boolean onDisk);
+	public boolean hasPassword(boolean persistent);
 
 	/**
 	 * Returns true if this system can inherit the credentials of
-	 * from the connection (Host).
+	 * from the other connector services in this host.
 	 * @return true if it can inherit the credentials, false otherwise
 	 */
 	public boolean inheritsCredentials();
@@ -273,7 +286,7 @@ public interface IConnectorService extends IRSEModelObject {
 	 * <p>
 	 * The intent is to allow tool writers to prevent multiple 
 	 * attempts to acquire credentials during a set period of time.
-	 * <b>It is the callers responsibility to set this value 
+	 * <b>It is the responsibility of the caller to set this value 
 	 * back to false when the tool no longer needs to suppress
 	 * acquisition credentials.</b>
 	 * 
@@ -333,7 +346,8 @@ public interface IConnectorService extends IRSEModelObject {
 
 	/**
 	 * @return true if the connector service supports the concept of remote
-	 * server launch properties. This will always return false {@link #supportsRemoteServerLaunching()}
+	 * server launch properties.
+	 * This will always return false {@link #supportsRemoteServerLaunching()}
 	 * is false. 
 	 */
 	boolean supportsServerLaunchProperties();
@@ -345,13 +359,21 @@ public interface IConnectorService extends IRSEModelObject {
 	boolean supportsRemoteServerLaunching();
 	
 	/**
-	 * @return the server launcher. Will be null unless {@link #supportsRemoteServerLaunching()} 
+	 * @return the server launcher. Will be null unless
-	 * is true.
+	 * {@link #supportsRemoteServerLaunching()} is true.
 	 */
 	IServerLauncher getRemoteServerLauncher();
 
+	/**
+	 * @return true if this connector service supports passwords and 
+	 * requires a password to connect to its target system.
+	 */
 	boolean requiresPassword();
 
+	/**
+	 * @return true if this connector service understands the concept of a 
+	 * user id and requires one to connect to its target system.
+	 */
 	boolean requiresUserId();
 
 }

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/IDelegatingConnectorService.java

@@ -13,7 +13,15 @@
  ********************************************************************************/
 package org.eclipse.rse.core.subsystems;
 
+/**
+ * A delegating connector service forwards all requests for infomation
+ * to another connector service. 
+ */
 public interface IDelegatingConnectorService extends IConnectorService 
 {
+	/**
+	 * @return the connector service that this connector service will
+	 * forward requests to.
+	 */
 	public IConnectorService getRealConnectorService();
 }

rse/plugins/org.eclipse.rse.subsystems.processes.shell.linux/src/org/eclipse/rse/internal/subsystems/processes/shell/linux/DelegatingShellProcessConnectorService.java

@@ -20,14 +20,25 @@ import org.eclipse.rse.core.subsystems.IConnectorService;
 import org.eclipse.rse.subsystems.processes.servicesubsystem.IProcessServiceSubSystem;
 import org.eclipse.rse.subsystems.shells.core.subsystems.servicesubsystem.IShellServiceSubSystem;
 
+/**
+ * This class delegates the connector service requests for the linux process 
+ * subsystem to the connector service of the shell subsystem.
+ */
 public class DelegatingShellProcessConnectorService extends AbstractDelegatingConnectorService 
 {
 	private IConnectorService _realService;
+
+	/**
+	 * @param host the linux host that is the target for this connector service.
+	 */
 	public DelegatingShellProcessConnectorService(IHost host) 
 	{
 		super(host);
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.AbstractDelegatingConnectorService#getRealConnectorService()
+	 */
 	public IConnectorService getRealConnectorService()
 	{
 		if (_realService != null)

rse/plugins/org.eclipse.rse.ui/subsystems/org/eclipse/rse/ui/subsystems/StandardConnectorService.java

@@ -16,59 +16,85 @@
 package org.eclipse.rse.ui.subsystems;
 
 import org.eclipse.rse.core.model.IHost;
+import org.eclipse.rse.core.model.SystemSignonInformation;
 import org.eclipse.rse.core.subsystems.AuthenticatingConnectorService;
+import org.eclipse.rse.core.subsystems.ICredentials;
+
 
 /**
- * This is a base class to make it easier to create connector service classes.
+ * A standard connector service is an authenticating connector service
- * <p>
+ * (see {@link AuthenticatingConnectorService}) that understand and prompts for
- * An {@link org.eclipse.rse.core.subsystems.IConnectorService} object
+ * user ids and passwords. It uses a standard credentials provider 
- * is returned from a subsystem object via getConnectorService(), and
+ * (see {@link StandardCredentialsProvider}) to do so.
- * it is used to represent the live connection to a particular subsystem.
- * <p>
- * You must override/implement
- * <ul>
- * <li>isConnected
- * <li>internalConnect
- * <li>internalDisconnect
- * </ul>
- * You should override:
- * <ul>
- * <li>reset 
- * <li>getVersionReleaseModification
- * <li>getHomeDirectory
- * <li>getTempDirectory
- * </ul>
- * You can override:
- * <ul>
- * <li>supportsUserId
- * <li>requiresUserId
- * <li>supportsPassword
- * <li>requiresPassword
- * </ul>
- * 
- * @see org.eclipse.rse.core.subsystems.AbstractConnectorServiceManager
  */
 public abstract class StandardConnectorService extends AuthenticatingConnectorService {
 	
+	/**
+	 * Construct a standard connector service. This also constructs
+	 * and uses a standard credentials provider.
+	 * @param name the name of the connector service
+	 * @param description the description of the connector service
+	 * @param host the host associated with this connector service
+	 * @param port the port used by this connector service, if IP based
+	 */
 	public StandardConnectorService(String name, String description, IHost host, int port) {
 		super(name, description, host, port);
 		setCredentialsProvider(new StandardCredentialsProvider(this));
 	}
 	
+	/**
+	 * Indicates if this connector service understands passwords.
+	 * This implementation always returns true.
+	 * Override if necessary.
+	 * @return true
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#supportsPassword()
+	 */
 	public boolean supportsPassword() {
 		return true;
 	}
 	
+	/**
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#requiresPassword()
+	 * Indicates if this connector service requires a password.
+	 * This implementation always returns true.
+	 * Override if necessary.
+	 * @return true
+	 */
 	public boolean requiresPassword() {
 		return true;
 	}
 	
+	/**
+	 * Indicates if this connector service understands user ids.
+	 * This implementation always returns true.
+	 * Override if necessary.
+	 * @return true
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#supportsUserId()
+	 */
 	public boolean supportsUserId() {
 		return true;
 	}
 	
+	/**
+	 * @see org.eclipse.rse.core.subsystems.IConnectorService#requiresUserId()
+	 * Indicates if this connector service requires a user id.
+	 * This implementation always returns true.
+	 * Override if necessary.
+	 * @return true
+	 */
 	public boolean requiresUserId() {
 		return true;
 	}
+
+	/**
+	 * @return the SystemSignonInformation constructed from the
+	 * credentials provider.
+	 */
+	protected final SystemSignonInformation getSignonInformation() {
+		SystemSignonInformation result = null;
+		ICredentials credentials = credentialsProvider.getCredentials();
+		result = (SystemSignonInformation) credentials;
+		return result;
+	}
 	
 }