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/Entity.idl | 174 ++++++++++++++++++++++++++----------------------
 1 file changed, 93 insertions(+), 81 deletions(-)

(limited to 'src/main/idl/Entity.idl')

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 )
-- 
cgit v1.2.3