1 package SL::DB::RequirementSpec;
6 use List::Util qw(max reduce);
7 use Rose::DB::Object::Helpers;
9 use SL::DB::MetaSetup::RequirementSpec;
10 use SL::DB::Manager::RequirementSpec;
11 use SL::Locale::String;
12 use SL::Util qw(_hashify);
14 __PACKAGE__->meta->add_relationship(
16 type => 'one to many',
17 class => 'SL::DB::RequirementSpecItem',
18 column_map => { id => 'requirement_spec_id' },
21 type => 'one to many',
22 class => 'SL::DB::RequirementSpecTextBlock',
23 column_map => { id => 'requirement_spec_id' },
26 type => 'one to many',
27 class => 'SL::DB::RequirementSpec',
28 column_map => { id => 'working_copy_id' },
32 __PACKAGE__->meta->initialize;
34 __PACKAGE__->before_save('_before_save_initialize_not_null_columns');
40 push @errors, t8('The title is missing.') if !$self->title;
45 sub _before_save_initialize_not_null_columns {
48 $self->previous_section_number(0) if !defined $self->previous_section_number;
49 $self->previous_fb_number(0) if !defined $self->previous_fb_number;
54 sub text_blocks_sorted {
55 my ($self, %params) = _hashify(1, @_);
57 my @text_blocks = @{ $self->text_blocks };
58 @text_blocks = grep { $_->output_position == $params{output_position} } @text_blocks if exists $params{output_position};
59 @text_blocks = sort { $a->position <=> $b->position } @text_blocks;
61 return wantarray ? @text_blocks : \@text_blocks;
65 my ($self, @rest) = @_;
67 croak "This sub is not a writer" if @rest;
69 my @sections = sort { $a->position <=> $b->position } grep { !$_->parent_id } @{ $self->items };
70 return wantarray ? @sections : \@sections;
73 sub sections { §ions_sorted; }
75 sub displayable_name {
78 return sprintf('%s: "%s"', $self->type->description, $self->title);
81 sub versioned_copies_sorted {
82 my ($self, %params) = _hashify(1, @_);
84 my @copies = @{ $self->versioned_copies };
85 @copies = grep { $_->version->version_number <= $params{max_version_number} } @copies if $params{max_version_number};
86 @copies = sort { $a->version->version_number <=> $b->version->version_number } @copies;
88 return wantarray ? @copies : \@copies;
92 my ($self, %params) = @_;
94 return $self->_create_copy(%params) if $self->db->in_transaction;
97 if (!$self->db->do_transaction(sub { $copy = $self->_create_copy(%params) })) {
98 $::lxdebug->message(LXDebug->WARN(), "create_copy failed: " . join("\n", (split(/\n/, $self->db->error))[0..2]));
106 my ($self, %params) = @_;
108 my $copy = Rose::DB::Object::Helpers::clone_and_reset($self);
109 $copy->copy_from($self, %params);
115 my ($self, $source, %attributes) = @_;
117 croak "Missing parameter 'source'" unless $source;
120 $self->assign_attributes(map({ ($_ => $source->$_) } qw(type_id status_id customer_id project_id title hourly_rate net_sum previous_section_number previous_fb_number is_template)),
124 $self->text_blocks(map { Rose::DB::Object::Helpers::clone_and_reset($_) } @{ $source->text_blocks });
126 # Save new object -- we need its ID for the items.
135 my $cloned = Rose::DB::Object::Helpers::clone_and_reset($item);
136 $cloned->requirement_spec_id($self->id);
137 $cloned->children(map { $clone_item->($_) } @{ $item->children });
139 $id_to_clone{ $item->id } = $cloned;
144 $self->items(map { $clone_item->($_) } @{ $source->sections });
146 # Save the items -- need to do that before setting dependencies.
150 foreach my $item (@{ $source->items }) {
151 next unless @{ $item->dependencies };
152 $id_to_clone{ $item->id }->update_attributes(dependencies => [ map { $id_to_clone{$_->id} } @{ $item->dependencies } ]);
155 $self->update_attributes(%attributes);
161 my ($self, $source, %attributes) = @_;
163 $self->db->with_transaction(sub { $self->_copy_from($source, %attributes); });
166 sub highest_version {
169 return reduce { $a->version->version_number > $b->version->version_number ? $a : $b } @{ $self->versioned_copies };
172 sub is_working_copy {
175 return !$self->working_copy_id;
178 sub next_version_number {
181 return max(0, map { $_->version->version_number } @{ $self->versioned_copies }) + 1;
185 my ($self, %attributes) = @_;
187 croak "Cannot work on a versioned copy" if $self->working_copy_id;
189 my ($copy, $version);
190 my $ok = $self->db->with_transaction(sub {
191 delete $attributes{version_number};
193 $version = SL::DB::RequirementSpecVersion->new(%attributes, version_number => $self->next_version_number)->save;
194 $copy = $self->create_copy;
195 $copy->update_attributes(version_id => $version->id, working_copy_id => $self->id);
196 $self->update_attributes(version_id => $version->id);
201 return $ok ? ($copy, $version) : ();
204 sub invalidate_version {
205 my ($self, %params) = @_;
207 croak "Cannot work on a versioned copy" if $self->working_copy_id;
209 return if !$self->id || !$self->version_id;
210 $self->update_attributes(version_id => undef);
222 SL::DB::RequirementSpec - RDBO model for requirement specs
226 The database structure behind requirement specs is a bit involved. The
227 important thing is how working copy/versions are handled.
229 The table contains three important columns: C<id> (which is also the
230 primary key), C<working_copy_id> and C<version_id>. C<working_copy_id>
231 is a self-referencing column: it can be C<NULL>, but if it isn't then
232 it contains another requirement spec C<id>. C<version_id> on the other
233 hand references the table C<requirement_spec_versions>.
235 The design is as follows:
239 =item * The user is always working on a working copy. The working copy
240 is identified in the database by having C<working_copy_id> set to
243 =item * All other entries in this table are referred to as I<versioned
244 copies>. A versioned copy is a copy of a working frozen at the moment
245 in time it was created. Each versioned copy refers back to the working
246 copy it belongs to: each has its C<working_copy_id> set.
248 =item * Each versioned copy must reference an entry in the table
249 C<requirement_spec_versions>. Meaning: for each versioned copy
250 C<version_id> must not be C<NULL>.
252 =item * Directly after creating a versioned copy even the working copy
253 itself points to a certain version via its C<version_id> column: to
254 the same version that the versioned copy just created points
255 to. However, any modification that will be visible to the customer
256 (text, positioning etc but not internal things like time/cost
257 estimation changes) will cause the working copy to be set to 'no
258 version' again. This is achieved via before save hooks in Perl.
262 =head1 DATABASE TRIGGERS AND CHECKS
264 Several database triggers and consistency checks exist that manage
265 requirement specs, their items and their dependencies. These are
266 described here instead of in the individual files for the other RDBO
271 When you delete a requirement spec all of its dependencies (items,
272 text blocks, versions etc.) are deleted by triggers.
274 When you delete an item (either a section or a (sub-)function block)
275 all of its children will be deleted as well. This will trigger the
276 same trigger resulting in a recursive deletion with the bottom-most
277 items being deleted first. Their item dependencies are deleted as
282 Whenever you update a requirement spec item a trigger will fire that
283 will update the parent's C<time_estimation> column. This also happens
284 when an item is deleted or updated.
286 =head2 CONSISTENCY CHECKS
288 Several consistency checks are applied to requirement spec items:
292 =item * Column C<requirement_spec_item.item_type> can only contain one of
293 the values C<section>, C<function-block> or C<sub-function-block>.
295 =item * Column C<requirement_spec_item.parent_id> must be C<NULL> if
296 C<requirement_spec_item.item_type> is set to C<section> and C<NOT
305 =item C<copy_from $source, %attributes>
307 Copies everything (basic attributes like type/title/customer, items,
308 text blocks, time/cost estimation) save for the versions from the
309 other requirement spec object C<$source> into C<$self> and saves
310 it. This is done within a transaction.
312 C<%attributes> are attributes that are assigned to C<$self> after all
313 the basic attributes from C<$source> have been assigned.
315 This function can be used for resetting a working copy to a specific
318 my $requirement_spec = SL::DB::RequirementSpec->new(id => $::form->{id})->load;
319 my $versioned_copy = SL::DB::RequirementSpec->new(id => $::form->{versioned_copy_id})->load;
321 $requirement_spec->copy_from(
323 version_id => $versioned_copy->version_id,
328 Creates and returns a copy of C<$self>. The copy is already
329 saved. Creating the copy happens within a transaction.
331 =item C<create_version %attributes>
333 Prerequisites: C<$self> must be a working copy (see L</working_copy>),
334 not a versioned copy.
336 This function creates a new version for C<$self>. This involves
341 =item 1. The next version number is calculated using
342 L</next_version_number>.
344 =item 2. An instance of L<SL::DB::RequirementSpecVersion> is
345 created. Its attributes are copied from C<%attributes> save for the
346 version number which is taken from step 1.
348 =item 3. A copy of C<$self> is created with L</create_copy>.
350 =item 4. The version instance created in step is assigned to the copy
353 =item 5. The C<version_id> in C<$self> is set to the copy's ID from
358 All this is done within a transaction.
360 In case of success a two-element list is returned consisting of the
361 copy & version objects created in steps 3 and 2 respectively. In case
362 of a failure an empty list will be returned.
364 =item C<displayable_name>
366 Returns a human-readable name for this instance consisting of the type
369 =item C<highest_version>
371 Given a working copy C<$self> this function returns the versioned copy
372 of C<$self> with the highest version number. If such a version exist
373 its instance is returned. Otherwise C<undef> is returned.
375 This can be used for calculating the difference between the working
376 copy and the last version created for it.
378 =item C<invalidate_version>
380 Prerequisites: C<$self> must be a working copy (see L</working_copy>),
381 not a versioned copy.
383 Sets the C<version_id> field to C<undef> and saves C<$self>.
385 =item C<is_working_copy>
387 Returns trueish if C<$self> is a working copy and not a versioned
388 copy. The condition for this is that C<working_copy_id> is C<undef>.
390 =item C<next_version_number>
392 Calculates and returns the next version number for this requirement
393 spec. Version numbers start at 1 and are incremented by one for each
394 version created for it, no matter whether or not it has been reverted
395 to a previous version since. It boils down to this pseudo-code:
397 if (has_never_had_a_version)
400 return max(version_number for all versions for this requirement spec) + 1
404 An alias for L</sections_sorted>.
406 =item C<sections_sorted>
408 Returns a list of requirement spec items that
410 This is not a writer. Use the C<items> relationship for that.
412 =item C<text_blocks_sorted %params>
414 Returns an array (or an array reference depending on context) of text
415 blocks sorted by their positional column in ascending order. If the
416 C<output_position> parameter is given then only the text blocks
417 belonging to that C<output_position> are returned.
421 Validate values before saving. Returns list or human-readable error
424 =item C<versioned_copies_sorted %params>
426 Returns an array (or an array reference depending on context) of
427 versioned copies sorted by their version number in ascending order. If
428 the C<max_version_number> parameter is given then only the versioned
429 copies whose version number is less than or equal to
430 C<max_version_number> are returned.
440 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>