Workflow::Factory - Generates new workflow and supporting objects |
instance()
Workflow::Factory - Generates new workflow and supporting objects
# Import the singleton for easy access use Workflow::Factory qw( FACTORY ); # Add XML configurations to the factory FACTORY->add_config_from_file( workflow => 'workflow.xml', action => [ 'myactions.xml', 'otheractions.xml' ], validator => [ 'validator.xml', 'myvalidators.xml' ], condition => 'condition.xml', persister => 'persister.xml' ); # Create a new workflow of type 'MyWorkflow' my $wf = FACTORY->create_workflow( 'MyWorkflow' ); # Fetch an existing workflow with ID '25' my $wf = FACTORY->fetch_workflow( 'MyWorkflow', 25 );
The Workflow Factory is your primary interface to the workflow system. You give it the configuration files and/or data structures for the Workflow, the Workflow::Action manpage, the Workflow::Condition manpage, the Workflow::Persister manpage, and the Workflow::Validator manpage objects and then you ask it for new and existing Workflow objects.
Developers using the workflow system should be familiar with how the factory processes configurations and how it makes the various components of the system are instantiated and stored in the factory.
instance()
The factory is a singleton, this is how you get access to the instance. You can also just import the 'FACTORY' constant as in the SYNOPSIS.
Create a new workflow of type $workflow_type
. This will create a
new record in whatever persistence mechanism you have associated with
$workflow_type
and set the workflow to its initial state.
Any observers you've associated with this workflow type will be attached to the returned workflow object.
This fires a 'create' event from the just-created workflow object. See
WORKFLOWS ARE OBSERVABLE
in Workflow for more.
Returns: newly created workflow object.
Retrieve a workflow object of type $workflow_type
and ID
$workflow_id
. (The $workflow_type
is necessary so we can fetch
the workflow using the correct persister.) If a workflow with ID
$workflow_id
is not found undef
is returned.
Any observers you've associated with this workflow type will be attached to the returned workflow object.
This fires a 'fetch' event from the retrieved workflow object. See
WORKFLOWS ARE OBSERVABLE
in Workflow for more.
Throws exception if no workflow type $workflow_type
available.
Returns: Workflow object
Pass in filenames for the various components you wish to initialize using the keys 'action', 'condition', 'persister', 'validator' and 'workflow'. The value for each can be a single filename or an arrayref of filenames.
The system is familiar with the 'perl' and 'xml' configuration formats -- see the 'doc/configuration.txt' for what we expect as the format and will autodetect the types based on the file extension of each file. Just give your file the right extension and it will be read in properly.
You may also use your own custom configuration file format -- see
SUBCLASSING
in the Workflow::Config manpage for what you need to do.
You can also read it in yourself and add the resulting hash reference
directly to the factory using add_config()
. However, you need to
ensure the configurations are added in the proper order -- when you
add an 'action' configuration and reference 'validator' objects, those
objects should already be read in. A good order is: 'validator',
'condition', 'action', 'workflow'. Then just pass the resulting hash
references to add_config()
using the right type and the behavior
should be exactly the same.
Returns: nothing; if we run into a problem parsing one of the files or creating the objects it requires we throw a the Workflow::Exception manpage.
Similar to add_config_from_file()
-- the keys may be 'action',
'condition', 'persister', 'validator' and/or 'workflow'. But the
values are the actual configuration hashrefs instead of the files
holding the configurations.
You normally will only need to call this if you are programmatically creating configurations (e.g., hot-deploying a validator class specified by a user) or using a custom configuration format and for some reason do not want to use the built-in mechanism in the Workflow::Config manpage to read it for you.
Returns: nothing; if we encounter an error trying to create the objects referenced in a configuration we throw a the Workflow::Exception manpage.
Stores the state and current datetime of the $workflow
object. This
is normally called only from the Workflow execute_action()
method.
Returns: $workflow
Retrieves all the Workflow::History manpage objects related to $workflow
.
NOTE: Normal users get the history objects from the Workflow object itself. Under the covers it calls this.
Returns: list of the Workflow::History manpage objects
Retrieves the action $action_name
from workflow $workflow
. Note
that this does not do any checking as to whether the action is proper
given the state of $workflow
or anything like that. It is mostly an
internal method for Workflow (which does do checking as to the
propriety of the action) to instantiate new actions.
Throws exception if no action with name $action_name
available.
Returns: the Workflow::Action manpage object
Retrieves the persister with name $persister_name
.
Throws exception if no persister with name $persister_name
available.
Retrieves the condition with name $condition_name
.
Throws exception if no condition with name $condition_name
available.
Retrieves the validator with name $validator_name
.
Throws exception if no validator with name $validator_name
available.
Adds all configurations in @config_hashrefs
to the factory. Also
cycles through the workflow states and creates a the Workflow::State manpage
object for each. These states are passed to the workflow when it is
instantiated.
We also require any necessary observer classes and throw an exception if we cannot. If successful the observers are kept around and attached to a workflow in create_workflow() and fetch_workflow().
Returns: nothing
Adds all configurations in @config_hashrefs
to the factory, doing a
'require' on the class referenced in the 'class' attribute of each
action.
Throws an exception if there is no 'class' associated with an action or if we cannot 'require' that class.
Returns: nothing
Adds all configurations in @config_hashrefs
to the factory, doing a
'require' on the class referenced in the 'class' attribute of each
persister.
Throws an exception if there is no 'class' associated with a persister, if we cannot 'require' that class, or if we cannot instantiate an object of that class.
Returns: nothing
Adds all configurations in @config_hashrefs
to the factory, doing a
'require' on the class referenced in the 'class' attribute of each
condition.
Throws an exception if there is no 'class' associated with a condition, if we cannot 'require' that class, or if we cannot instantiate an object of that class.
Returns: nothing
Adds all configurations in @config_hashrefs
to the factory, doing a
'require' on the class referenced in the 'class' attribute of each
validator.
Throws an exception if there is no 'class' associated with a validator, if we cannot 'require' that class, or if we cannot instantiate an object of that class.
Returns: nothing
Add defined observers with workflow.
The workflow has to be provided as the single parameter accepted by this method.
The observers added will have to be of the type relevant to the workflow type.
=head3 new
The new method is a dummy constructor, since we are using a factory it makes no sense to call new - and calling new will result in a the Workflow::Exception manpage
instance should be called or the imported 'FACTORY' should be utilized.
You can subclass the factory to implement your own methods and still
use the useful facade of the FACTORY
constant. For instance, the
implementation is typical Perl subclassing:
package My::Cool::Factory; use strict; use base qw( Workflow::Factory ); sub some_cool_method { my ( $self ) = @_; ... }
To use your factory you can just do the typical import:
#!/usr/bin/perl use strict; use My::Cool::Factory qw( FACTORY );
Or you can call instance()
directly:
#!/usr/bin/perl use strict; use My::Cool::Factory; my $factory = My::Cool::Factory->instance();
Workflow
the Workflow::Condition manpage
the Workflow::Persister manpage
the Workflow::Validator manpage
Copyright (c) 2003-2007 Chris Winters. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Jonas B. Nielsen (jonasbn) <jonasbn@cpan.org> is the current maintainer.
Chris Winters <chris@cwinters.com>, original author.
Workflow::Factory - Generates new workflow and supporting objects |