From 900631ca79cf283eff42266ea6ebe8b9f4bd0cd1 Mon Sep 17 00:00:00 2001
From: Andrew Branson <andrew.branson@cern.ch>
Date: Mon, 30 Sep 2013 09:06:51 +0200
Subject: Javadoc on IDLs

---
 src/main/idl/CommonExceptions.idl                  |  19 +--
 src/main/idl/Entity.idl                            | 174 +++++++++++----------
 .../java/com/c2kernel/entity/TraceableEntity.java  |  39 +++--
 3 files changed, 127 insertions(+), 105 deletions(-)

(limited to 'src')

diff --git a/src/main/idl/CommonExceptions.idl b/src/main/idl/CommonExceptions.idl
index 9301ad0..fd1122a 100644
--- a/src/main/idl/CommonExceptions.idl
+++ b/src/main/idl/CommonExceptions.idl
@@ -14,7 +14,8 @@
 module common
 {
     /**************************************************************************
-    * Thrown by the different Factories
+    * Thrown when the directory couldn't be modified during Entity creation, or
+    * Role management
     **************************************************************************/
     exception CannotManageException
     {
@@ -24,8 +25,9 @@ module common
 
 
     /**************************************************************************
-    * The requested Transition in the State Diagram of the Step
-    * cannot be performed.
+    * The requested transition is not currently available, or does not exist.
+    * Most commonly occurs when the Activity is in a different state than the
+    * caller has assumed.
     **************************************************************************/
     exception InvalidTransitionException
     {
@@ -34,9 +36,7 @@ module common
 
 
     /**************************************************************************
-    * The action for the requested Transition has got invalid data
-    * Also used in other contexts if the provided data is not valid
-    * (eg. index out of bounds)
+    * Either the supplied data, or the relevant description, was invalid.
     **************************************************************************/
     exception InvalidDataException
     {
@@ -45,12 +45,7 @@ module common
 
 
     /**************************************************************************
-    * The Agent has no rigths to request the Transition.
-    *
-    *<p><pre> Two major reasons:
-    * 1. The role of the Agent and the Step specifictaion does not much.
-    * 2. The Step is already allocated to an Agent.
-    *</pre>
+    * The given agent is not permitted to perform the requested action.
     **************************************************************************/
     exception AccessRightsException
     {
diff --git a/src/main/idl/Entity.idl b/src/main/idl/Entity.idl
index aa607c7..f94bdf4 100644
--- a/src/main/idl/Entity.idl
+++ b/src/main/idl/Entity.idl
@@ -15,40 +15,40 @@
 
 module entity
 {
-    /**************************************************************************
-    * ManageableEntity is an <i>uniquely identifiable CORBA object</i>.
-    *
-    * - It is persistent or not. This is relevant when the timelife of it
-    *   is very short and/or there is no need for recovery from crash.
-    **************************************************************************/
+    /**
+    * ManageableEntity is the CORBA super-interface for Entities. It is uniquely 
+    * identifiable by its <i>system key</i>, and contains XML fragments arranged 
+    * in a tree structure. 
+    **/ 
+
     abstract interface ManageableEntity
     {
 
         /**
-        * <p>System generated unique key of the Entity. It is unique
-        * in the context defined by the domain expert which is to
-        * define the root NamingContext in the Naming Service
-        * (ie. return of orb.resolve_initial_references("NameService") ).
-        * <p>In principle it is equivalent with an OID of an object in a
-        * OODBMS or with an IOR defined on CORBA.
+        * System generated unique key of the Entity. It is unique in the domain tree of the local centre in which is is contained.
         **/
         unsigned long getSystemKey();
 
 
         /**
-        * The description for operation getData.
-        *
-        * @param xpath A not so dummy argument.
-        *             - LifeCycle
-        *             - Collection
-        *             - History
-        *             - Properties
-        *             - JobList
-        *             - Capabilities
-        *
-        * @return The result string in xml format.
-        *
-        * @exception ObjectNotFoundException 'what' was not found.
+        * Returns a chunk of XML which may be a serialized C2KLocalObject, or in the case of Outcomes is merely a fragment of XML.
+        * 
+        * @param path - All Entity data is arranged in a tree structure which uniquely identifies that object within the Entity it is contained, according to the following scheme:
+        * <ul><li><code>LifeCycle/workflow</code> <i>(Items only)</i>: The Workflow object for this Item, containing the graph of activities defining the Item's lifecycle, and the Predefined Step container for data modification</li>
+        * <li><code>Collection/{Name}</code> <i>(Items only)</i>: Collection objects defining links between Items</li>
+        * <li><code>Property/{Name}</code>: Name value pairs to idenfity this Entity, define its type, and hold any other oft-changing indicators that would be heavy to extract from Outcomes</li>
+		* <li><code>AuditTrail/{ID}</code> <i>(Items only)</i>: Events describing all activity state changes in this Item.</li>
+		* <li><code>Outcome/{Schema name}/{Schema version}/{Event ID}</code> <i>(Items only)</i>: XML fragments resulting from the execution of an Activity, validated against the XML Schema defined by that activity.</li>
+		* <li><code>ViewPoint/{Schema name}/{Name}</code> <i>(Items only)</i>: A named pointer to the latest version of an Outcome, defined by the Activity.</li>
+		* <li><code>Job/{ID}</code> <i>(Agents only)</i>: A persistent Job, reflecting a request for execution of an Activity to this Agent. Not all roles create persistent Jobs like this, only those specifically flagged to do so.</li> 
+		*  
+		* @see com.c2kernel.persistency.ClusterStorage#getPath
+		* 
+        * @return The XML string of the data. All fragments except Outcomes will deserialize into objects with the kernel CastorXMLUtility available in the Gateway. 
+        * 
+        * @exception ObjectNotFoundException when the path is not present in this Entity
+        * @exception AccessRightsException <i>Not currently implemented</i>
+        * @exception PersistencyException when the path could not be loaded because of a problem with the storage subsystem.
         **/
         string queryData( in string xpath )
             raises( common::AccessRightsException,
@@ -58,18 +58,47 @@ module entity
 
 
     /**************************************************************************
-    *
+    * Agent is a ManageableEntity that represents an Activity executor in the 
+    * system. It holds a job list, which are persistent requests for execution 
+    * from waiting activities assigned to a role that has such Job pushing enabled.
     **************************************************************************/
     interface Agent : ManageableEntity
     {
+    	/** Initialises a new Agent. Should not be done by client processes - they
+    	* should use an Agent factory such as a Server item.
+    	* @param agentProps - XML marshalled {@link com.c2kernel.Property.PropertyArrayList PropertyArrayList} containing the initial
+    	* Property objects of the Agent
+    	* @throws AccessRightsException not yet implemented, reserved for future access control
+    	* @throws InvalidDataException when the data supplied couldn't be unmarshalled
+    	* @throws PersistencyException when there was a problem communicating with storage
+    	**/
         void initialise( in string  agentProps )
             raises( common::AccessRightsException,
                     common::InvalidDataException,
                     common::PersistencyException );
+                    
+        /** Supplies the new set of jobs for the given item and activity. The Agent should replace all existing jobs for that activity 
+          * with the given set. This method should generally only be called by a workflow while performing an execution.
+          *
+          * @param sysKey the item which generated the jobs
+          * @param stepPath the activity within the lifecycle of the item which the jobs relate to
+          * @param newJobs an XML marshalled {@link com.c2kernel.entity.agent.JobArrayList JobArrayList} containing the new Jobs
+          **/
 		void refreshJobList( in unsigned long sysKey, in string stepPath, in string newJobs );
+		
+		/** Add this Agent to the given role
+		  * @param roleName the new role to add
+		  * @throws ObjectNotFoundException when the role doesn't exist
+		  * @throws CannotManageException when an error occurs writing the data to LDAP
+		  **/
 		void addRole( in string roleName )
 			raises( common::ObjectNotFoundException,
 					common::CannotManageException );
+
+		/** Remove this Agent from the given role
+		  * @param the role name to remove
+		  * @throws CannotManageException when an error occurs writing the data to LDAP
+		  **/
 		void removeRole( in string roleName )
 			raises( common::ObjectNotFoundException,
 					common::CannotManageException );
@@ -77,40 +106,17 @@ module entity
 
 
     /**************************************************************************
-    * Item is an ManageableEntity which have LifeCycle(s) and can have a
-    * History, Collections and Queries.
-    *
-    * <p><pre>Here is the summary of the different Item configuration:
-    * - It always has one or more LifeCycles.
-    * - It is persistent or not. This is relevant when the Item's LifeCycle
-    *   is very short and/or there is no need for recovery from crash.
-    *   It is very likely that an Item with no persistency cannot use Queries.
-    * - Item can have only one History. It is possible to have an Item
-    *   without History which means it does not support audit trailing.
-    *   An Item with no persistency very likely won't need the History.
-    * - Item can have many Collection of the different types (see: {@link CollectionBase}).
-    *   In the simple case Item have one Collection for each type but it
-    *   also should be able to have many Collections of the same type.
-    *   Note that for the later collections have to be named in order to
-    *   identify them!
-    * - Item can have a list of named Queries (can be empty list).
-    *
-    * One extreme is to create a non persistent Item which has only
-    *   the LifeCycle. This Item can 'only' generate Events in the proper order
-    *   and execute special Actions which are implemented by the domain user.
-    *   A simple user code could be such an Item!
-    *</pre>
-    *
-    * @author kovax
-    * @version 1.0
+    * Item is an ManageableEntity which has a lifecycle, and as a consequence 
+    * generates Events, Outcomes and Viewpoints.
     **************************************************************************/
-
     interface Item : ManageableEntity
     {
-        /**
-        *
-        * @param
+        /** Initialises a new Item. Initial properties and the lifecycle are supplied. They should come from the Item's description.
         *
+        * @param agentId the Agent doing the initialisation
+        * @param itemProps The XML marshalled {@link com.c2kernel.Property.PropertyArrayList PropertyArrayList} containing the initial
+    	* Property objects of the Agent
+        * @param workflow The XML marshalled new lifecycle of the Item
         * @exception ObjectNotFoundException
         **/
         void initialise( in unsigned long agentId,
@@ -121,26 +127,33 @@ module entity
                     common::PersistencyException );
 
         /**
-        * The Agent reguests one Step in the LifeCycle to perform one Transition.
-        * Item delegetes this request to its LifeCycle object.
-        *
-        * @param agentInfo Complete identification of the Agent. It is used
-        *   to check the rigths of the Agent (see:{@link AccessRigthsException})
+        * Requests a transition of an Activity in this Item's workflow. If possible and permitted, an Event is 
+        * generated and stored, the Activity's state is updated, which may cause the Workflow to proceed. If 
+        * this transition requires Outcome data, this is supplied and stored, and a Viewpoint will be created 
+        * or updated to point to this latest version. In the case of PredefinedSteps, additional data changes 
+        * may be performed in the server data.
+        * 
+        * This method should not be called directly, as there is a large client side to activity execution 
+        * implemented in the Proxy objects, such as script execution and schema validation.
         *
-        * @param lifeCycleID
+        * @param agentID The ID of the Agent. Some activities may be restricted in which roles may execute them.
+        * Some transitions cause the activity to be assigned to the executing Agent.
         *
-        * @param stepPath The id of the Step in the LifeCycle tree
+        * @param stepPath The path in the Workflow to the desired Activity
         *
-        * @param transitionID The id of the Transition
+        * @param transitionID The transition to be performed
         *
-        * @param reguestData Domain specific data required to process the
-        *   request (eg. conidtions).
+        * @param requestData The XML Outcome of the work defined by the Activity. Must be valid to the XML Schema,
+        * though this is not verified on the server, rather in the AgentProxy in the Client API.
         *
-        * @exception AccessRigthsException The Agent has no rigths
-        *   to make the request.
-        * @exception InvalidTransitionException It is impossible to
-        *   perform the Transition.
-        * @exception ObjectNotFoundException Step does not exists.
+        * @throws AccessRightsException The Agent is not permitted to perform the operation. Either it does not 
+        * have the correct role, or the Activity is reserved by another Agent. Also thrown when the given Agent ID doesn't exist.
+        * @throws InvalidTransitionException The Activity is not in the correct state to make the requested transition.
+        * @throws ObjectNotFoundException The Activity or a container of it does not exist.
+        * @throws InvalidDataException An activity property for the requested Activity was invalid e.g. SchemaVersion was not a number. 
+        Also thrown when an uncaught Java exception or error occurred.
+        * @throws PersistencyException There was a problem committing the changes to storage.
+        * @throws ObjectAlreadyExistsException Not normally thrown, but reserved for PredefinedSteps to throw if they need to.
         **/
         void requestAction( in unsigned long       agentID,
                             in string              stepPath,
@@ -156,17 +169,16 @@ module entity
 
 
         /**
-        * Queries the LifeCycle for Steps with different conditions. Returns the
-        * xml string containing the Steps matching those conditions.
-        *
-        * @param agentInfo Complete identification of the Agent. It is used
-        * if 'filter' is true.
-        *
-        * @param stateID The ID of the State (eg. Active)
-        *
-        * @param filter false: All the Steps; true: Steps for the Agent only (ID ,role)
+        * Returns a set of Jobs for this Agent on this Item. Each Job represents a possible transition
+        * of a particular Activity in the Item's lifecycle. The list may be filtered to only refer to 
+        * currently active activities. 
         *
-        * @return The result string in xml format (could be many Steps, or nothing).
+        * @param agentId The system key of the Agent requesting Jobs.
+        * @param filter If true, then only Activities which are currently active will be included.
+        * @return An XML marshalled {@link com.c2kernel.entity.agent.JobArrayList JobArrayList}
+        * @throws AccessRightsException - when the Agent doesn't exist
+        * @throws ObjectNotFoundException - when the Item doesn't have a lifecycle
+        * @throws PersistencyException - when there was a storage or other unknown error
         **/
         string queryLifeCycle( in unsigned long       agentId,                              
                                in boolean             filter )
diff --git a/src/main/java/com/c2kernel/entity/TraceableEntity.java b/src/main/java/com/c2kernel/entity/TraceableEntity.java
index 83c30a2..c6442a0 100644
--- a/src/main/java/com/c2kernel/entity/TraceableEntity.java
+++ b/src/main/java/com/c2kernel/entity/TraceableEntity.java
@@ -244,22 +244,37 @@ public class TraceableEntity extends ItemPOA
     {
         synchronized (this) {
             Logger.msg(1, "TraceableEntity::queryLifeCycle("+mSystemKey+") - agent: " + agentId);
-
-            try
-            {
-                AgentPath agent = new AgentPath(agentId);
-                Workflow wf = (Workflow)mStorage.get(mSystemKey, ClusterStorage.LIFECYCLE+"/workflow", null);
+            try {
+                AgentPath agent;
+				try {
+					agent = new AgentPath(agentId);
+				} catch (InvalidEntityPathException e) {
+					throw new AccessRightsException("Agent "+agentId+" doesn't exist");
+				}
+                Workflow wf;
+				try {
+					wf = (Workflow)mStorage.get(mSystemKey, ClusterStorage.LIFECYCLE+"/workflow", null);
+				} catch (ClusterStorageException e) {
+					Logger.error("TraceableEntity::queryLifeCycle("+mSystemKey+") - Error loading workflow");
+					Logger.error(e);
+					throw new PersistencyException("Error loading workflow");
+				}
                 JobArrayList jobBag = new JobArrayList();
                 CompositeActivity domainWf = (CompositeActivity)wf.search("workflow/domain");
                 jobBag.list = filter?domainWf.calculateJobs(agent, true):domainWf.calculateAllJobs(agent, true);
                 Logger.msg(1, "TraceableEntity::queryLifeCycle("+mSystemKey+") - Returning "+jobBag.list.size()+" jobs.");
-                return Gateway.getMarshaller().marshall( jobBag );
-            }
-            catch( Throwable ex )
-            {
-                Logger.error(ex);
-                return "<ERROR/>";
-            }
+                try {
+					return Gateway.getMarshaller().marshall( jobBag );
+				} catch (Exception e) {
+					Logger.error(e);
+					throw new PersistencyException("Error marshalling job bag");
+				}
+	        }
+	        catch ( Throwable ex ) {
+	        	Logger.error("TraceableEntity::queryLifeCycle("+mSystemKey+") - Unknown error");
+	            Logger.error(ex);
+	            throw new PersistencyException("Unknown error querying jobs. Please see server log.");
+	        }
         }
     }
 
-- 
cgit v1.2.3