Cleaned up documentation for SysKey changes

2 files changed, 17 insertions, 15 deletions

diff --git a/src/main/idl/CommonTypes.idl b/src/main/idl/CommonTypes.idl
index 09b0767..1e53343 100644
--- a/src/main/idl/CommonTypes.idl
+++ b/src/main/idl/CommonTypes.idl
@@ -36,7 +36,8 @@ module common
     };

 

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

-    * Serialized UUID for Item identification

+    * Serialized UUID for Item identification. 

+    * Converts to Java UUID with: new UUID(msb, lsb);

     *

     * @version 1.0

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

diff --git a/src/main/idl/Entity.idl b/src/main/idl/Entity.idl
index 24e5d9c..7305e53 100644
--- a/src/main/idl/Entity.idl
+++ b/src/main/idl/Entity.idl
@@ -25,23 +25,24 @@ module entity
     {

 

         /**

-        * System generated unique key of the Entity. It is unique in the domain tree of the local centre in which is is contained.

+        * System generated unique key of the Entity. It is a 128 bit UUID, expressed as two 64 bit longs in the IDLs, but as a UUID object in the Java kernel. The ItemPath is used as the Item identifier in the kernel and its API, 

+        which can be derived from either a UUID object or a SystemKey structure.

         **/

         common::SystemKey getSystemKey();

 

         /** 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 agentKey the Agent doing the initialisation

         * @param itemProps The XML marshalled {@link com.c2kernel.Property.PropertyArrayList PropertyArrayList} containing the initial

     	* Property objects of the Item

         * @param workflow The XML marshalled new lifecycle of the Item

         * @param collection The XML marshalled CollectionArrayList of the initial state of the Item's collections

         * @exception ObjectNotFoundException

         **/

-        void initialise( in common::SystemKey  agentId,

-        				 in string  itemProps,

-                         in string  workflow,

-                         in string  collections )

+        void initialise( in common::SystemKey  agentKey,

+        				 in string             itemProps,

+                         in string             workflow,

+                         in string             collections )

             raises( common::AccessRightsException,

                     common::InvalidDataException,

                     common::PersistencyException,

@@ -67,7 +68,7 @@ module 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 )

+        string queryData( in string path )

             raises( common::AccessRightsException,

                     common::ObjectNotFoundException,

                     common::PersistencyException );

@@ -82,7 +83,7 @@ module entity
         * 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 agentID The ID of the Agent. Some activities may be restricted in which roles may execute them.

+        * @param agentKey The SystemKey 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 path in the Workflow to the desired Activity

@@ -101,7 +102,7 @@ module entity
         * @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.

         **/

-        string requestAction( in common::SystemKey agentID,

+        string requestAction( in common::SystemKey agentKey,

                             in string              stepPath,

                             in unsigned long       transitionID,

                             in string    			requestData

@@ -119,14 +120,14 @@ module entity
         * of a particular Activity in the Item's lifecycle. The list may be filtered to only refer to 

         * currently active activities. 

         *

-        * @param agentId The system key of the Agent requesting Jobs.

+        * @param agentKey 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 common::SystemKey   agentId,                              

+        string queryLifeCycle( in common::SystemKey   agentKey,                              

                                in boolean             filter )

             raises( common::AccessRightsException,

                     common::ObjectNotFoundException,

@@ -145,11 +146,11 @@ module entity
         /** 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 itemKey the item which generated the jobs. The Agent should discard any existing jobs for that Item.

+          * @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 common::SystemKey sysKey,

+		void refreshJobList( in common::SystemKey itemKey,

 							 in string stepPath,

 							 in string newJobs );