Javadoc on IDLs

2 files changed, 100 insertions, 93 deletions

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 )