1 files changed, 64 insertions, 7 deletions
diff --git a/src/main/java/com/c2kernel/process/auth/Authenticator.java b/src/main/java/com/c2kernel/process/auth/Authenticator.java
index 40defc4..44745da 100644
--- a/src/main/java/com/c2kernel/process/auth/Authenticator.java
+++ b/src/main/java/com/c2kernel/process/auth/Authenticator.java
@@ -3,14 +3,71 @@ package com.c2kernel.process.auth;
 import com.c2kernel.common.InvalidDataException;
 import com.c2kernel.common.ObjectNotFoundException;
 
-
+/**
+ * This interface is used by the kernel to store an authenticated connection
+ * and/or token that will be used by kernel components. The CRISTAL property
+ * 'Authenticator' is used to specify the implementation used. It is
+ * instantiated by the connect() methods of the Gateway, and will be found in
+ * the AgentProxy returned by connect(). Lookup and ClusterStorage instances are
+ * initialized with this Authenticator, which is expected to maintain the same
+ * user's connection through the process lifetime, reconnecting if the
+ * connection is lost.
+ * 
+ * @since 3.0
+ * 
+ */
 public interface Authenticator {
-	
-	public boolean authenticate(String agentName, String password, String resource) throws InvalidDataException, ObjectNotFoundException;
-	
-	public boolean authenticate(String resource) throws InvalidDataException, ObjectNotFoundException;
-	
+
+	/**
+	 * Authenticates a CRISTAL agent. If this method returns true, then the
+	 * connect method will create and return an AgentProxy for the given
+	 * username using the Lookup and ProxyManager.
+	 * 
+	 * @param agentName
+	 *            The username of the Agent to be authenticated. This must be
+	 *            already present as an Agent in the CRISTAL directory.
+	 * @param password
+	 *            The Agent's password
+	 * @param resource
+	 *            The authentication resource/domain/realm of the agent.
+	 *            Included so that domains may include CRISTAL users from
+	 *            different realms. This parameter is passed into the connect()
+	 *            method if required. May be null.
+	 * @return a boolean indicating if the authentication was successful. If so,
+	 *         then the Gateway will generate an AgentProxy for the given user.
+	 * @throws ObjectNotFoundException
+	 *             When the Agent doesn't exist
+	 * @throws InvalidDataException
+	 *             When authentication fails for another reason
+	 */
+	public boolean authenticate(String agentName, String password,
+			String resource) throws InvalidDataException,
+			ObjectNotFoundException;
+
+	/**
+	 * Authenticates a superuser connection for the server. It must be able to
+	 * act on behalf of any other Agent, as the server needs to do this.
+	 * Credentials may be in the CRISTAL properties, or some other mechanism.
+	 * 
+	 * @param resource
+	 * @return
+	 * @throws InvalidDataException
+	 * @throws ObjectNotFoundException
+	 */
+	public boolean authenticate(String resource) throws InvalidDataException,
+			ObjectNotFoundException;
+
+	/**
+	 * Lookup and storage implementations that need to use user or superuser
+	 * authentication can retrieve it using this method. This will be highly
+	 * implementation specific.
+	 * 
+	 * @return the connection/token created during authentication
+	 */
 	public Object getAuthObject();
-	
+
+	/**
+	 * Close or expire the connection as the CRISTAL process shuts down.
+	 */
 	public void disconnect();
 }