1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
#ifndef __Entity_Idl__
#define __Entity_Idl__
/*
* Copyright (C) 2001 CERN - European Organization for Nuclear Research
* All rights reserved.
*
* @author $Author: abranson $ $Date: 2005/04/26 06:47:48 $
* @version $Revision: 1.24 $
*/
#include <CommonTypes.idl>
#pragma prefix "c2kernel.com"
module entity
{
/**
* 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
{
/**
* 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();
/**
* 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,
common::ObjectNotFoundException,
common::PersistencyException );
/**
* 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 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 path in the Workflow to the desired Activity
*
* @param transitionID The transition to be performed
*
* @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.
*
* @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,
in unsigned long transitionID,
in string requestData
)
raises( common::AccessRightsException,
common::InvalidTransitionException,
common::ObjectNotFoundException,
common::InvalidDataException,
common::PersistencyException,
common::ObjectAlreadyExistsException );
/**
* 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.
*
* @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 )
raises( common::AccessRightsException,
common::ObjectNotFoundException,
common::PersistencyException );
};
/**************************************************************************
* 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 unsigned long agentId,
in string itemProps,
in string workflow )
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 );
};
/**************************************************************************
* Item is an ManageableEntity which has a lifecycle, and as a consequence
* generates Events, Outcomes and Viewpoints.
**************************************************************************/
interface Item : ManageableEntity
{
/** 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,
in string itemProps,
in string workflow,
in string collections )
raises( common::AccessRightsException,
common::InvalidDataException,
common::PersistencyException );
}; //end of Item
}; //end of module entity
#endif //__Entity_Idl__
|
