TSt.dcl 11.1 KB
Newer Older
1 2
definition module TSt
/**
3 4 5
* This module defines the core task state data structure which is transformed by tasks.
* 
* Additionally it provides utility functions to manipulate the state.
6 7
*/
import StdMaybe
8 9
import Types, Void
import TaskTree
10
import RPC
11

Bas Lijnse's avatar
Bas Lijnse committed
12
from SessionDB	import :: Session
13
from Config		import :: Config(..)
14
from Store		import :: Store(..)
15
from Time		import :: Timestamp(..)
16 17
from Http		import :: HTTPRequest

18 19
from	iTasks import class iTask(..)
import	GenPrint, GenParse, GenVisualize, GenUpdate
20

21
// The task state
22 23
:: *TSt 		=	{ taskNr 		:: !TaskNr											// for generating unique form-id's
					, taskInfo		:: !TaskInfo										// task information available to tasks
24
					, firstRun		:: !Bool											// Is this task evaluated for the first time
Bas Lijnse's avatar
Bas Lijnse committed
25
					, curValue		:: !Maybe Dynamic									// Current task value
26 27 28 29
					, userId		:: !UserId											// id of user to which task is assigned
					, delegatorId	:: !UserId											// id of user who issued the task
					, tree			:: !TaskTree										// accumulator for constructing a task tree			
					, activated		:: !Bool   											// if true activate task, if set as result task completed
30

31
					, mainTask		:: !ProcessId										// The id of the current main task 
32
							
33
					, options		:: !Options											// options
34
					, staticInfo	:: !StaticInfo										// info which does not change during a run
35
					
36
					, exception		:: !Maybe Dynamic									// Optional, used when raising exceptions
37
					
38 39
					, doChange		:: !Bool											// Apply change
					, changes		:: ![Maybe (!ChangeLifeTime, !DynamicId, !Dynamic)]	// Active changes
40
					
41
					, config		:: !Config											// The server configuration
42
					, request		:: !HTTPRequest										// The current http request
43
									
ecrombag's avatar
ecrombag committed
44 45
					, systemStore	:: !Store											// UserDB
					, dataStore		:: !Store											// Runtime data (Processes, Sessions, Tasks, Dynamics)
46
					, documentStore	:: !Store											// Documents
47
					, world			:: !*World											// The world
48 49
					}

50
:: Options		=	{ trace			:: !Bool									// default: False
51 52
					}

53 54
:: StaticInfo	=	{ appName			:: String								// the name of the server executable
					, currentProcessId	:: !ProcessId							// the id of the current process
55
					, currentSession	:: Session								// the current session			
56
					, staticWorkflows	:: ![Workflow]							// the list of workflows supported by the application				
57
					}
58

59

60

61 62 63 64 65 66
// A workflow specification
:: Workflow		=	{ name			:: !String									// a unique name of this workflow
					, label			:: !String									// a label that will be used for displaying
					, roles			:: ![String]								// the roles that are allowed to initate this workflow
					, mainTask		:: Task Void								// the main task of the workflow
					}
67 68

// A change function which may be used to change tasks at runtime
69
:: Change a :== (TaskProperties (Task a) (Task a) -> (Maybe TaskProperties, Maybe (Task a), Maybe Dynamic))
70

71 72 73 74
// Changes may be applied only once, or persist for future changes
:: ChangeLifeTime	= CLTransient
					| CLPersistent !String

75 76 77
/**
* Creates an initial task state.
*
78
* @param The application name
79
* @param The server configuration
80
* @param The current HTTP request
81 82
* @param The session data
* @param The workflows available in the application
83
* @param The generic data store
84
* @param The world
85 86 87
*
* @return a TSt iTask state
*/
88
mkTSt :: String Config HTTPRequest Session ![Workflow] !*Store !*Store !*Store !*World -> *TSt
89 90

/**
91
* Creates an instance of a task definition
92
* As soon as an instance is created it is immediately evaluated once.
93
*
94 95
* @param The task
* @param Start as toplevel, or as subtask of another task (parent information is read from the task state)
96 97
* @param The task state
*
98 99
* @param The process id of the instance
* @param The modified task state
100
*/
101
createTaskInstance :: !(Task a) !TaskManagerProperties !Bool !*TSt -> (!ProcessId, !*TSt) | iTask a
102

103 104 105 106 107 108 109 110 111
/**
* Calculates a single task tree for a given process id
*
* @param The process id
* @param The task state
*
* @return Just an HtmlTree when the process is found, Nothing on failure
* @return The modified task state
*/
112 113 114 115 116 117 118 119 120 121 122 123
calculateTaskTree :: !ProcessId !*TSt -> (!TaskTree, !*TSt)

