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

COPYRIGHT

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

AUTHORS

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