1Workflow::Factory(3) User Contributed Perl Documentation Workflow::Factory(3)
2
6 Workflow::Factory - Generates new workflow and supporting objects
7
9 # Import the singleton for easy access
10 use Workflow::Factory qw( FACTORY );
11 # Add XML configurations to the factory
13 FACTORY->add_config_from_file( workflow => 'workflow.xml',
14 action => [ 'myactions.xml', 'otheractions.xml' ],
15 validator => [ 'validator.xml', 'myvalidators.xml' ],
16 condition => 'condition.xml',
17 persister => 'persister.xml' );
18 # Create a new workflow of type 'MyWorkflow'
20 my $wf = FACTORY->create_workflow( 'MyWorkflow' );
21 # Fetch an existing workflow with ID '25'
23 my $wf = FACTORY->fetch_workflow( 'MyWorkflow', 25 );
24
26 Public
27 The Workflow Factory is your primary interface to the workflow system.
29 You give it the configuration files and/or data structures for the
30 Workflow, Workflow::Action, Workflow::Condition, Workflow::Persister,
31 and Workflow::Validator objects and then you ask it for new and exist‐
32 ing Workflow objects.
33 Internal
35 Developers using the workflow system should be familiar with how the
37 factory processes configurations and how it makes the various compo‐
38 nents of the system are instantiated and stored in the factory.
39
41 Public Methods
42 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 prop‐
90 erly.
91 You may also use your own custom configuration file format -- see "SUB‐
93 CLASSING" 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', 'con‐
100 dition', 'action', 'workflow'. Then just pass the resulting hash refer‐
101 ences to "add_config()" using the right type and the behavior should be
102 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', 'con‐
110 dition', 'persister', 'validator' and/or 'workflow'. But the values are
111 the actual configuration hashrefs instead of the files holding the con‐
112 figurations.
113 You normally will only need to call this if you are programmatically
115 creating configurations (e.g., hot-deploying a validator class speci‐
116 fied by a user) or using a custom configuration format and for some
117 reason do not want to use the built-in mechanism in Workflow::Config to
118 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 )
126 Stores the state and current datetime of the $workflow object. This is
128 normally called only from the Workflow "execute_action()" method.
129 Returns: $workflow
131 get_workflow_history( $workflow )
133 Retrieves all Workflow::History objects related to $workflow.
135 NOTE: Normal users get the history objects from the Workflow object
137 itself. Under the covers it calls this.
138 Returns: list of Workflow::History objects
140 get_action( $workflow, $action_name )
142 Retrieves the action $action_name from workflow $workflow. Note that
144 this does not do any checking as to whether the action is proper given
145 the state of $workflow or anything like that. It is mostly an internal
146 method for Workflow (which does do checking as to the propriety of the
147 action) to instantiate new actions.
148 Throws exception if no action with name $action_name available.
150 Returns: Workflow::Action object
152 get_persister( $persister_name )
154 Retrieves the persister with name $persister_name.
156 Throws exception if no persister with name $persister_name available.
158 get_condition( $condition_name )
160 Retrieves the condition with name $condition_name.
162 Throws exception if no condition with name $condition_name available.
164 get_validator( $validator_name )
166 Retrieves the validator with name $validator_name.
168 Throws exception if no validator with name $validator_name available.
170 Internal Configuration Methods
172 _add_workflow_config( @config_hashrefs )
174 Adds all configurations in @config_hashrefs to the factory. Also cycles
176 through the workflow states and creates a Workflow::State object for
177 each. These states are passed to the workflow when it is instantiated.
178 We also require any necessary observer classes and throw an exception
180 if we cannot. If successful the observers are kept around and attached
181 to a workflow in create_workflow() and fetch_workflow().
182 Returns: nothing
184 _add_action_config( @config_hashrefs )
186 Adds all configurations in @config_hashrefs to the factory, doing a
188 'require' on the class referenced in the 'class' attribute of each
189 action.
190 Throws an exception if there is no 'class' associated with an action or
192 if we cannot 'require' that class.
193 Returns: nothing
195 _add_persister_config( @config_hashrefs )
197 Adds all configurations in @config_hashrefs to the factory, doing a
199 'require' on the class referenced in the 'class' attribute of each per‐
200 sister.
201 Throws an exception if there is no 'class' associated with a persister,
203 if we cannot 'require' that class, or if we cannot instantiate an
204 object of that class.
205 Returns: nothing
207 _add_condition_config( @config_hashrefs )
209 Adds all configurations in @config_hashrefs to the factory, doing a
211 'require' on the class referenced in the 'class' attribute of each con‐
212 dition.
213 Throws an exception if there is no 'class' associated with a condition,
215 if we cannot 'require' that class, or if we cannot instantiate an
216 object of that class.
217 Returns: nothing
219 _add_validator_config( @config_hashrefs )
221 Adds all configurations in @config_hashrefs to the factory, doing a
223 'require' on the class referenced in the 'class' attribute of each val‐
224 idator.
225 Throws an exception if there is no 'class' associated with a validator,
227 if we cannot 'require' that class, or if we cannot instantiate an
228 object of that class.
229 Returns: nothing
231 #=head3 associate_observers_with_workflow
233 #=head3 new
235
237 Implementation and Usage
238 You can subclass the factory to implement your own methods and still
240 use the useful facade of the "FACTORY" constant. For instance, the
241 implementation is typical Perl subclassing:
242 package My::Cool::Factory;
244 use strict;
246 use base qw( Workflow::Factory );
247 sub some_cool_method {
249 my ( $self ) = @_;
250 ...
251 }
252 To use your factory you can just do the typical import:
254 #!/usr/bin/perl
256 use strict;
258 use My::Cool::Factory qw( FACTORY );
259 Or you can call "instance()" directly:
261 #!/usr/bin/perl
263 use strict;
265 use My::Cool::Factory;
266 my $factory = My::Cool::Factory->instance();
268
270 Workflow
271 Workflow::Action
273 Workflow::Condition
275 Workflow::Config
277 Workflow::Persister
279 Workflow::Validator
281
283 Copyright (c) 2003-2006 Chris Winters. All rights reserved.
284 This library is free software; you can redistribute it and/or modify it
286 under the same terms as Perl itself.
287
289 Jonas B. Nielsen (jonasbn) <jonasbn@cpan.org> is the current main‐
290 tainer.
291 Chris Winters <chris@cwinters.com>, original author.
293perl v5.8.8 2007-04-25 Workflow::Factory(3)