1Workflow::Factory(3)  User Contributed Perl Documentation Workflow::Factory(3)
2
3
4

NAME

6       Workflow::Factory - Generates new workflow and supporting objects
7

VERSION

9       This documentation describes version 1.61 of this package
10

SYNOPSIS

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

DESCRIPTION

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

METHODS

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 ensure
111       the configurations are added in the proper order -- when you add an
112       'action' configuration and reference 'validator' objects, those objects
113       should already be read in. A good order is: 'validator', 'condition',
114       'action', 'workflow'. Then just pass the resulting hash references to
115       add_config() using the right type and the behavior should be exactly
116       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 ) [ deprecated ]
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       get_action_config( $workflow, $action_name )
183
184       Retrieves the configuration for action $action_name as specified in the
185       actions configuration file, with the keys listed in the 'action'
186       section of Workflow::Config
187
188       Throws exception if no action with name $action_name available.
189
190       Returns: A hash with the configuration as its keys.
191
192       get_persister( $persister_name )
193
194       Retrieves the persister with name $persister_name.
195
196       Throws exception if no persister with name $persister_name available.
197
198       get_condition( $condition_name )
199
200       Retrieves the condition with name $condition_name.
201
202       Throws exception if no condition with name $condition_name available.
203
204       get_validator( $validator_name )
205
206       Retrieves the validator with name $validator_name.
207
208       Throws exception if no validator with name $validator_name available.
209
210   Internal Configuration Methods
211       _add_workflow_config( @config_hashrefs )
212
213       Adds all configurations in @config_hashrefs to the factory. Also cycles
214       through the workflow states and creates a Workflow::State object for
215       each. These states are passed to the workflow when it is instantiated.
216
217       We also require any necessary observer classes and throw an exception
218       if we cannot. If successful the observers are kept around and attached
219       to a workflow in create_workflow() and fetch_workflow().
220
221       Returns: nothing
222
223       _load_observers( $workflow_config_hashref )
224
225       Loads and adds observers based on workflow type
226
227       Returns number indicating amount of observers added, meaning zero can
228       indicate success based on expected outcome.
229
230       _add_action_config( @config_hashrefs )
231
232       Adds all configurations in @config_hashrefs to the factory, doing a
233       'require' on the class referenced in the 'class' attribute of each
234       action.
235
236       Throws an exception if there is no 'class' associated with an action or
237       if we cannot 'require' that class.
238
239       Returns: nothing
240
241       _add_persister_config( @config_hashrefs )
242
243       Adds all configurations in @config_hashrefs to the factory, doing a
244       'require' on the class referenced in the 'class' attribute of each
245       persister.
246
247       Throws an exception if there is no 'class' associated with a persister,
248       if we cannot 'require' that class, or if we cannot instantiate an
249       object of that class.
250
251       Returns: nothing
252
253       _add_condition_config( @config_hashrefs )
254
255       Adds all configurations in @config_hashrefs to the factory, doing a
256       'require' on the class referenced in the 'class' attribute of each
257       condition.
258
259       Throws an exception if there is no 'class' associated with a condition,
260       if we cannot 'require' that class, or if we cannot instantiate an
261       object of that class.
262
263       Returns: nothing
264
265       _add_validator_config( @config_hashrefs )
266
267       Adds all configurations in @config_hashrefs to the factory, doing a
268       'require' on the class referenced in the 'class' attribute of each
269       validator.
270
271       Throws an exception if there is no 'class' associated with a validator,
272       if we cannot 'require' that class, or if we cannot instantiate an
273       object of that class.
274
275       Returns: nothing
276
277       _commit_transaction
278
279       Calls the commit method in the workflow's persister.
280
281       Returns: nothing
282
283       _rollback_transaction
284
285       Calls the rollback method in the workflow's persister.
286
287       associate_observers_with_workflow
288
289       Add defined observers with workflow.
290
291       The workflow has to be provided as the single parameter accepted by
292       this method.
293
294       The observers added will have to be of the type relevant to the
295       workflow type.
296
297       new
298
299       The new method is a dummy constructor, since we are using a factory it
300       makes no sense to call new - and calling new will result in a
301       Workflow::Exception
302
303       "instance" should be called or the imported 'FACTORY' should be
304       utilized.
305

DYNAMIC CONFIG LOADING

307       If you have either a large set of config files or a set of very large
308       config files then you may not want to incur the overhead of loading
309       each and every one on startup if you cannot predict which set you will
310       use in that instance of your application.
311
312       This approach doesn't make much sense in a persistent environment such
313       as mod_perl but it may lower startup costs if you have regularly
314       scheduled scripts that may not need to touch all possible types of
315       workflow.
316
317       To do this you can specify a callback that the factory will use to
318       retrieve batched hashes of config declarations. Whenever an unknown
319       workflow name is encountered the factory will first try to load your
320       config declarations then continue.
321
322       The callback takes one argument which is the workflow type. It should
323       return a reference to a hash of arguments in a form suitable for
324       "add_config_from_file".
325
326       For example:
327
328        use Workflow::Factory qw(FACTORY);
329        use My::Config::System;
330
331        sub init {
332          my $self = shift;
333
334          FACTORY->config_callback(
335            sub {
336              my $wf_type = shift;
337              my %ret = My::Config::System->get_files_for_wf( $wf_type ) || ();
338              return \%ret;
339            }
340          );
341        }
342

SUBCLASSING

344   Implementation and Usage
345       You can subclass the factory to implement your own methods and still
346       use the useful facade of the "FACTORY" constant. For instance, the
347       implementation is typical Perl subclassing:
348
349        package My::Cool::Factory;
350
351        use strict;
352        use base qw( Workflow::Factory );
353
354        sub some_cool_method {
355            my ( $self ) = @_;
356            ...
357        }
358
359       To use your factory you can just do the typical import:
360
361        #!/usr/bin/perl
362
363        use strict;
364        use My::Cool::Factory qw( FACTORY );
365
366       Or you can call instance() directly:
367
368        #!/usr/bin/perl
369
370        use strict;
371        use My::Cool::Factory;
372
373        my $factory = My::Cool::Factory->instance();
374

GLOBAL RUN-TIME OPTIONS

376       Setting package variable $VALIDATE_ACTION_CONFIG to a true value (it is
377       undef by default) turns on optional validation of extra attributes of
378       Workflow::Action configs.  See Workflow::Action for details.
379

SEE ALSO

381       •   Workflow
382
383       •   Workflow::Action
384
385       •   Workflow::Condition
386
387       •   Workflow::Config
388
389       •   Workflow::Persister
390
391       •   Workflow::Validator
392
394       Copyright (c) 2003-2022 Chris Winters. All rights reserved.
395
396       This library is free software; you can redistribute it and/or modify it
397       under the same terms as Perl itself.
398
399       Please see the LICENSE
400

AUTHORS

402       Please see Workflow
403
404
405
406perl v5.36.0                      2023-01-20              Workflow::Factory(3)
Impressum