More documentation

2 files changed, 40 insertions, 7 deletions

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();