/**
* Calculates all task trees
*
* @param The task state
*
* @return The list of task trees (task forest)
* @return The modified task state
*/
calculateTaskForest :: !*TSt -> (![TaskTree], !*TSt)

124

125 126 127 128
/**
* Applies a change to a running task process task state.
* 
* @param The process id
129
* @param The change in a dynamic
130
* @param The change lifetime
131 132 133 134
* @param The task state
*
* @return The modified task state
*/
135
applyChangeToTaskTree :: !ProcessId !Dynamic !ChangeLifeTime !*TSt -> *TSt
136

137
/**
138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
* Lists which workflows are available
*
* @param The task state
*
* @return The list of workflows
* @return The modified task state
*/
getWorkflows :: !*TSt -> (![Workflow],!*TSt)
/**
* Looks up a specific workflow by name
*
* @param The unique workflow name
* @param The task state
*
* @return Maybe the workflow definition
* @return The modified task state
*/
getWorkflowByName :: !String !*TSt -> (!Maybe Workflow, !*TSt)

/**
158
* Apply a function on World on a TSt
159
*/ 
160
appWorldTSt	:: !.(*World -> *World) !*TSt -> *TSt
161 162

/**
163
* Apply a function yielding a result on World on a TSt
164
*/
165
accWorldTSt	:: !.(*World -> *(.a,*World))!*TSt -> (.a,!*TSt)
166 167 168 169 170 171 172

/**
* Get the current session from the TSt
*/
getCurrentSession :: !*TSt 	-> (!Session, !*TSt)

/**
173
* Get the id of the current process in the TSt
174 175 176 177 178 179 180 181
*/

getCurrentProcess :: !*TSt -> (!ProcessId, !*TSt)
/**
* Extract the calculated task forest data structure from the TSt
*/
getTaskTree :: !*TSt	-> (!TaskTree, !*TSt)

182 183
//// TASK CREATION

184 185
/**
* Wrap a function of proper type to create a function that also
186 187 188
* keeps track of the the internal numbering and administration.
* The given task function will add a single basic step to the current
* sequence.
189 190 191 192 193
*
* @param A name used as the task label
* @param The function on the TSt that is the task
*
* @return The newly constructed basic task
194
*/
195
mkInteractiveTask			:: !String !(*TSt -> *(!a,!*TSt)) -> Task a
Bas Lijnse's avatar
Bas Lijnse committed
196

Bas Lijnse's avatar
Bas Lijnse committed
197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222
/**
* Wrap a function of proper type to create a function that also
* keeps track of the the internal numbering and administration.
* The given task function will add a single instantly computed step to
* the current sequence.
*
* @param A name used as the task label
* @param The function on the TSt that is the task
*
* @return The newly constructed basic task
*/
mkInstantTask		:: !String !(*TSt -> *(!a,!*TSt)) -> Task a

/**
* Wrap a function of proper type to create a function that also
* keeps track of the the internal numbering and administration.
* The given task function will add a monitoring task to the 
* the current sequence.
*
* @param A name used as the task label
* @param The function on the TSt that is the task
*
* @return The newly constructed basic task
*/
mkMonitorTask :: !String !(*TSt -> *(!a,!*TSt)) -> Task a

223 224 225 226 227 228 229 230 231 232 233

/**
* Creates an rpc task from an rpc call definition.
* A parse function is used to parse the result of the rpc call
*
* @param A name used as the task label
* @param The initial RPC info record
* @param The parse function
*
* @return The constructed RPC task
*/
234
mkRpcTask :: !String !RPCExecute !(String -> a) -> Task a | gUpdate{|*|} a
235 236


237 238 239 240
/**
* Wraps a function of proper type to create a task that will consist
* of a sequence of subtasks. The given task function will execute in a blank sequence
* and the resulting sequence will be combined in a single sequence node.
241 242 243 244 245
*
* @param A name used as the task label
* @param The function on the TSt that is the task
*
* @return The newly constructed sequence task
246
*/
247
mkSequenceTask		:: !String !(*TSt -> *(!a,!*TSt)) -> Task a
248 249 250 251 252

/**
* Wrap a function of proper type to create a function that also
* keeps track of the the internal numbering and administration for
* combining a set of parallel subtasks
253 254 255 256 257
*
* @param A name used as the task label
* @param The function on the TSt that is the task
*
* @return The newly constructed parallel task
258
*/
259
mkParallelTask 		:: !String !(*TSt -> *(!a,!*TSt)) -> Task a
260

261 262 263 264 265 266
/**
* Wrap a function of proper type to create a function that will make a
* main task. This is a sequence node that keeps track of additional information
* such as task status, event times and user/delegate information.
*
* @param A name used as the task label
267
* @param The task that will run inside the main task
268 269 270
*
* @return The newly constructed sequence task
*/
271
mkMainTask		:: !String !(*TSt -> *(!a,!*TSt)) -> Task a
272 273 274 275 276 277 278 279 280 281 282 283

