From 19e84996506d092a70b018c5f640d1ef82a48740 Mon Sep 17 00:00:00 2001 From: Andrew Branson Date: Wed, 10 Sep 2014 09:20:31 +0200 Subject: Cleaned up documentation for SysKey changes --- src/main/idl/CommonTypes.idl | 3 ++- src/main/idl/Entity.idl | 29 +++++++++++++++-------------- 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 Not currently implemented * @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 ); -- cgit v1.2.3