1Workflow::Factory(3) User Contributed Perl Documentation Workflow::Factory(3)
2
3
4
6 Workflow::Factory - Generates new workflow and supporting objects
7
9 This documentation describes version 1.54 of this package
10
12 # Import the singleton for easy access
13 use Workflow::Factory qw( FACTORY );
14
15 # Add XML configurations to the factory
16 FACTORY->add_config_from_file( workflow => 'workflow.xml',
17 action => [ 'myactions.xml', 'otheractions.xml' ],
18 validator => [ 'validator.xml', 'myvalidators.xml' ],
19 condition => 'condition.xml',
20 persister => 'persister.xml' );
21
22 # Create a new workflow of type 'MyWorkflow'
23 my $wf = FACTORY->create_workflow( 'MyWorkflow' );
24
25 # Fetch an existing workflow with ID '25'
26 my $wf = FACTORY->fetch_workflow( 'MyWorkflow', 25 );
27
29 Public
30 The Workflow Factory is your primary interface to the workflow system.
31 You give it the configuration files and/or data structures for the
32 Workflow, Workflow::Action, Workflow::Condition, Workflow::Persister,
33 and Workflow::Validator objects and then you ask it for new and
34 existing Workflow objects.
35
36 Internal
37 Developers using the workflow system should be familiar with how the
38 factory processes configurations and how it makes the various
39 components of the system are instantiated and stored in the factory.
40
42 Public Methods
43 instance()
44
45 The factory is a singleton, this is how you get access to the instance.
46 You can also just import the 'FACTORY' constant as in the "SYNOPSIS".
47
48 create_workflow( $workflow_type, $context, $wf_class )
49
50 Create a new workflow of type $workflow_type. This will create a new
51 record in whatever persistence mechanism you have associated with
52 $workflow_type and set the workflow to its initial state.
53
54 The $context argument is optional, you can pass an exisiting instance
55 of Workflow::Context to be reused. Otherwise a new instance is created.
56
57 The $wf_class argument is optional. Pass it the name of a class to be
58 used for the workflow to be created. By default, all workflows are of
59 the Workflow class.
60
61 Any observers you've associated with this workflow type will be
62 attached to the returned workflow object.
63
64 This fires a 'create' event from the just-created workflow object. See
65 "WORKFLOWS ARE OBSERVABLE" in Workflow for more.
66
67 Returns: newly created workflow object.
68
69 fetch_workflow( $workflow_type, $workflow_id, $context, $wf_class )
70
71 Retrieve a workflow object of type $workflow_type and ID $workflow_id.
72 (The $workflow_type is necessary so we can fetch the workflow using the
73 correct persister.) If a workflow with ID $workflow_id is not found
74 "undef" is returned.
75
76 The $context argument is optional, you can pass an exisiting instance
77 of Workflow::Context to be reused. Otherwise a new instance is created.
78
79 The $wf_class argument is optional. Pass it the name of a class to be
80 used for the workflow to be created. By default, all workflows are of
81 the Workflow class.
82
83 Any observers you've associated with this workflow type will be
84 attached to the returned workflow object.
85
86 This fires a 'fetch' event from the retrieved workflow object. See
87 "WORKFLOWS ARE OBSERVABLE" in Workflow for more.
88
89 Throws exception if no workflow type $workflow_type available.
90
91 Returns: Workflow object
92
93 add_config_from_file( %config_declarations )
94
95 Pass in filenames for the various components you wish to initialize
96 using the keys 'action', 'condition', 'persister', 'validator' and
97 'workflow'. The value for each can be a single filename or an arrayref
98 of filenames.
99
100 The system is familiar with the 'perl' and 'xml' configuration formats
101 -- see the 'doc/configuration.txt' for what we expect as the format and
102 will autodetect the types based on the file extension of each file.
103 Just give your file the right extension and it will be read in
104 properly.
105
106 You may also use your own custom configuration file format -- see
107 "SUBCLASSING" in Workflow::Config for what you need to do.
108
109 You can also read it in yourself and add the resulting hash reference
110 directly to the factory using "add_config()". However, you need to
111 ensure the configurations are added in the proper order -- when you add
112 an 'action' configuration and reference 'validator' objects, those
113 objects should already be read in. A good order is: 'validator',
114 'condition', 'action', 'workflow'. Then just pass the resulting hash
115 references to "add_config()" using the right type and the behavior
116 should be exactly the same.
117
118 Returns: nothing; if we run into a problem parsing one of the files or
119 creating the objects it requires we throw a Workflow::Exception.
120
121 add_config( %config_hashrefs )
122
123 Similar to "add_config_from_file()" -- the keys may be 'action',
124 'condition', 'persister', 'validator' and/or 'workflow'. But the values
125 are the actual configuration hashrefs instead of the files holding the
126 configurations.
127
128 You normally will only need to call this if you are programmatically
129 creating configurations (e.g., hot-deploying a validator class
130 specified by a user) or using a custom configuration format and for
131 some reason do not want to use the built-in mechanism in
132 Workflow::Config to read it for you.
133
134 Returns: nothing; if we encounter an error trying to create the objects
135 referenced in a configuration we throw a Workflow::Exception.
136
137 get_persister_for_workflow_type
138
139 get_persisters
140
141 #TODO
142
143 get_validators
144
145 #TODO
146
147 Internal Methods
148 #TODO
149
150 save_workflow( $workflow )
151
152 Stores the state and current datetime of the $workflow object. This is
153 normally called only from the Workflow "execute_action()" method.
154
155 This method respects transactions if the selected persister supports
156 it. Currently, the DBI-based persisters will commit the workflow
157 transaction if everything executes successfully and roll back if
158 something fails. Note that you need to manage any
159 Workflow::Persister::DBI::ExtraData transactions yourself.
160
161 Returns: $workflow
162
163 get_workflow_history( $workflow )
164
165 Retrieves all Workflow::History objects related to $workflow.
166
167 NOTE: Normal users get the history objects from the Workflow object
168 itself. Under the covers it calls this.
169
170 Returns: list of Workflow::History objects
171
172 get_action( $workflow, $action_name )
173
174 Retrieves the action $action_name from workflow $workflow. Note that
175 this does not do any checking as to whether the action is proper given
176 the state of $workflow or anything like that. It is mostly an internal
177 method for Workflow (which does do checking as to the propriety of the
178 action) to instantiate new actions.
179
180 Throws exception if no action with name $action_name available.
181
182 Returns: Workflow::Action object
183
184 get_persister( $persister_name )
185
186 Retrieves the persister with name $persister_name.
187
188 Throws exception if no persister with name $persister_name available.
189
190 get_condition( $condition_name )
191
192 Retrieves the condition with name $condition_name.
193
194 Throws exception if no condition with name $condition_name available.
195
196 get_validator( $validator_name )
197
198 Retrieves the validator with name $validator_name.
199
200 Throws exception if no validator with name $validator_name available.
201
202 Internal Configuration Methods
203 _add_workflow_config( @config_hashrefs )
204
205 Adds all configurations in @config_hashrefs to the factory. Also cycles
206 through the workflow states and creates a Workflow::State object for
207 each. These states are passed to the workflow when it is instantiated.
208
209 We also require any necessary observer classes and throw an exception
210 if we cannot. If successful the observers are kept around and attached
211 to a workflow in create_workflow() and fetch_workflow().
212
213 Returns: nothing
214
215 _load_observers( $workflow_config_hashref )
216
217 Loads and adds observers based on workflow type
218
219 Returns number indicating amount of observers added, meaning zero can
220 indicate success based on expected outcome.
221
222 _add_action_config( @config_hashrefs )
223
224 Adds all configurations in @config_hashrefs to the factory, doing a
225 'require' on the class referenced in the 'class' attribute of each
226 action.
227
228 Throws an exception if there is no 'class' associated with an action or
229 if we cannot 'require' that class.
230
231 Returns: nothing
232
233 _add_persister_config( @config_hashrefs )
234
235 Adds all configurations in @config_hashrefs to the factory, doing a
236 'require' on the class referenced in the 'class' attribute of each
237 persister.
238
239 Throws an exception if there is no 'class' associated with a persister,
240 if we cannot 'require' that class, or if we cannot instantiate an
241 object of that class.
242
243 Returns: nothing
244
245 _add_condition_config( @config_hashrefs )
246
247 Adds all configurations in @config_hashrefs to the factory, doing a
248 'require' on the class referenced in the 'class' attribute of each
249 condition.
250
251 Throws an exception if there is no 'class' associated with a condition,
252 if we cannot 'require' that class, or if we cannot instantiate an
253 object of that class.
254
255 Returns: nothing
256
257 _add_validator_config( @config_hashrefs )
258
259 Adds all configurations in @config_hashrefs to the factory, doing a
260 'require' on the class referenced in the 'class' attribute of each
261 validator.
262
263 Throws an exception if there is no 'class' associated with a validator,
264 if we cannot 'require' that class, or if we cannot instantiate an
265 object of that class.
266
267 Returns: nothing
268
269 _commit_transaction
270
271 Calls the commit method in the workflow's persister.
272
273 Returns: nothing
274
275 _rollback_transaction
276
277 Calls the rollback method in the workflow's persister.
278
279 associate_observers_with_workflow
280
281 Add defined observers with workflow.
282
283 The workflow has to be provided as the single parameter accepted by
284 this method.
285
286 The observers added will have to be of the type relevant to the
287 workflow type.
288
289 new
290
291 The new method is a dummy constructor, since we are using a factory it
292 makes no sense to call new - and calling new will result in a
293 Workflow::Exception
294
295 "instance" should be called or the imported 'FACTORY' should be
296 utilized.
297
299 If you have either a large set of config files or a set of very large
300 config files then you may not want to incur the overhead of loading
301 each and every one on startup if you cannot predict which set you will
302 use in that instance of your application.
303
304 This approach doesn't make much sense in a persistent environment such
305 as mod_perl but it may lower startup costs if you have regularly
306 scheduled scripts that may not need to touch all possible types of
307 workflow.
308
309 To do this you can specify a callback that the factory will use to
310 retrieve batched hashes of config declarations. Whenever an unknown
311 workflow name is encountered the factory will first try to load your
312 config declarations then continue.
313
314 The callback takes one argument which is the workflow type. It should
315 return a reference to a hash of arguments in a form suitable for
316 "add_config_from_file".
317
318 For example:
319
320 use Workflow::Factory qw(FACTORY);
321 use My::Config::System;
322
323 sub init {
324 my $self = shift;
325
326 FACTORY->config_callback(
327 sub {
328 my $wf_type = shift;
329 my %ret = My::Config::System->get_files_for_wf( $wf_type ) || ();
330 return \%ret;
331 }
332 );
333 }
334
336 Implementation and Usage
337 You can subclass the factory to implement your own methods and still
338 use the useful facade of the "FACTORY" constant. For instance, the
339 implementation is typical Perl subclassing:
340
341 package My::Cool::Factory;
342
343 use strict;
344 use base qw( Workflow::Factory );
345
346 sub some_cool_method {
347 my ( $self ) = @_;
348 ...
349 }
350
351 To use your factory you can just do the typical import:
352
353 #!/usr/bin/perl
354
355 use strict;
356 use My::Cool::Factory qw( FACTORY );
357
358 Or you can call "instance()" directly:
359
360 #!/usr/bin/perl
361
362 use strict;
363 use My::Cool::Factory;
364
365 my $factory = My::Cool::Factory->instance();
366
368 Setting package variable $VALIDATE_ACTION_CONFIG to a true value (it is
369 undef by default) turns on optional validation of extra attributes of
370 Workflow::Action configs. See Workflow::Action for details.
371
373 • Workflow
374
375 • Workflow::Action
376
377 • Workflow::Condition
378
379 • Workflow::Config
380
381 • Workflow::Persister
382
383 • Workflow::Validator
384
386 Copyright (c) 2003-2021 Chris Winters. All rights reserved.
387
388 This library is free software; you can redistribute it and/or modify it
389 under the same terms as Perl itself.
390
391 Please see the LICENSE
392
394 Please see Workflow
395
396
397
398perl v5.34.0 2021-07-27 Workflow::Factory(3)