Workflow::Persister::DBI(3pm)

1Workflow::Persister::DBUIs(e3r)Contributed Perl DocumentWaotrikofnlow::Persister::DBI(3)
2
3
4

NAME

6       Workflow::Persister::DBI - Persist workflow and history to DBI database
7

VERSION

9       This documentation describes version 1.19 of this package
10

SYNOPSIS

12        <persister name="MainDatabase"
13                   class="Workflow::Persister::DBI"
14                   dsn="DBI:mysql:database=workflows"
15                   user="wf"
16                   password="mypass"/>
17
18        <persister name="BackupDatabase"
19                   class="Workflow::Persister::DBI"
20                   dsn="DBI:Pg:dbname=workflows"
21                   user="wf"
22                   password="mypass"
23                   date_format="%Y-%m-%d %H:%M"
24                   autocommit="0"
25                   workflow_table="wf"
26                   workflow_sequence="wf_seq"
27                   history_table="wf_history"
28                   history_sequence="wf_history_seq"/>
29

DESCRIPTION

31       Main persistence class for storing the workflow and workflow history
32       records to a DBI-accessible datasource.
33
34   Subclassing: Getting handle from elsewhere
35       A common need to create a subclass is to use a database handle created
36       with other means. For instance, OpenInteract has a central
37       configuration file for defining datasources, and the datasource will be
38       available in a predictable manner. So we can create a subclass to
39       provide the database handle on demand from the "CTX" object available
40       from everywhere. A sample implementation is below. (Note that in real
41       life we would just use SPOPS for this, but it is still a good example.)
42
43        package Workflow::Persister::DBI::OpenInteractHandle;
44
45        use strict;
46        use base qw( Workflow::Persister::DBI );
47        use OpenInteract2::Context qw( CTX );
48
49        my @FIELDS = qw( datasource_name );
50        __PACKAGE__->mk_accessors( @FIELDS );
51
52        # override parent method, assuming that we set the 'datasource'
53        # parameter in the persister declaration
54
55        sub init {
56           my ( $self, $params ) = @_;
57           $self->datasource_name( $params->{datasource} );
58           my $ds_config = CTX->lookup_datasource_config( $self->datasource_name );
59
60           # delegate the other assignment tasks to the parent class
61
62           $self->assign_generators( $ds_config->{driver_name}, $params );
63           $self->assign_tables( $params );
64        }
65
66        sub handle {
67            my ( $self ) = @_;
68            return CTX->datasource( $self->datasource_name );
69        }
70
71   Subclassing: Changing fieldnames
72       Earlier versions of Workflow used the field 'user' to record in the
73       history the user making a state change or comment. Unfortunately 'user'
74       is a reserved word in our favorite database, PostgreSQL. (Oops.) So in
75       addition to changing the field to an assuredly-unreserved word
76       (workflow_user), we made the fieldnames customizable by subclasses.
77
78       Just override either or both of the methods:
79
80       get_workflow_fields()
81
82       Return list of fields in this order:
83
84         workflow_id, type, state, last_update
85
86       get_history_fields()
87
88       Return list of fields in this order:
89
90         workflow_hist_id, workflow_id, action, description,
91         state, workflow_user, history_date
92
93       Note that we may cache the results, so don't try and do anything weird
94       like change the fieldnames based on the workflow user or something...
95

METHODS

