From 2353f4fc4252f7067478d6a9d8993daeb5d66e6a Mon Sep 17 00:00:00 2001
From: Andrew Branson <andrew.branson@cern.ch>
Date: Fri, 6 Jun 2014 17:14:26 +0200
Subject: Partial javadoc and scope tightening of the new interfaces.

---
 .../com/c2kernel/process/auth/Authenticator.java   | 71 +++++++++++++++++++---
 .../java/com/c2kernel/process/auth/ProxyLogin.java | 15 ++++-
 2 files changed, 76 insertions(+), 10 deletions(-)

(limited to 'src/main/java/com/c2kernel/process/auth')

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();
 }
diff --git a/src/main/java/com/c2kernel/process/auth/ProxyLogin.java b/src/main/java/com/c2kernel/process/auth/ProxyLogin.java
index 94416cf..665158c 100644
--- a/src/main/java/com/c2kernel/process/auth/ProxyLogin.java
+++ b/src/main/java/com/c2kernel/process/auth/ProxyLogin.java
@@ -4,9 +4,18 @@ import java.util.Properties;
 
 import com.c2kernel.entity.proxy.AgentProxy;
 
+/**
+ * This interface is used by client processes to implement alternative login
+ * mechanisms aside from the standard username and password. Implementations may
+ * synchronize Agents with an external user library, such as Active Directory.
+ * Implementations are expected to set up the Gateway process and its
+ * authenticated components itself.
+ * 
+ */
 public interface ProxyLogin {
 
-		public void initialize(Properties props) throws Exception;
-		public AgentProxy authenticate(String resource) throws Exception;
-		
+	public void initialize(Properties props) throws Exception;
+
+	public AgentProxy authenticate(String resource) throws Exception;
+
 }
-- 
cgit v1.2.3