Partial javadoc and scope tightening of the new interfaces.

2 files changed, 76 insertions, 10 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();

 }

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;

+

 }