More documentation

4 files changed, 73 insertions, 57 deletions

diff --git a/src/main/java/com/c2kernel/entity/TraceableEntity.java b/src/main/java/com/c2kernel/entity/TraceableEntity.java
index 7d5df52..f0bf957 100644
--- a/src/main/java/com/c2kernel/entity/TraceableEntity.java
+++ b/src/main/java/com/c2kernel/entity/TraceableEntity.java
@@ -33,9 +33,11 @@ import com.c2kernel.lookup.ItemPath;
 import com.c2kernel.utils.Logger;

 

 /**************************************************************************

-*

-* @author $Author: abranson $ $Date: 2005/10/06 14:46:22 $

-* @version $Revision: 1.108 $

+*  TraceableEntity is the implementation of the CORBA Item, although it 

+*  delegates all non-CORBA functions to ItemImplementation.

+*  

+*  Traditional Pinky/Brain ASCII art:

+*  

 * <pre>

 *                                ,.   '\'\    ,---.

 *                            .  | \\  l\\l_ //    |

@@ -66,9 +68,6 @@ public class TraceableEntity extends ItemPOA
     private final org.omg.PortableServer.POA  mPoa;

     private final ItemImplementation	      mItemImpl;

 

-   /**************************************************************************

-    * Constructor used by the Locator only

-    **************************************************************************/

     public TraceableEntity( ItemPath                   key,

                             org.omg.PortableServer.POA poa )

     {

@@ -78,9 +77,6 @@ public class TraceableEntity extends ItemPOA
     }

 

 

-   /**************************************************************************

-    *

-    **************************************************************************/

     @Override

 	public org.omg.PortableServer.POA _default_POA()

     {

@@ -91,18 +87,12 @@ public class TraceableEntity extends ItemPOA
     }

 

 

-   /**************************************************************************

-    *

-    **************************************************************************/

     @Override

 	public SystemKey getSystemKey()

     {

         return mItemImpl.getSystemKey();

     }

 

-   /**************************************************************************

-    *

-    **************************************************************************/

     @Override

 	public void initialise( SystemKey agentId,

                             String  propString,

@@ -118,11 +108,6 @@ public class TraceableEntity extends ItemPOA
         }

     }

 

-    /**

-     * @throws InvalidCollectionModification 

-     *

-     **************************************************************************/

-	//requestdata is xmlstring

     @Override

 	public String requestAction( SystemKey agentId,

                                String stepPath,

@@ -141,9 +126,6 @@ public class TraceableEntity extends ItemPOA
         }

     }

 

-   /**************************************************************************

-    *

-    **************************************************************************/

     @Override

 	public String queryLifeCycle( SystemKey agentId,

                                   boolean     filter

@@ -157,17 +139,6 @@ public class TraceableEntity extends ItemPOA
         }

     }

 

-   /**************************************************************************

-    * The description for operation getData.

-    *

-    * @param path - the path to the object required

-    * 		  the suffix 'all' retrieves a listing of all keys on that level

-    *

-    * @return The result string in xml format

-	*		   except 'all' which returns a comma sep list

-    *

-    * @exception ObjectNotFoundException

-    * ************************************************************************/

     @Override

 	public String queryData(String path)

         throws AccessRightsException,

diff --git a/src/main/java/com/c2kernel/entity/agent/ActiveEntity.java b/src/main/java/com/c2kernel/entity/agent/ActiveEntity.java
index feb8880..e497c07 100644
--- a/src/main/java/com/c2kernel/entity/agent/ActiveEntity.java
+++ b/src/main/java/com/c2kernel/entity/agent/ActiveEntity.java
@@ -34,10 +34,10 @@ import com.c2kernel.lookup.AgentPath;
 import com.c2kernel.utils.Logger;

 

 /**************************************************************************

- * ActiveEntity

- *

- * @author $Author: abranson $ $Date: 2005/04/26 06:48:12 $

- * @version $Revision: 1.39 $

+ * ActiveEntity - the CORBA object representing the Agent. All functionality

+ * is delegated to the AgentImplementation, which extends ItemImplementation,

+ * as this cannot extend its equivalent TraceableEntity

+ * 

  **************************************************************************/

 public class ActiveEntity extends AgentPOA

 {

diff --git a/src/main/java/com/c2kernel/entity/agent/AgentImplementation.java b/src/main/java/com/c2kernel/entity/agent/AgentImplementation.java
index c9eee73..e59c731 100644
--- a/src/main/java/com/c2kernel/entity/agent/AgentImplementation.java
+++ b/src/main/java/com/c2kernel/entity/agent/AgentImplementation.java
@@ -34,6 +34,16 @@ import com.c2kernel.lookup.RolePath;
 import com.c2kernel.process.Gateway;

 import com.c2kernel.utils.Logger;

 

+/**

+ * Implementation of Agent, though called from the CORBA implementation ActiveEntity.

+ * 

+ * <p>The Agent is an extension of the Item that can execute Jobs, and in doing so

+ * change the state of Item workflows, submit data to them in the form of Outcomes

+ * and run any scripts associated with those activities. In this server object,

+ * none of this specific Agent work is performed - it all must be done using the

+ * client API. The server implementation only manages the Agent's data: its roles

+ * and persistent Jobs.

+ */

 public class AgentImplementation extends ItemImplementation implements

 		AgentOperations {

 

@@ -45,10 +55,12 @@ public class AgentImplementation extends ItemImplementation implements
 		mAgentPath = path;

 	}

 

-	   /**

-     * Called by an activity when it reckons we need to update our joblist for it

-     */

 

+	/**

+	 * Updates an Agent's list of Jobs relating to a particular activity. Only

+	 * Activities that are assigned to a Role that is flagged to push Jobs do this.

+	 * 

+	 */

     @Override

 	public synchronized void refreshJobList(SystemKey sysKey, String stepPath, String newJobs) {

         try {

@@ -76,6 +88,14 @@ public class AgentImplementation extends ItemImplementation implements
 

     }

 

+    /** Adds the given Role to this Agent. Called from the SetAgentRoles

+     * predefined step.

+     * 

+     * @param roleName - the new Role to add

+     * @throws CannotManageException When the process has no lookup manager

+     * @throws ObjectNotFoundException 

+     * 

+     */

     @Override

 	public void addRole(String roleName) throws CannotManageException, ObjectNotFoundException {

         RolePath newRole = Gateway.getLookup().getRolePath(roleName);

@@ -86,6 +106,12 @@ public class AgentImplementation extends ItemImplementation implements
         }

     }

 

+    /**

+     * Removes the given Role from this Agent. Called by the SetAgentRoles 

+     * predefined step.

+     * 

+     * @param roleName

+     */

     @Override

 	public void removeRole(String roleName) throws CannotManageException, ObjectNotFoundException {

         RolePath rolePath = Gateway.getLookup().getRolePath(roleName);

@@ -96,6 +122,13 @@ public class AgentImplementation extends ItemImplementation implements
         }

     }

 

+    /**

+     * Agents have their own predefined step containers. They contain the standard

+     * predefined steps, plus special Agent ones related to Agent management and 

+     * instantiation.

+     * 

+     * @see com.c2kernel.lifecycle.instance.predefined.agent.AgentPredefinedStepContainer

+     */

 	@Override

 	protected PredefinedStepContainer getNewPredefStepContainer() {

 		return new AgentPredefinedStepContainer();

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;