SIAM/Driver/Simple.pm

filter: Statementstmt 79.0% 189 / 239 Branchbran 75.7% 53 / 70 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 79.1% 19 / 24 Podpod 100% 15 / 15 totaltotal 79.3% 276 / 348 CC 46 SCAR 16.3
CC
46
Cov
78%
fetch_computable
8.5
_retrieve_object_data
8.0
_import_object
7.5
CRAP 5.1
« SIAM/DeviceComponent.pm ↑ Summary SIAM/Object.pm »
1 package SIAM::Driver::Simple;
2  
3 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 3 ▶use YAML ();
Subroutine BEGIN: called CC=1 SCAR=0.0
7 3 ▶use Log::Handler;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 3 ▶use Digest::MD5 ();
Subroutine BEGIN: called CC=1 SCAR=0.0
9 3 ▶use File::stat;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 =head1 NAME
12  
13  
14 SIAM::Driver::Simple - a reference implementation of SIAM Driver
15  
16  
17 =cut
18  
19  
20 =head1 SYNOPSIS
21  
22 The driver does not connect to any external databases. Instead, it reads
23 all the SIAM objects from its YAML data file.
24  
25 The top level element in the data file is expected to be an array of
26 objects that are contained in the SIAM root. The following object
27 classes are expected to be contained by the root object:
28  
29 =over 4
30  
31 =item * SIAM::Contract
32  
33 =item * SIAM::AccessScope
34  
35 =item * SIAM::User
36  
37 =item * SIAM::Device
38  
39 =item * SIAM::Attribute
40  
41 =back
42  
43 Each object definition may have an entry with the key C<_contains_>
44 which points to an array of contained objects. For example, an
45 C<SIAM::Contract> object is expected to contain one or more
46 C<SIAM::Service> objects.
47  
48 If a key starts with C<_compute_>, it represents a computable for a
49 given object.
50  
51 All other keys in the object entry define the object attributes. The
52 values are expected to be strings and numbers. The data file should
53 define all the attributes, including C<siam.object.id> and
54 C<siam.object.class>.
55  
56 See the file I<t/driver-simple.data.yaml> in SIAM package distribution
57 for reference.
58  
59  
60 =head1 MANDATORY METHODS
61  
62 The following methods are required by C<SIAM::Documentation::DriverSpec>.
63  
64  
65 =head2 new
66  
67 Instantiates a new driver object. The method expects a hashref
68 containing the attributes, as follows:
69  
70 =over 4
71  
72 =item * Logger
73  
74 The logger object is supplied by SIAM.
75  
76 =item * Datafile
77  
78 Full path of the YAML data file which defines all the objects for this driver.
79  
80 =back
81  
82 =cut
83  
84 sub new
85 1 ▶{
Subroutine new: called CC=5 SCAR=17.8
Pod documented
86 1 my $class = shift;
87 1 my $drvopts = shift;
88  
89 1 my $self = {};
90 1 bless $self, $class;
91  
92 1 $self->{'logger'} = $drvopts->{'Logger'};
93 die('Logger is not supplied to the driver')
94 1 ▶ unless defined($self->{'logger'});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"logger"} 0 1 1
95
96 1 foreach my $param ('Datafile')
97 {
98 1 ▶ if( not defined($drvopts->{$param}) )
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $drvopts->{$param}) 0 1 1
99 {
100 0 $self->error('Missing mandatiry parameter ' . $param .
101 ' in SIAM::Driver::Simple->new()');
102 0 return undef;
103 }
104 }
105  
106 1 $self->{'datafile'} = $drvopts->{'Datafile'};
107
108 1 ▶ if( not -r $self->{'datafile'} )
Branch: 1 branch
BranchTrueFalseTotal
unless (-r $self->{"datafile"}) 0 1 1
109 {
110 0 $self->error('Data file is not readable: ' . $self->{'datafile'});
111 0 return undef;
112 }
113
114 1 return $self;
115 }
116  
117  
118 =head2 connect
119  
120 Reads the YAML data file
121  
122 =cut
123  
124 sub connect
125 1 ▶{
Subroutine connect: called CC=4 SCAR=14.3
Pod documented
126 1 my $self = shift;
127  
128 $self->debug('Connecting SIAM::Driver::Simple driver to data file: ' .
129 1 $self->{'datafile'});
130  
131 1 my $st = stat($self->{'datafile'});
132 1 $self->{'datafile_lastmod'} = $st->mtime();
133
134 1 my $data = eval { YAML::LoadFile($self->{'datafile'}) };
135 1 ▶ if( $@ )
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 1 1
136 {
137 $self->error('Cannot load YAML data from ' .
138 0 $self->{'datafile'} . ': ' . $@);
139 0 return undef;
140 }
141
142 1 ▶ if( ref($data) ne 'ARRAY' )
Branch: 1 branch
BranchTrueFalseTotal
if (ref $data ne "ARRAY") 0 1 1
143 {
144 0 $self->error('Top level is not a sequence in ' . $self->{'datafile'});
145 0 return undef;
146 }
147  
148 1 $self->{'objects'} = {};
149 1 $self->{'cont_attr_index'} = {};
150 1 $self->{'attr_index'} = {};
151 1 $self->{'contains'} = {};
152 1 $self->{'container'} = {};
153 1 $self->{'data_ready'} = 1;
154 1 $self->{'computable_cache'} = {};
155
156 1 foreach my $obj (@{$data})
157 {
158 21 $self->_import_object($obj, 'SIAM.ROOT');
159 }
160
161 1 return $self->{'data_ready'};
162 }
163  
164 # recursively import the objects
165  
166 sub _import_object
167 59 ▶{
Subroutine _import_object: called CC=7 SCAR=20.1
168 59 my $self = shift;
169 59 my $obj = shift;
170 59 my $container_id = shift;
171  
172 59 my $id = $obj->{'siam.object.id'};
173 59 ▶ if( not defined($id) )
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $id) 0 59 59
174 {
175 0 $self->error($container_id .
176 ' contains an object without "siam.object.id"' );
177 0 $self->{'data_ready'} = 0;
178 0 return;
179 }
180  
181 59 my $class = $obj->{'siam.object.class'};
182 59 ▶ if( not defined($class) )
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $class) 0 59 59
183 {
184 0 $self->error('Object ' . $id . ' does not have "siam.object.class"' );
185 0 $self->{'data_ready'} = 0;
186 0 return;
187 }
188
189 # duplicate all attributes except "_contains_"
190  
191 59 my $dup = {};
192 59 ▶ while( my ($key, $val) = each %{$obj} )
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %{$obj;}) 317 59 376
193 {
194 317 ▶ if( $key ne '_contains_' )
Branch: 1 branch
BranchTrueFalseTotal
if ($key ne "_contains_") 298 19 317
195 {
196 298 $dup->{$key} = $val;
197 $self->{'cont_attr_index'}{$class}{$container_id}{
198 298 $key}{$val}{$id} = 1;
199 298 $self->{'attr_index'}{$class}{$key}{$val}{$id} = 1;
200 }
201 }
202
203 59 $self->{'objects'}{$id} = $dup;
204 59 $self->{'contains'}{$container_id}{$class}{$id} = 1;
205 59 $self->{'container'}{$id} = $container_id;
206
207 59 ▶ if( defined($obj->{'_contains_'}) )
Branch: 1 branch
BranchTrueFalseTotal
if (defined $obj->{"_contains_"}) 19 40 59
208 {
209 19 foreach my $contained_obj (@{$obj->{'_contains_'}})
210 {
211 38 $self->_import_object($contained_obj, $id);
212 }
213 }
214 }
215  
216  
217 =head2 disconnect
218  
219 Disconnects the driver from its underlying databases.
220  
221 =cut
222  
223 sub disconnect
224 0 ▶{
Subroutine disconnect: not called CC=1 SCAR=6.9
Pod documented
225 0 my $self = shift;
226
227 0 delete $self->{'objects'};
228 0 delete $self->{'attr_index'};
229 0 delete $self->{'cont_attr_index'};
230 0 delete $self->{'contains'};
231 0 delete $self->{'container'};
232 0 delete $self->{'computable_cache'};
233 0 $self->{'data_ready'} = 0;
234 }
235  
236  
237 =head2 fetch_attributes
238  
239 $status = $driver->fetch_attributes($attrs);
240  
241 Retrieve the object by ID and populate the hash with object attributes.
242  
243 =cut
244  
245 sub fetch_attributes
246 114 ▶{
Subroutine fetch_attributes: called CC=5 SCAR=17.1
Pod documented
247 114 my $self = shift;
248 114 my $obj = shift;
249  
250 114 my $id = $obj->{'siam.object.id'};
251 114 ▶ if( not defined($id) )
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $id) 0 114 114
252 {
253 0 $self->error('siam.object.id is not specified in fetch_attributes' );
254 0 return undef;
255 }
256
257 114 ▶ if( not defined($self->{'objects'}{$id}) )
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $self->{"objects"}{$id}) 0 114 114
258 {
259 0 $self->error('Object not found: ' . $id );
260 0 return undef;
261 }
262  
263 114 ▶ while( my($key, $val) = each %{$self->{'objects'}{$id}} )
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %{$$self{"objects"}{$id};}) 559 114 673
264 {
265 559 ▶ if( $key !~ /^_compute_/o )
Branch: 1 branch
BranchTrueFalseTotal
unless ($key =~ /^_compute_/o) 557 2 559
266 {
267 557 $obj->{$key} = $val;
268 }
269 }
270
271 114 return 1;
272 }
273
274  
275 =head2 fetch_computable
276  
277 $value = $driver->fetch_computable($id, $key);
278  
279 Retrieve a computable. Return empty string if unsupported.
280  
281 =cut
282  
283 sub fetch_computable
284 3 ▶{
Subroutine fetch_computable: called CC=7 SCAR=21.4
Pod documented
285 3 my $self = shift;
286 3 my $id = shift;
287 3 my $key = shift;
288  
289 3 my $obj = $self->{'objects'}{$id};
290 3 ▶ if( not defined($obj) )
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $obj) 0 3 3
291 {
292 0 $self->error('Object not found: ' . $id );
293 0 return undef;
294 }
295  
296 3 ▶ if( $key eq 'siam.contract.content_md5hash' )
Branch: 1 branch
BranchTrueFalseTotal
if ($key eq 'siam.contract.content_md5hash') { } 2 1 3
297 {
298 2 ▶ if( $obj->{'siam.object.class'} eq 'SIAM::Contract' )
Branch: 1 branch
BranchTrueFalseTotal
if ($obj->{"siam.object.class"} eq "SIAM::Contract") 2 0 2
299 {
300 2 my $st = stat($self->{'datafile'});
301 2 ▶ if( $st->mtime() != $self->{'datafile_lastmod'} )
Branch: 2 branches
BranchTrueFalseTotal
if ($st->mtime != $self->{'datafile_lastmod'}) { } 0 2 2
elsif (defined $self->{'computable_cache'}{$key}) { } 0 2 2
302 {
303 0 $self->disconnect();
304 0 $self->connect();
305 }
306 elsif( defined($self->{'computable_cache'}{$key}) )
307 {
308 0 return $self->{'computable_cache'}{$key};
309 }
310
311 2 my $md5 = new Digest::MD5;
312 2 $self->_object_content_md5($id, $md5);
313 2 my $ret = $md5->hexdigest();
314 2 $self->{'computable_cache'}{$key} = $ret;
315 2 return $ret;
316 }
317 }
318 else
319 {
320 1 my $val = $self->{'objects'}{$id}{'_compute_' . $key};
321 1 ▶ if( defined($val) )
Branch: 1 branch
BranchTrueFalseTotal
if (defined $val) 1 0 1
322 {
323 1 return $val;
324 }
325 }
326
327 0 return '';
328 }
329
330  
331 # recursively add all contained objects for MD5 calculation
332 sub _object_content_md5
333 20 ▶{
Subroutine _object_content_md5: called CC=5 SCAR=16.1
334 20 my $self = shift;
335 20 my $id = shift;
336 20 my $md5 = shift;
337  
338 20 my $obj = $self->{'objects'}{$id};
339
340 20 foreach my $attr (sort keys %{$obj})
341 {
342 141 $md5->add('#' . $attr . '//' . $obj->{$attr} . '#');
343 }
344  
345 20 ▶ if( defined($self->{'contains'}{$id}) )
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->{"contains"}{$id}) 12 8 20
346 {
347 12 foreach my $class (sort keys %{$self->{'contains'}{$id}})
348 {
349 14 foreach my $contained_id (sort
350 14 keys %{$self->{'contains'}{$id}{$class}})
351 {
352 18 $self->_object_content_md5($contained_id, $md5);
353 }
354 }
355 }
356 }
357
358  
359  
360 =head2 fetch_contained_object_ids
361  
362 $ids = $driver->fetch_contained_object_ids($id, 'SIAM::Contract', {
363 'match_attribute' => [ 'siam.object.access_scope_id',
364 ['SCOPEID01', 'SCOPEID02'] ]
365 }
366 );
367  
368 Retrieve the contained object IDs.
369  
370 =cut
371  
372 sub fetch_contained_object_ids
373 55 ▶{
Subroutine fetch_contained_object_ids: called CC=5 SCAR=16.1
Pod documented
374 55 my $self = shift;
375 55 my $container_id = shift;
376 55 my $class = shift;
377 55 my $options = shift;
378  
379 55 my $ret = [];
380  
381 55 ▶ if( defined($options) )
Branch: 1 branch
BranchTrueFalseTotal
if (defined $options) 20 35 55
382 {
383 20 ▶ if( defined($options->{'match_attribute'}) )
Branch: 1 branch
BranchTrueFalseTotal
if (defined $options->{"match_attribute"}) 20 0 20
384 {
385 20 my ($filter_attr, $filter_val) = @{$options->{'match_attribute'}};
386
387 20 foreach my $val (@{$filter_val})
388 {
389 20 push(@{$ret},
390 20 keys %{$self->{'cont_attr_index'}{$class}{$container_id}{
391 20 $filter_attr}{$val}});
392 }
393  
394 20 return $ret;
395 }
396 }
397
398 35 ▶ if( defined($self->{'contains'}{$container_id}{$class}) )
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->{"contains"}{$container_id}{$class}) 35 0 35
399 {
400 35 push(@{$ret}, keys %{$self->{'contains'}{$container_id}{$class}});
401 }
402  
403 35 return $ret;
404 }
405  
406  
407  
408 =head2 fetch_contained_classes
409  
410 $classes = $driver->fetch_contained_classes($id);
411  
412 Returns arrayref with class names.
413  
414 =cut
415  
416 sub fetch_contained_classes
417 60 ▶{
Subroutine fetch_contained_classes: called CC=3 SCAR=11.0
Pod documented
418 60 my $self = shift;
419 60 my $id = shift;
420  
421 60 my $ret = [];
422 60 ▶ if( defined($self->{'contains'}{$id}) )
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->{"contains"}{$id}) 20 40 60
423 {
424 20 foreach my $class (sort keys %{$self->{'contains'}{$id}})
425 {
426 25 push(@{$ret}, $class);
427 }
428 }
429 60 return $ret;
430 }
431  
432  
433 =head2 fetch_container
434  
435 $attr = $driver->fetch_container($id);
436  
437 Retrieve the container ID and class.
438  
439 =cut
440  
441 sub fetch_container
442 2 ▶{
Subroutine fetch_container: called CC=3 SCAR=11.1
Pod documented
443 2 my $self = shift;
444 2 my $id = shift;
445  
446 2 my $container_id = $self->{'container'}{$id};
447 2 ▶ if( not defined($container_id) )
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $container_id) 0 2 2
448 {
449 0 return undef;
450 }
451  
452 2 my $ret = {'siam.object.id' => $container_id};
453 2 ▶ if( $container_id ne 'SIAM.ROOT' )
Branch: 1 branch
BranchTrueFalseTotal
if ($container_id ne "SIAM.ROOT") 1 1 2
454 {
455 $ret->{'siam.object.class'} =
456 1 $self->{'objects'}{$container_id}{'siam.object.class'};
457 }
458
459 2 return $ret;
460 }
461  
462  
463 =head2 fetch_object_ids_by_attribute
464  
465 $list = $driver->fetch_object_ids_by_attribute($classname, $attr, $value);
466  
467 Returns a list of object IDs which match the attribute value.
468  
469 =cut
470  
471 sub fetch_object_ids_by_attribute
472 0 ▶{
Subroutine fetch_object_ids_by_attribute: not called CC=1 SCAR=6.9
Pod documented
473 0 my $self = shift;
474 0 my $class = shift;
475 0 my $attr = shift;
476 0 my $value = shift;
477  
478 0 return [keys %{$self->{'attr_index'}{$class}{$attr}{$value}}];
479 }
480
481  
482  
483 =head2 set_condition
484  
485 The method does nothing in this driver, but only issues a debug message.
486  
487 =cut
488  
489 sub set_condition
490 0 ▶{
Subroutine set_condition: not called CC=1 SCAR=6.9
Pod documented
491 0 my $self = shift;
492 0 my $id = shift;
493 0 my $key = shift;
494 0 my $value = shift;
495  
496 0 $self->debug('set_condition is called for ' . $id . ': (' .
497 $key . ', ' . $value . ')');
498 }
499  
500  
501 =head2 manifest_attributes
502  
503 The method returns an arrayref with all known attribute names.
504  
505 =cut
506  
507 sub manifest_attributes
508 1 ▶{
Subroutine manifest_attributes: called CC=4 SCAR=13.9
Pod documented
509 1 my $self = shift;
510  
511 # avoid duplicates and skip siam.* attributes
512 1 my %manifest;
513 1 ▶ while(my ($class, $r1) = each %{$self->{'attr_index'}})
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %{$$self{"attr_index"};}) 12 1 13
514 {
515 12 ▶ while(my ($attr, $r2) = each %{$r1})
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %{$r1;}) 77 12 89
516 {
517 77 ▶ if( $attr !~ /^siam\./o )
Branch: 1 branch
BranchTrueFalseTotal
unless ($attr =~ /^siam\./o) 20 57 77
518 {
519 20 $manifest{$attr} = 1;
520 }
521 }
522 }
523  
524 1 return [keys %manifest];
525 }
526  
527  
528  
529  
530 =head1 ADDITIONAL METHODS
531  
532 The following methods are not in the Specification.
533  
534  
535 =head2 debug
536  
537 Prints a debug message to the logger.
538  
539 =cut
540  
541 sub debug
542 1 ▶{
Subroutine debug: called CC=1 SCAR=0.0
Pod documented
543 1 my $self = shift;
544 1 my $msg = shift;
545 1 $self->{'logger'}->debug($msg);
546 }
547  
548  
549 =head2 error
550  
551 Prints an error message to the logger.
552  
553 =cut
554  
555 sub error
556 0 ▶{
Subroutine error: not called CC=1 SCAR=6.9
Pod documented
557 0 my $self = shift;
558 0 my $msg = shift;
559 0 $self->{'logger'}->error($msg);
560 }
561  
562  
563 =head2 object_exists
564  
565 Takes an object ID and returns true if such object is present in the database.
566  
567 =cut
568  
569 sub object_exists
570 0 ▶{
Subroutine object_exists: not called CC=1 SCAR=6.9
Pod documented
571 0 my $self = shift;
572 0 my $id = shift;
573 0 return defined($self->{'objects'}{$id});
574 }
575  
576  
577 =head2 clone_data
578  
579 $data = SIAM::Driver::Simple->clone_data($siam, $callback);
580  
581 The method takes a SIAM object and a callback reference. It walks
582 through the SIAM data and produces a clone suitable for
583 storing into a YAML file and re-using with C<SIAM::Driver::Simple>.
584  
585 The callback is a sub reference which is supplied with the object ID as
586 an argument. Only the objects which result in true value are being
587 cloned.
588  
589 The method is usable for producing a test data out of productive system.
590  
591 =cut
592  
593 sub clone_data
594 1 ▶{
Subroutine clone_data: called CC=1 SCAR=0.0
Pod documented
595 1 my $class = shift;
596 1 my $siam = shift;
597 1 my $filter_callback = shift;
598  
599 1 return $class->_retrieve_object_data($siam, $filter_callback);
600 }
601  
602 # recursively walk the objects
603
604 sub _retrieve_object_data
605 50 ▶{
Subroutine _retrieve_object_data: called CC=8 SCAR=20.8
606 50 my $class = shift;
607 50 my $obj = shift;
608 50 my $filter_callback = shift;
609  
610 50 my $ret = {};
611  
612 50 ▶ if( not $obj->is_root() )
Branch: 1 branch
BranchTrueFalseTotal
unless ($obj->is_root) 49 1 50
613 {
614 49 my $attrs = $obj->attributes();
615 49 ▶ while(my($key, $val) = each %{$attrs})
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %{$attrs;}) 326 49 375
616 {
617 326 $ret->{$key} = $val;
618 }
619 }
620  
621 50 my $contained_data = [];
622 50 my $classes = $obj->_driver->fetch_contained_classes($obj->id);
623 50 foreach my $objclass ( @{$classes} )
624 {
625 18 my $objects = $obj->get_contained_objects($objclass);
626 18 foreach my $contained_obj (@{$objects})
627 {
628 50 ▶ if( &{$filter_callback}($contained_obj) )
Branch: 1 branch
BranchTrueFalseTotal
if (&{$filter_callback;}($contained_obj)) 49 1 50
629 {
630 49 push(@{$contained_data},
631 $class->_retrieve_object_data($contained_obj,
632 $filter_callback));
633 }
634 }
635 }
636  
637 50 ▶ if( $obj->is_root() )
Branch: 1 branch
BranchTrueFalseTotal
if ($obj->is_root) 1 49 50
638 {
639 1 return $contained_data;
640 }
641
642 49 ▶ if( scalar(@{$contained_data}) > 0 )
Branch: 1 branch
BranchTrueFalseTotal
if (scalar @{$contained_data;} > 0) 13 36 49
643 {
644 13 $ret->{'_contains_'} = $contained_data;
645 }
646  
647 49 return $ret;
648 }
649
650  
651  
652  
653 =head1 SEE ALSO
654  
655 L<SIAM::Documentation::DriverSpec>, L<YAML>, L<Log::Handler>
656  
657 =cut
658  
659 3 1;
660  
661 # Local Variables:
662 # mode: cperl
663 # indent-tabs-mode: nil
664 # cperl-indent-level: 4
665 # cperl-continued-statement-offset: 4
666 # cperl-continued-brace-offset: -4
667 # cperl-brace-offset: 0
668 # cperl-label-offset: -2
669 # End:
« SIAM/DeviceComponent.pm ↑ Summary SIAM/Object.pm »