97   Public Methods
98       All public methods are inherited from Workflow::Persister.
99
100   Private Methods
101       init( \%params )
102
103       Create a database handle from the given parameters. You are only
104       required to provide 'dsn', which is the full DBI DSN you normally use
105       as the first argument to "connect()".
106
107       You can set these parameters in your persister configuration file and
108       they will be passed to init.
109
110       You may also use:
111
112       user
113           Name of user to login with.
114
115       password
116           Password for "user" to login with.
117
118       date_format
119           Date format to use when working with the database. Accepts a format
120           string that can be processed by the DateTime module. See
121           http://search.cpan.org/~drolsky/DateTime-0.39/lib/DateTime.pm#strftime_Specifiers
122           <http://search.cpan.org/~drolsky/DateTime-0.39/lib/DateTime.pm#strftime_Specifiers>
123           for the format options.
124
125           The default is '%Y-%m-%d %H:%M' for backward compatibility.
126
127       autocommit
128           0 or 1 to turn autocommit off or on for the database handle.
129
130           Setting autocommit to off will run Workflow with transactions. If
131           there is a failure somewhere and the persister supports it,
132           Workflow will attempt to roll back all database activity in the
133           current transaction.
134
135           If you turn autocommit off, you must still commit transactions for
136           Workflow::Persister::DBI::ExtraData yourself. Also, if you are
137           sharing the database handle, you must be careful to not pass
138           control to the workflow engine with pending transactions as they
139           will be committed if the workflow actions are successful.
140
141           The default autocommit value for the database handle is on.
142
143       workflow_table
144           Table to use for persisting workflow. Default is 'workflow'.
145
146       history_table
147           Table to use for persisting workflow history. Default is
148           'workflow_history'.
149
150       You may also use parameters for the different types of ID generators.
151       See below under the "init_*_generator" for the necessary parameters for
152       your database.
153
154       In addition to creating a database handle we parse the "dsn" to see
155       what driver we are using to determine how to generate IDs. We have the
156       ability to use automatically generated IDs for PostgreSQL, MySQL, and
157       SQLite. If your database is not included a randomly generated ID will
158       be used. (Default length of 8 characters, which you can modify with a
159       "id_length" parameter.)
160
161       You can also create your own adapter for a different type of database.
162       Just check out the existing Workflow::Persister::DBI::AutoGeneratedId
163       and Workflow::Persister::DBI::SequenceId classes for examples.
164
165       assign_generators( $driver, \%params )
166
167       Given $driver and the persister parameters in "\%params", assign the
168       appropriate ID generators for both the workflow and history tables.
169
170       Returns: nothing, but assigns the object properties
171       "workflow_id_generator" and "history_id_generator".
172
173       assign_tables( \%params )
174
175       Assign the table names from "\%params" (using 'workflow_table' and
176       'history_table') or use the defaults 'workflow' and 'workflow_history'.
177
178       Returns: nothing, but assigns the object properties "workflow_table"
179       and "history_table".
180
181       init_postgres_generators( \%params )
182
183       Create ID generators for the workflow and history tables using
184       PostgreSQL sequences. You can specify the sequences used for the
185       workflow and history tables:
186
187       workflow_sequence
188           Sequence for the workflow table. Default: 'workflow_seq'
189
190       history_sequence
191           Sequence for the workflow history table. Default:
192           'workflow_history_seq'
193
194       init_mysql_generators( \%params )
195
196       Create ID generators for the workflow and history tables using the
197       MySQL 'auto_increment' type. No parameters are necessary.
198
199       init_sqlite_generators( \%params )
200
201       Create ID generators for the workflow and history tables using the
202       SQLite implicit increment. No parameters are necessary.
203
204       init_random_generators( \%params )
205
206       Create ID generators for the workflow and history tables using a random
207       set of characters. You can specify:
208
209       id_length
210           Length of character sequence to generate. Default: 8.
211
212       init_oracle_generators
213
214       Create ID generators for the workflow and history tables using the
215       Oracle sequences. No parameters are necessary.
216
217       create_workflow
218
219       Serializes a workflow into the persistance entity configured by our
220       workflow.
221
222       Takes a single parameter: a workflow object
223
224       Returns a single value, a id for unique identification of out
225       serialized workflow for possible deserialization.
226
227       fetch_workflow
228
229       Deserializes a workflow from the persistance entity configured by our
230       workflow.
231
232       Takes a single parameter: the unique id assigned to our workflow upon
233       serialization (see "create_workflow").
234
235       Returns a hashref consisting of two keys:
236
237       ·   state, the workflows current state
238
239       ·   last_update, date indicating last update
240
241       update_workflow
242
243       Updates a serialized workflow in the persistance entity configured by
244       our workflow.
245
246       Takes a single parameter: a workflow object
247
248       Returns: Nothing
249
250       create_history
251
252       Serializes history records associated with a workflow object
253
254       Takes two parameters: a workflow object and an array of workflow
255       history objects
256
257       Returns: provided array of workflow history objects upon success
258
259       fetch_history
260
261       Deserializes history records associated with a workflow object
262
263       Takes a single parameter: a workflow object
264
265       Returns an array of workflow history objects upon success
266
267       commit_transaction ( $wf )
268
269       Commit the transaction for a workflow if autocommit is not enabled.
270
271       Returns nothing
272
273       rollback_transaction
274
275       Rollsback the transaction for a workflow if autocommit is not enabled.
276
277       Returns nothing
278

COPYRIGHT

286       Copyright (c) 2003-2007 Chris Winters. All rights reserved.
287
288       This library is free software; you can redistribute it and/or modify it
289       under the same terms as Perl itself.
290

AUTHORS

292       Jonas B. Nielsen (jonasbn) <jonasbn@cpan.org> is the current
293       maintainer.
294
295       Chris Winters <chris@cwinters.com>, original author.
296
297
298
299perl v5.12.0                      2010-05-07       Workflow::Persister::DBI(3)