[javadoc] for ICrendentialsProvider, AbstractCredentialsProvider, and StandardCredentialsProvider

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

@@ -22,34 +22,61 @@ public abstract class AbstractCredentialsProvider implements ICredentialsProvide
 	private IConnectorService connectorService = null;
 	private boolean suppressed = false;
 	
+	/**
+	 * Create a credentials provider for a particular connector service.
+	 * Subclasses should implement their own constuctors but invoke this constructor
+	 * in them.
+	 * @param connectorService the associatated connector service.
+	 */
 	public AbstractCredentialsProvider(IConnectorService connectorService) {
 		this.connectorService = connectorService;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.ICredentialsProvider#getConnectorService()
+	 */
 	public final IConnectorService getConnectorService() {
 		return connectorService;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.ICredentialsProvider#isSuppressed()
+	 */
 	public final boolean isSuppressed() {
 		return suppressed;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.ICredentialsProvider#setSuppressed(boolean)
+	 */
 	public final void setSuppressed(boolean suppressed) {
 		this.suppressed = suppressed;
 	}
 	
+	/**
+	 * @return true if the associated connector service supports user ids.
+	 */
 	protected final boolean supportsUserId() {
 		return connectorService.supportsUserId();
 	}
 	
+	/**
+	 * @return true if the associated connector service requires a user id.
+	 */
 	protected final boolean requiresUserId() {
 		return connectorService.requiresUserId();
 	}
 	
+	/**
+	 * @return true if the associated connector service supports a password.
+	 */
 	protected final boolean supportsPassword() {
 		return connectorService.supportsPassword();
 	}
 	
+	/**
+	 * @return true if the associated connector service requires a password.
+	 */
 	protected final boolean requiresPassword() {
 		return connectorService.requiresPassword();
 	}

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

@@ -11,28 +11,125 @@ package org.eclipse.rse.core.subsystems;
 
 import org.eclipse.rse.services.clientserver.messages.SystemMessage;
 
+/**
+ * A credentials provider provides credentials to a connector service.
+ * Every authenticating connector service has its own credentials provider, 
+ * usually created when that connector service is created.
+ * <p>
+ * Credentials will usually consist of a user id and password
+ * but may be something else in which case implementers are free 
+ * change the user id and password methods to something that makes
+ * sense for their case.
+ * <p>
+ * A provider may be in a suppressed state, in which case it will
+ * prohibit the acquisition of credentials.
+ * @see ICredentials
+ * @see IConnectorService
+ * @see AuthenticatingConnectorService
+ */
 public interface ICredentialsProvider {
 	
+	/**
+	 * Causes the provider to create a set of credentials for use by a 
+	 * connector service in order to connect to a target host system.
+	 * This may be done by presenting a dialog or by retrieving remembered
+	 * values.
+	 * @param reacquire true if the provider should refresh any remembered
+	 * credentials. Typically used to force the showing of a dialog containing
+	 * remembered credentials.
+	 * @throws InterruptedException if the acquisition of credentials is 
+	 * canceled by the user, if the provider is in suppressed state,
+	 * or interrupted by some other means.
+	 */
 	void acquireCredentials(boolean reacquire) throws InterruptedException;
 	
+	/**
+	 * The connector service using this provider may find the credentials provided
+	 * are incorrector or expired. This method asks the provider to repair those
+	 * credentials. This would typically be used to present a dialog asking for the reentry of 
+	 * an expired password.
+	 * @param message the message indicating the nature of the damage that must
+	 * be repaired. For example, indicating expiration of a password.
+	 * @throws InterruptedException if the repair is canceled for some reason.
+	 */
 	void repairCredentials(SystemMessage message)throws InterruptedException;
 
+	/**
+	 * Clears the credentials known by this credentials provider. This will 
+	 * cause a reacquistion of all compoenents of the credentials at the next
+	 * acquire. If credentials consist of a user id and password then both of those
+	 * are cleared.
+	 * Does not clear any persistently remembered values.
+	 */
 	void clearCredentials();
 	
+	/**
+	 * Retrieves the credentials known to this credentials provider. Does not
+	 * cause the credentials to be acquired. May be used after {@link #acquireCredentials(boolean)}
+	 * to retrieve credentials.
+	 * @return the credentials that have previously been acquired or repaired.
+	 * May be null if no credentials have yet been acquired.
+	 */
 	ICredentials getCredentials();
 	
+	/**
+	 * If the credentials include a password or equivalent then clears only that
+	 * that portion of the credentials. If the credentials do not include a password
+	 * then the implementation may somehow invalidate the credentials so that 
+	 * they will be reacquired at the next acquisition.
+	 */
 	void clearPassword();
 
+	/**
+	 * If the credentials include a password or equivalent then set that password
+	 * to the new value.
+	 * If the credentials do not include a password then
+	 * the implementation may ignore this.
+	 * @param password the new value of the password in the credentials held by this provider
+	 */
 	void setPassword(String password);
 
+	/**
+	 * If the credentials include a user id then set that user id to the new value.
+	 * If the credentials do not include a user id then this is implementation 
+	 * defined.
+	 * @param userId the user id to place into the credentials held by this provider
+	 */
 	void setUserId(String userId);
 
+	/**
+	 * If the credentials include a user id then retrieve that user id.
+	 * If the credentials do not currently contain a user id then a default user id
+	 * related to the connector service may be obtained.
+	 * If the credentials do not support a user id then this should return null.
+	 * @return the userid of the credentials held by this provider
+	 */
 	String getUserId();
 	
+	/**
+	 * Retrieves the suppression state of the provider.
+	 * Acquisition may be suppressed for a period of time after a previous attempt.
+	 * This is to provide client control of the acquisition policy.
+	 * If true then {@link #acquireCredentials(boolean)} will immediately cancel when invoked.
+	 * @return true if the provider is suppressed.
+	 */
 	boolean isSuppressed();
 	
+	/**
+	 * Sets the suppressed state of the provider.
+	 * Acquisition may be suppressed for a period of time after a previous attempt.
+	 * This is to provide client control of the acquisition policy.
+	 * If true then {@link #acquireCredentials(boolean)} will immediately cancel when invoked.
+	 * @param suppressed true if the provider is to be suppressed.
+	 */
 	void setSuppressed(boolean suppressed);
 	
+	/**
+	 * Retrieves the connector service associated with this provider. Each provider
+	 * has its own connector service. All authenticating connector services have their 
+	 * own provider.
+	 * @return the connector service associated with this provider
+	 */
 	IConnectorService getConnectorService();
 	
 }

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

@@ -15,7 +15,6 @@ import org.eclipse.rse.core.model.SystemSignonInformation;
 import org.eclipse.rse.core.subsystems.AbstractCredentialsProvider;
 import org.eclipse.rse.core.subsystems.IConnectorService;
 import org.eclipse.rse.core.subsystems.ICredentials;
-import org.eclipse.rse.core.subsystems.ICredentialsProvider;
 import org.eclipse.rse.core.subsystems.ISubSystem;
 import org.eclipse.rse.core.subsystems.ISubSystemConfiguration;
 import org.eclipse.rse.core.subsystems.util.ISubSystemConfigurationAdapter;
@@ -35,8 +34,8 @@ import org.eclipse.swt.widgets.Shell;
 import org.eclipse.ui.PlatformUI;
 
 /**
- * The {@link StandardCredentialsProvider} is an implementation of
+ * The {@link StandardCredentialsProvider} is an extension of
- * {@link ICredentialsProvider} that provides for the prompting of a userid
+ * {@link AbstractCredentialsProvider} that provides for the prompting of a userid
  * and password.
  * <p>
  * It uses a {@link PasswordPersistenceManager} to store the passwords in the
@@ -50,14 +49,22 @@ import org.eclipse.ui.PlatformUI;
  * specific prompting.
  */
 public class StandardCredentialsProvider extends AbstractCredentialsProvider {
-	
+	/**
+	 * A runnable that will actually perform the prompting.
+	 */
 	private class PromptForCredentials implements Runnable {
 		private boolean canceled = false;
 
+		/**
+		 * @return true if prompting was canceled.
+		 */
 		public boolean isCanceled() {
 			return canceled;
 		}
 
+		/* (non-Javadoc)
+		 * @see java.lang.Runnable#run()
+		 */
 		public void run() {
 			ISystemPasswordPromptDialog dialog = getPasswordPromptDialog(getShell());
 			dialog.setSystemInput(getConnectorService());
@@ -85,6 +92,11 @@ public class StandardCredentialsProvider extends AbstractCredentialsProvider {
 			}
 		}
 	}
+
+	/**
+	 * A runnable that will prompt for a new password. Typically used when 
+	 * a password has expired.
+	 */
 	private class PromptForNewPassword implements Runnable {
 		private SystemMessage message;
 		private boolean canceled = false;
@@ -107,32 +119,41 @@ public class StandardCredentialsProvider extends AbstractCredentialsProvider {
 				savePassword = dlg.getIsSavePassword();
 			}
 		}
-	
 	}
+
 	private String userId = null;
 	private String password = null;
 	private boolean savePassword = false;
 	private boolean saveUserId = false;
 
+	/**
+	 * Creates a standard credentials provider for a connector service. 
+	 * @param connectorService the connector service associated with this 
+	 * provider.
+	 * @see IConnectorService
+	 */
 	public StandardCredentialsProvider(IConnectorService connectorService) {
 		super(connectorService);
 	}
 
 	/**
 	 * <i>Do not override.</i>
-	 * Sets the signon information for this connector service.
+	 * Acquires the credentials (userid and password) for this connector service.
 	 * The search order for the password is as follows:</p>
 	 * <ol>
-	 * <li>First check if the password is already known by this connector service and that it is still valid.
+	 * <li>First check if the password is already known by this
-	 * <li>If password not known then look in the password store and verify that it is still valid.
+	 * connector service and that it is still valid.
-	 * <li>If a valid password is not found then prompt the user.
+	 * <li>If password not known then look in the password
+	 * store and verify that it is still valid.
+	 * <li>If a valid password is not found or is to be reacquired
+	 * then prompt the user
 	 * </ol>
-	 * Must be run in the UI thread. 
+	 * @param reacquire if true then present the prompt even
-	 * Can be null if the password is known to exist in either this class or in the password store.
+	 * if the password was found and is valid.
-	 * @param reacquire if true then present the prompt even if the password was found and is valid.
+	 * @throws InterruptedException if user is prompted and user
-	 * @throws InterruptedException if user is prompted and user cancels that prompt or if isSuppressSignonPrompt is true.
+	 * cancels that prompt or if {@link #isSuppressed()} is true.
 	 */
-	public void acquireCredentials(boolean reacquire) throws InterruptedException {
+	public final void acquireCredentials(boolean reacquire) throws InterruptedException {
 		if (isSuppressed()) {
 			throw new InterruptedException();
 		}
@@ -189,21 +210,25 @@ public class StandardCredentialsProvider extends AbstractCredentialsProvider {
 		}
 	}
 
-	public void clearCredentials() {
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.ICredentialsProvider#clearCredentials()
+	 */
+	public final void clearCredentials() {
 		password = null;
 		userId = null;
 	}
 
-	/**
+	/* (non-Javadoc)
-	 * <i>Useful utility method. Fully implemented, do not override.</i><br>
+	 * @see org.eclipse.rse.core.subsystems.ICredentialsProvider#clearPassword()
-	 * Clear internal password cache. Called when user uses the property dialog to 
-	 * change his userId.  
 	 */
 	final public void clearPassword() {
 		password = null;
 	}
 
-	public ICredentials getCredentials() {
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.ICredentialsProvider#getCredentials()
+	 */
+	public final ICredentials getCredentials() {
 		IHost host = getConnectorService().getHost();
 		String hostName = host.getHostName();
 		String systemType = host.getSystemType();
@@ -211,11 +236,8 @@ public class StandardCredentialsProvider extends AbstractCredentialsProvider {
 		return result;
 	}
 
-	/**
+	/* (non-Javadoc)
-	 * <i>Useful utility method. Fully implemented, do not override.</i><br>
+	 * @see org.eclipse.rse.core.subsystems.ICredentialsProvider#getUserId()
-	 * Returns the active userId if we are connected.
-	 * If not it returns the userId for the primary subsystem ignoring the 
-	 * cached userId.
 	 */
 	final public String getUserId() {
 		if (supportsUserId()) {
@@ -226,11 +248,17 @@ public class StandardCredentialsProvider extends AbstractCredentialsProvider {
 		return userId;
 	}
 
-	public void repairCredentials(SystemMessage prompt) throws InterruptedException {
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.ICredentialsProvider#repairCredentials(org.eclipse.rse.services.clientserver.messages.SystemMessage)
+	 */
+	public final void repairCredentials(SystemMessage prompt) throws InterruptedException {
 		promptForNewPassword(prompt);
 	}
 
-	public void setPassword(String password) {
+	/* (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.ICredentialsProvider#setPassword(java.lang.String)
+	 */
+	public final void setPassword(String password) {
 		this.password = password;
 	}
 
@@ -269,7 +297,7 @@ public class StandardCredentialsProvider extends AbstractCredentialsProvider {
 	/**
 	 * <i>A default implementation is supplied, but can be overridden if desired.</i><br>
 	 * Instantiates and returns the dialog to prompt for the userId and password.
-	 * @return An instance of a dialog class that implements the ISystemPasswordPromptDialog interface
+	 * @return An instance of a dialog class that implements {@link ISystemPasswordPromptDialog}
 	 */
 	protected ISystemPasswordPromptDialog getPasswordPromptDialog(Shell shell) {
 		ISystemPasswordPromptDialog dlg = new SystemPasswordPromptDialog(shell, requiresUserId(), requiresPassword());
@@ -278,30 +306,18 @@ public class StandardCredentialsProvider extends AbstractCredentialsProvider {
 
 	/**
 	 * <i>Optionally overridable, not implemented by default.</i><br>
-	 * Get the signon validator to use in the password dialog prompt.
+	 * Get the credentails validator to use to validate the credentials as entered
-	 * By default, returns null.
+	 * in the dialog. This should only do a local validation.
+	 * @return null indicating that no signon validator exists.
 	 */
 	protected ICredentialsValidator getSignonValidator() {
 		return null;
 	}
 
-	/**
-	 * <i>Useful utility method. Fully implemented, no need to override.</i><br>
-	 * Should passwords be folded to uppercase?
-	 * By default, returns: 
-	 *   <pre><code>getSubSystem().forceUserIdToUpperCase()</code></pre>
-	 */
 	private boolean forcePasswordToUpperCase() {
 		return getPrimarySubSystem().forceUserIdToUpperCase();
 	}
 
-	/**
-	 * <i>Useful utility method. Fully implemented, no need to override.</i><br>
-	 * Get the password input validator to use in the password dialog prompt.
-	 * <p>
-	 * By default, returns:</p>
-	 *   <pre><code>getSubSystem().getParentSubSystemConfiguration().getPasswordValidator()</code></pre>
-	 */
 	private ISystemValidator getPasswordValidator() {
 		ISubSystemConfiguration ssFactory = getPrimarySubSystem().getSubSystemConfiguration();
 		ISubSystemConfigurationAdapter adapter = (ISubSystemConfigurationAdapter) ssFactory.getAdapter(ISubSystemConfigurationAdapter.class);
@@ -317,22 +333,12 @@ public class StandardCredentialsProvider extends AbstractCredentialsProvider {
 		return shell;
 	}
 
-	/**
-	 * @return the userId from the primary subsystem.
-	 */
 	private String getSubSystemUserId() {
 		ISubSystem ss = getPrimarySubSystem();
 		String result = ss.getUserId();
 		return result;
 	}
 
-	/**
-	 * <i>Useful utility method. Fully implemented, no need to override.</i><br>
-	 * Get the userId input validator to use in the password dialog prompt.
-	 * <p>
-	 * By default, returns </p>
-	 *   <pre><code>getSubSystem().getParentSubSystemConfiguration().getUserIdValidator()</code></pre>
-	 */
 	private ISystemValidator getUserIdValidator() {
 		ISubSystemConfiguration ssFactory = getPrimarySubSystem().getSubSystemConfiguration();
 		ISubSystemConfigurationAdapter adapter = (ISubSystemConfigurationAdapter) ssFactory.getAdapter(ISubSystemConfigurationAdapter.class);
@@ -361,11 +367,6 @@ public class StandardCredentialsProvider extends AbstractCredentialsProvider {
 		}
 	}
 
-	/**
-	 * <i>Useful utility method. Fully implemented, no need to override.</i><br>
-	 * Sets the password information for this system's subsystem.
-	 * @param signonInfo the password information object
-	 */
 	private void setSignonInformation(SystemSignonInformation signonInfo) {
 		password = signonInfo.getPassword();
 		userId = signonInfo.getUserId();