//// TASK APPLICATION

/**
* Applies a task to the task state and yields the tasks result.
*
* @param The task that is applied
* @param The task state
*
* @return The value produced by the task
* @return The modified task state
*/
284
applyTask			:: !(Task a) !*TSt -> (!a,!*TSt) | iTask a
285 286


287
//// TASK CONTENT
288
setTUIDef			:: !TUIDef !*TSt				-> *TSt	//Only for interactive tasks
289

290
setTUIUpdates		:: ![TUIUpdate] !*TSt			-> *TSt //Only for interactive tasks
Bas Lijnse's avatar
Bas Lijnse committed
291

Bas Lijnse's avatar
Bas Lijnse committed
292
setStatus			:: ![HtmlTag] !*TSt				-> *TSt	//Only for monitor tasks
Bas Lijnse's avatar
Bas Lijnse committed
293 294 295 296 297

getTaskValue		:: !*TSt						-> (Maybe a, !*TSt) | TC a

getUserUpdates		:: !*TSt						-> ([(String,String)],!*TSt)

298
//loadTaskFunction	:: !TaskNr !*TSt				-> (Maybe (Task a), !*TSt)
Bas Lijnse's avatar
Bas Lijnse committed
299

300 301 302 303 304 305 306 307 308 309
/**
* Writes a 'task scoped' value to the store
* These values are copied and garbage collected along with a task
*/
setTaskStore		:: !String !a !*TSt				-> *TSt | iTask a
/**
* Reads a 'task scoped' value from the store
*/
getTaskStore		:: !String !*TSt				-> (Maybe a, !*TSt) | iTask a

310
/**
311
* Store and load the result of a workflow instance
312
*/
313 314
loadProcessResult		:: !TaskNr 					!*TSt -> (!Maybe a, !*TSt) | TC a
storeProcessResult		:: !TaskNr !Dynamic			!*TSt -> *TSt
315

316 317 318 319 320
/**
* Removes all events for the current task. This is automatically called by applyTask
* after task evaluation to prevent updates from being applied twice.
*/
clearUserUpdates	:: !*TSt						-> *TSt
321

322
/**
Bas Lijnse's avatar
Bas Lijnse committed
323 324 325
* Resets a sequence
*/
resetSequence		::	!*TSt					-> *TSt
Bas Lijnse's avatar
Bas Lijnse committed
326 327

/**
328
* Delete task state (for garbage collection) for a task and its subtasks
Bas Lijnse's avatar
Bas Lijnse committed
329
* 
330
* @param Task nr to delete states for
Bas Lijnse's avatar
Bas Lijnse committed
331 332
* @param The task state
*
333
* @return The updated task state
Bas Lijnse's avatar
Bas Lijnse committed
334
*/
335 336 337 338 339 340 341 342 343 344 345 346
deleteTaskStates	:: !TaskNr !*TSt			-> *TSt
/**
* Copy task state for a task and its subtasks.
*
* @param From task nr
* @param To task nr
* @param The task state
*
* @return The updated task state
*/
copyTaskStates		:: !TaskNr !TaskNr !*TSt	-> *TSt

347 348 349 350 351 352
/**
* Writes all cached values in the store
*/
flushStore			:: !*TSt					-> *TSt


353
//// UTILITY
354

355
/**
356
* Parses a formatted task number to its integer list representation
357
*
358
* @param The task nr as formatted string
359
*
360 361 362
* @return The task nr as integer list
*/
taskNrFromString 	:: !String 					-> TaskNr
363 364 365 366 367 368 369 370
/**
* Converts a task number to its dotted string representation
*
* @param The task number as integer list
*
* @return The formatted task number
*/
taskNrToString		:: !TaskNr 					-> String
371 372 373 374 375 376 377 378 379

/**
* Extracts the task label of a task
*
* @param The task
* 
* @return The task's label
*/
taskLabel			:: !(Task a)				-> String
380

381 382 383 384 385 386
//Should not be public!
createTaskThread :: !(Task a) -> (*TSt -> *(!Dynamic,!*TSt)) | iTask a
storeTaskThread :: !TaskNr !(*TSt -> *(!Dynamic,!*TSt)) !*TSt -> *TSt
loadTaskThread :: !TaskNr !*TSt -> (*TSt -> *(!Dynamic,!*TSt), !*TSt)
loadTaskFunctionStatic  :: !TaskNr !*TSt -> (!Maybe (Task a),       !*TSt) | TC a
storeTaskFunctionStatic  :: !TaskNr !(Task a)       !*TSt -> *TSt | TC a