1Workflow::Factory(3) User Contributed Perl Documentation Workflow::Factory(3)
2
6 Workflow::Factory - Generates new workflow and supporting objects
7
9 This documentation describes version 1.18 of this package
10
12 # Import the singleton for easy access
13 use Workflow::Factory qw( FACTORY );
14 # 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 # Create a new workflow of type 'MyWorkflow'
23 my $wf = FACTORY->create_workflow( 'MyWorkflow' );
24 # 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 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 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 create_workflow( $workflow_type )
49 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 Any observers you've associated with this workflow type will be
55 attached to the returned workflow object.
56 This fires a 'create' event from the just-created workflow object. See
58 "WORKFLOWS ARE OBSERVABLE" in Workflow for more.
59 Returns: newly created workflow object.
61 fetch_workflow( $workflow_type, $workflow_id )
63 Retrieve a workflow object of type $workflow_type and ID $workflow_id.
65 (The $workflow_type is necessary so we can fetch the workflow using the
66 correct persister.) If a workflow with ID $workflow_id is not found
67 "undef" is returned.
68 Any observers you've associated with this workflow type will be
70 attached to the returned workflow object.
71 This fires a 'fetch' event from the retrieved workflow object. See
73 "WORKFLOWS ARE OBSERVABLE" in Workflow for more.
74 Throws exception if no workflow type $workflow_type available.
76 Returns: Workflow object
78 add_config_from_file( %config_declarations )
80 Pass in filenames for the various components you wish to initialize
82 using the keys 'action', 'condition', 'persister', 'validator' and
83 'workflow'. The value for each can be a single filename or an arrayref
84 of filenames.
85 The system is familiar with the 'perl' and 'xml' configuration formats
87 -- see the 'doc/configuration.txt' for what we expect as the format and
88 will autodetect the types based on the file extension of each file.
89 Just give your file the right extension and it will be read in
90 properly.
91 You may also use your own custom configuration file format -- see
93 "SUBCLASSING" in Workflow::Config for what you need to do.
94 You can also read it in yourself and add the resulting hash reference
96 directly to the factory using "add_config()". However, you need to
97 ensure the configurations are added in the proper order -- when you add
98 an 'action' configuration and reference 'validator' objects, those
99 objects should already be read in. A good order is: 'validator',
100 'condition', 'action', 'workflow'. Then just pass the resulting hash
101 references to "add_config()" using the right type and the behavior
102 should be exactly the same.
103 Returns: nothing; if we run into a problem parsing one of the files or
105 creating the objects it requires we throw a Workflow::Exception.
106 add_config( %config_hashrefs )
108 Similar to "add_config_from_file()" -- the keys may be 'action',
110 'condition', 'persister', 'validator' and/or 'workflow'. But the values
111 are the actual configuration hashrefs instead of the files holding the
112 configurations.
113 You normally will only need to call this if you are programmatically
115 creating configurations (e.g., hot-deploying a validator class
116 specified by a user) or using a custom configuration format and for
117 some reason do not want to use the built-in mechanism in
118 Workflow::Config to read it for you.
119 Returns: nothing; if we encounter an error trying to create the objects
121 referenced in a configuration we throw a Workflow::Exception.
122 Internal Methods
124 save_workflow( $workflow )
125 Stores the state and current datetime of the $workflow object. This is
127 normally called only from the Workflow "execute_action()" method.
128 This method respects transactions if the selected persister supports
130 it. Currently, the DBI-based persisters will commit the workflow
131 transaction if everything executes successfully and roll back if
132 something fails. Note that you need to manage any
133 Workflow::Persister::DBI::ExtraData transactions yourself.
134 Returns: $workflow
136 get_workflow_history( $workflow )
138 Retrieves all Workflow::History objects related to $workflow.
140 NOTE: Normal users get the history objects from the Workflow object
142 itself. Under the covers it calls this.
143 Returns: list of Workflow::History objects
145 get_action( $workflow, $action_name )
147 Retrieves the action $action_name from workflow $workflow. Note that
149 this does not do any checking as to whether the action is proper given
150 the state of $workflow or anything like that. It is mostly an internal
151 method for Workflow (which does do checking as to the propriety of the
152 action) to instantiate new actions.
153 Throws exception if no action with name $action_name available.
155 Returns: Workflow::Action object
157 get_persister( $persister_name )
159 Retrieves the persister with name $persister_name.
161 Throws exception if no persister with name $persister_name available.
163 get_condition( $condition_name )
165 Retrieves the condition with name $condition_name.
167 Throws exception if no condition with name $condition_name available.
169 get_validator( $validator_name )
171 Retrieves the validator with name $validator_name.
173 Throws exception if no validator with name $validator_name available.
175 Internal Configuration Methods
177 _add_workflow_config( @config_hashrefs )
178 Adds all configurations in @config_hashrefs to the factory. Also cycles
180 through the workflow states and creates a Workflow::State object for
181 each. These states are passed to the workflow when it is instantiated.
182 We also require any necessary observer classes and throw an exception
184 if we cannot. If successful the observers are kept around and attached
185 to a workflow in "create_workflow()" and "fetch_workflow()".
186 Returns: nothing
188 _add_action_config( @config_hashrefs )
190 Adds all configurations in @config_hashrefs to the factory, doing a
192 'require' on the class referenced in the 'class' attribute of each
193 action.
194 Throws an exception if there is no 'class' associated with an action or
196 if we cannot 'require' that class.
197 Returns: nothing
199 _add_persister_config( @config_hashrefs )
201 Adds all configurations in @config_hashrefs to the factory, doing a
203 'require' on the class referenced in the 'class' attribute of each
204 persister.
205 Throws an exception if there is no 'class' associated with a persister,
207 if we cannot 'require' that class, or if we cannot instantiate an
208 object of that class.
209 Returns: nothing
211 _add_condition_config( @config_hashrefs )
213 Adds all configurations in @config_hashrefs to the factory, doing a
215 'require' on the class referenced in the 'class' attribute of each
216 condition.
217 Throws an exception if there is no 'class' associated with a condition,
219 if we cannot 'require' that class, or if we cannot instantiate an
220 object of that class.
221 Returns: nothing
223 _add_validator_config( @config_hashrefs )
225 Adds all configurations in @config_hashrefs to the factory, doing a
227 'require' on the class referenced in the 'class' attribute of each
228 validator.
229 Throws an exception if there is no 'class' associated with a validator,
231 if we cannot 'require' that class, or if we cannot instantiate an
232 object of that class.
233 Returns: nothing
235 _commit_transaction
237 Calls the commit method in the workflow's persister.
239 Returns: nothing
241 _rollback_transaction
243 Calls the rollback method in the workflow's persister.
245 associate_observers_with_workflow
247 Add defined observers with workflow.
249 The workflow has to be provided as the single parameter accepted by
251 this method.
252 The observers added will have to be of the type relevant to the
254 workflow type.
255 new
257 The new method is a dummy constructor, since we are using a factory it
259 makes no sense to call new - and calling new will result in a
260 Workflow::Exception
261 "instance" should be called or the imported 'FACTORY' should be
263 utilized.
264
266 Implementation and Usage
267 You can subclass the factory to implement your own methods and still
268 use the useful facade of the "FACTORY" constant. For instance, the
269 implementation is typical Perl subclassing:
270 package My::Cool::Factory;
272 use strict;
274 use base qw( Workflow::Factory );
275 sub some_cool_method {
277 my ( $self ) = @_;
278 ...
279 }
280 To use your factory you can just do the typical import:
282 #!/usr/bin/perl
284 use strict;
286 use My::Cool::Factory qw( FACTORY );
287 Or you can call "instance()" directly:
289 #!/usr/bin/perl
291 use strict;
293 use My::Cool::Factory;
294 my $factory = My::Cool::Factory->instance();
296
298 Workflow
299 Workflow::Action
301 Workflow::Condition
303 Workflow::Config
305 Workflow::Persister
307 Workflow::Validator
309
311 Copyright (c) 2003-2007 Chris Winters. All rights reserved.
312 This library is free software; you can redistribute it and/or modify it
314 under the same terms as Perl itself.
315
317 Jonas B. Nielsen (jonasbn) <jonasbn@cpan.org> is the current
318 maintainer.
319 Chris Winters <chris@cwinters.com>, original author.
321perl v5.12.0 2010-05-07 Workflow::Factory(3)