Debian Codegraph @

Debconf/DbDriver.pm

raw
1 #!/usr/bin/perl
2
3 =head1 NAME
4
5 Debconf::DbDriver - base class for debconf db drivers
6
7 =cut
8
9 package Debconf::DbDriver;
10 use warnings;
11 use strict;
12 use Debconf::Log qw{:all};
13 use base 1.01; # ensure that they don't have a broken perl installation
14
15 =head1 DESCRIPTION
16
17 This is a base class that may be inherited from by debconf database
18 drivers. It provides a simple interface that debconf uses to look up
19 information related to items in the database.
20
21 =cut
22
23 =head1 FIELDS
24
25 =over 4
26
27 =item name
28
29 The name of the database. This field is required.
30
31 =item readonly
32
33 Set to true if this database driver is read only. Defaults to false.
34
35 In the config file the literal strings "true" and "false" can be used.
36 Internally it uses 1 and 0.
37
38 =item backup
39
40 Detemrines whether a backup should be made of the old version of the
41 database or not.
42
43 In the config file the literal strings "true" and "false" can be used.
44 Internally it uses 1 and 0.
45
46 =item required
47
48 Tells if a database driver is required for proper operation of
49 debconf. Required drivers can cause debconf to abort if they are not
50 accessible. It can be useful to make remote databases non-required, so
51 debconf is usable if connections to them go down. Defaults to true.
52
53 In the config file the literal strings "true" and "false" can be used.
54 Internally it uses 1 and 0.
55
56 =item failed
57
58 Tells if a database driver failed to work. If this is set the driver should
59 begin to reject all requests.
60
61 =item accept_type
62
63 A regular expression indicating types of items that may be queried in this
64 driver. Defaults to accepting all types of items.
65
66 =item reject_type
67
68 A regular expression indicating types of items that are rejected by this
69 driver.
70
71 =item accept_name
72
73 A regular expression that is matched against item names to see if they are
74 accepted by this driver. Defaults to accepting all item names.
75
76 =item reject_name
77
78 A regular expression that is matched against item names to see if they are
79 rejected by this driver.
80
81 =item root
82
83 The absolute path to the root directory of the system containing the database.
84
85 =back
86
87 =cut
88
89 # I rarely base objects on fields, but I want strong compile-time type
90 # checking for this class of objects, and speed.
91 use fields qw(name readonly required backup failed
92 accept_type reject_type accept_name reject_name root);
93
94 # Class data.
95 our %drivers;
96
97 =head1 METHODS
98
99 =head2 new
100
101 Create a new object. A hash of fields and values may be passed in to set
102 initial state. (And you have to use this to set the name, at the very
103 least.)
104
105 =cut
106
107 sub new {
108 my Debconf::DbDriver $this=shift;
109 unless (ref $this) {
110 $this = fields::new($this);
111 }
112 # Set defaults.
113 $this->{required}=1;
114 $this->{readonly}=0;
115 $this->{failed}=0;
116 # Set fields from parameters.
117 my %params=@_;
118 foreach my $field (keys %params) {
119 if ($field eq 'readonly' || $field eq 'required' || $field eq 'backup') {
120 # Convert from true/false strings to numbers.
121 if (lc($params{$field}) eq "true") {
122 $this->{$field}=1;
123 next;
124 } elsif (lc($params{$field}) eq "false") {
125 $this->{$field}=0;
126 next;
127 }
128 }
129 elsif ($field=~/^(accept|reject)_/) {
130 # Internally, store these as pre-compiled regexps.
131 $this->{$field}=qr/$params{$field}/i;
132 }
133 $this->{$field}=$params{$field};
134 }
135 # Name is a required field.
136 unless (exists $this->{name}) {
137 # Set to something since error function uses this field..
138 $this->{name}="(unknown)";
139 $this->error("no name specified");
140 }
141 # Register in class data.
142 $drivers{$this->{name}} = $this;
143 # Other initialization.
144 $this->init;
145 return $this;
146 }
147
148 =head2 init
149
150 Called when a new object of this class is instantiated. Override to
151 add initialization code.
152
153 =cut
154
155 sub init {}
156
157 =head2 error(message)
158
159 Rather than ever dying on errors, drivers should instead call
160 this method to state than an error was encountered. If the driver is
161 required, it will be a fatal error. If not, the error message will merely
162 be displayed to the user, the driver will be marked as failed, and debconf
163 will continue on, "dazed and confuzed".
164
165 =cut
166
167 sub error {
168 my $this=shift;
169
170 if ($this->{required}) {
171 warn('DbDriver "'.$this->{name}.'":', @_);
172 exit 1;
173 }
174 else {
175 warn('DbDriver "'.$this->{name}.'" warning:', @_);
176 }
177 }
178
179 =head2 driver(drivername)
180
181 This is a class method that allows any driver to be looked up by name.
182 If any driver with the given name exists, it is returned.
183
184 =cut
185
186 sub driver {
187 my $this=shift;
188 my $name=shift;
189
190 return $drivers{$name};
191 }
192
193 =head2 accept(itemname, [type])
194
195 Return true if this driver will accept queries for the given item. Uses the
196 various accept_* and reject_* fields to determine this.
197
198 The type field should be passed when possible, giving the type of the item.
199 If it is not passed, the function will try to look up the type in the item's
200 template, but that may not always work, if the template is not yet set up.
201
202 =cut
203
204 sub accept {
205 my $this=shift;
206 my $name=shift;
207 my $type=shift;
208
209 return if $this->{failed};
210
211 if ((exists $this->{accept_name} && $name !~ /$this->{accept_name}/) ||
212 (exists $this->{reject_name} && $name =~ /$this->{reject_name}/)) {
213 debug "db $this->{name}" => "reject $name";
214 return;
215 }
216
217 if (exists $this->{accept_type} || exists $this->{reject_type}) {
218 if (! defined $type || ! length $type) {
219 my $template = Debconf::Template->get($this->getfield($name, 'template'));
220 return 1 unless $template; # no type to act on
221 $type=$template->type || '';
222 }
223 return if exists $this->{accept_type} && $type !~ /$this->{accept_type}/;
224 return if exists $this->{reject_type} && $type =~ /$this->{reject_type}/;
225 }
226
227 return 1;
228 }
229
230 =head2 ispassword(itemname)
231
232 Returns true if the item appears to hold a password. This is pretty messy;
233 we have to dig up its template (unless it _is_ a template).
234
235 =cut
236
237 sub ispassword {
238 my $this=shift;
239 my $item=shift;
240
241 my $template=$this->getfield($item, 'template');
242 return unless defined $template;
243 $template=Debconf::Template->get($template);
244 return unless $template;
245 my $type=$template->type || '';
246 return 1 if $type eq 'password';
247 return 0;
248 }
249
250 =head1 ABSTRACT METHODS
251
252 Subclasses must implement these methods.
253
254 =head2 iterator
255
256 Create an object of type Debconf::Iterator that can be used to iterate over
257 each item in the db, and return it.
258
259 Each subclass must implement this method.
260
261 =head2 shutdown
262
263 Save the entire database state, and closes down the driver's access to the
264 database.
265
266 Each subclass must implement this method.
267
268 =head2 exists(itemname)
269
270 Return true if the given item exists in the database.
271
272 Each subclass must implement this method.
273
274 =head2 addowner(itemname, ownername, type)
275
276 Register an owner for the given item. Returns the owner name, or undef
277 if this failed.
278
279 Note that adding an owner can cause a new item to spring into
280 existance.
281
282 The type field is used to tell the DbDriver what type of item is
283 being added (the DbDriver may decide to reject some types of items).
284
285 Each subclass must implement this method.
286
287 =head2 removeowner(itemname, ownername)
288
289 Remove an owner from a item. Returns the owner name, or undef if
290 removal failed. If the number of owners goes to zero, the item should
291 be removed.
292
293 Each subclass must implement this method.
294
295 =head2 owners(itemname)
296
297 Return a list of all owners of the item.
298
299 Each subclass must implement this method.
300
301 =head2 getfield(itemname, fieldname)
302
303 Return the given field of the given item, or undef if getting that
304 field failed.
305
306 Each subclass must implement this method.
307
308 =head2 setfield(itemname, fieldname, value)
309
310 Set the given field the the given value, and return the value, or undef if
311 setting failed.
312
313 Each subclass must implement this method.
314
315 =head2 removefield(itemname, fieldname)
316
317 Remove the given field from the given item, if it exists. This is _not_ the
318 same as setting the field to '', instead, it removes it from the list of
319 fields. Returns true unless removing of the field failed, when it will
320 return undef.
321
322 =head2 fields(itemname)
323
324 Return the fields present in the item.
325
326 Each subclass must implement this method.
327
328 =head2 getflag(itemname, flagname)
329
330 Return 'true' if the given flag is set for the given item, "false" if
331 not.
332
333 Each subclass must implement this method.
334
335 =head2 setflag(itemname, flagname, value)
336
337 Set the given flag to the given value (will be one of "true" or "false"),
338 and return the value. Or return undef if setting failed.
339
340 Each subclass must implement this method.
341
342 =head2 flags(itenname)
343
344 Return the flags that are present for the item.
345
346 Each subclass must implement this method.
347
348 =head2 getvariable(itemname, variablename)
349
350 Return the value of the given variable of the given item, or undef if
351 there is no such variable.
352
353 Each subclass must implement this method.
354
355 =head2 setvariable(itemname, variablename, value)
356
357 Set the given variable of the given item to the value, and return the
358 value, or undef if setting failed.
359
360 Each subclass must implement this method.
361
362 =head2 variables(itemname)
363
364 Return the variables that exist for the item.
365
366 Each subclass must implement this method.
367
368 =head1 AUTHOR
369
370 Joey Hess <[email protected]>
371
372 =cut
373
374 1