More documentation

1 files changed, 28 insertions, 16 deletions

diff --git a/src/main/java/com/c2kernel/lookup/LookupManager.java b/src/main/java/com/c2kernel/lookup/LookupManager.java
index b05a4a4..c33bc35 100644
--- a/src/main/java/com/c2kernel/lookup/LookupManager.java
+++ b/src/main/java/com/c2kernel/lookup/LookupManager.java
@@ -27,13 +27,18 @@ import com.c2kernel.common.ObjectCannotBeUpdated;
 import com.c2kernel.common.ObjectNotFoundException;

 

 /**

- * @author abranson

+ * The LookupManager interface contains all of the directory modifying methods

+ * of the Lookup. This allows read-only Lookup implementations. Server processes

+ * will attempt to cast their Lookups into LookupManagers, and fail to start up

+ * if this is not possible.

  *

  */

 public interface LookupManager extends Lookup {

 	

 	/**

-	 * Called when a server starts up. The Lookup implementation should ensure that the initial structure of its directory is valid, and create it on first boot.

+	 * Called when a server starts up. The Lookup implementation should ensure 

+	 * that the initial structure of its directory is valid, and create it on 

+	 * first boot.

 	 * 

 	 * @throws ObjectNotFoundException When initialization data is not found

 	 */

@@ -45,13 +50,15 @@ public interface LookupManager extends Lookup {
 	 * Register a new a Path in the directory.

 	 * 

 	 * @param newPath The path to add

-	 * @throws ObjectCannotBeUpdated When there is an error writing to the directory

+	 * @throws ObjectCannotBeUpdated When there is an error writing to the 

+	 * directory

 	 * @throws ObjectAlreadyExistsException When the Path has already been registered

 	 */

 	public void add(Path newPath) throws ObjectCannotBeUpdated, ObjectAlreadyExistsException;

 

 	/**

-	 * Remove a Path from the directory

+	 * Remove a Path from the directory.

+	 * 

 	 * @param path The path to remove

 	 * @throws ObjectCannotBeUpdated When an error occurs writing to the directory

 	 */

@@ -60,12 +67,11 @@ public interface LookupManager extends Lookup {
 	// Role and agent management

 	

 	/**

-	 * Creates a new Role in this centre

+	 * Creates a new Role. Called by the server predefined step 'CreateNewRole'

 	 * 

-	 * @param role

-	 * @param hasJobList

+	 * @param role The new role path

 	 * @return

-	 * @throws ObjectAlreadyExistsException

+	 * @throws ObjectAlreadyExistsException 

 	 * @throws ObjectCannotBeUpdated

 	 */

 	public RolePath createRole(RolePath role) throws ObjectAlreadyExistsException, ObjectCannotBeUpdated;

@@ -73,7 +79,7 @@ public interface LookupManager extends Lookup {
 	/**

 	 * Adds the given Agent to the given Role, if they both exist.

 	 * 

-	 * @param agent - the 

+	 * @param agent 

 	 * @param rolePath

 	 * @throws ObjectCannotBeUpdated

 	 * @throws ObjectNotFoundException

@@ -81,7 +87,7 @@ public interface LookupManager extends Lookup {
 	public void addRole(AgentPath agent, RolePath rolePath) throws ObjectCannotBeUpdated, ObjectNotFoundException;

 

 	/**

-	 * Removes the given Agent from the given Role. Does not delete the Role.

+	 * Remove the given Agent from the given Role. Does not delete the Role.

 	 * 

 	 * @param agent

 	 * @param role

@@ -91,8 +97,10 @@ public interface LookupManager extends Lookup {
 	public void removeRole(AgentPath agent, RolePath role) throws ObjectCannotBeUpdated, ObjectNotFoundException;

 

 	/**

-	 * @param agent

-	 * @param newPassword

+	 * Set an Agent's password

+	 * 

+	 * @param agent The Agent

+	 * @param newPassword The Agent's new password

 	 * @throws ObjectNotFoundException

 	 * @throws ObjectCannotBeUpdated

 	 * @throws NoSuchAlgorithmException

@@ -100,10 +108,14 @@ public interface LookupManager extends Lookup {
 	public void setAgentPassword(AgentPath agent, String newPassword) throws ObjectNotFoundException, ObjectCannotBeUpdated, NoSuchAlgorithmException;

 	

 	/**

-	 * @param role

-	 * @param hasJobList

-	 * @throws ObjectNotFoundException

-	 * @throws ObjectCannotBeUpdated

+	 * Set the flag specifying whether Activities holding this Role should push

+	 * Jobs its Agents.

+	 * 

+	 * @param role The role to modify

+	 * @param hasJobList boolean flag

+	 * 

+	 * @throws ObjectNotFoundException When the Role doesn't exist

+	 * @throws ObjectCannotBeUpdated 

 	 */

 	public void setHasJobList(RolePath role, boolean hasJobList) throws ObjectNotFoundException, ObjectCannotBeUpdated;