#!/usr/bin/perl =head1 NAME Debconf::DbDriver - base class for debconf db drivers =cut package Debconf::DbDriver; use warnings; use strict; use Debconf::Log qw{:all}; use base 1.01; # ensure that they don't have a broken perl installation =head1 DESCRIPTION This is a base class that may be inherited from by debconf database drivers. It provides a simple interface that debconf uses to look up information related to items in the database. =cut =head1 FIELDS =over 4 =item name The name of the database. This field is required. =item readonly Set to true if this database driver is read only. Defaults to false. In the config file the literal strings "true" and "false" can be used. Internally it uses 1 and 0. =item backup Detemrines whether a backup should be made of the old version of the database or not. In the config file the literal strings "true" and "false" can be used. Internally it uses 1 and 0. =item required Tells if a database driver is required for proper operation of debconf. Required drivers can cause debconf to abort if they are not accessible. It can be useful to make remote databases non-required, so debconf is usable if connections to them go down. Defaults to true. In the config file the literal strings "true" and "false" can be used. Internally it uses 1 and 0. =item failed Tells if a database driver failed to work. If this is set the driver should begin to reject all requests. =item accept_type A regular expression indicating types of items that may be queried in this driver. Defaults to accepting all types of items. =item reject_type A regular expression indicating types of items that are rejected by this driver. =item accept_name A regular expression that is matched against item names to see if they are accepted by this driver. Defaults to accepting all item names. =item reject_name A regular expression that is matched against item names to see if they are rejected by this driver. =item root The absolute path to the root directory of the system containing the database. =back =cut # I rarely base objects on fields, but I want strong compile-time type # checking for this class of objects, and speed. use fields qw(name readonly required backup failed accept_type reject_type accept_name reject_name root); # Class data. our %drivers; =head1 METHODS =head2 new Create a new object. A hash of fields and values may be passed in to set initial state. (And you have to use this to set the name, at the very least.) =cut sub new { my Debconf::DbDriver $this=shift; unless (ref $this) { $this = fields::new($this); } # Set defaults. $this->{required}=1; $this->{readonly}=0; $this->{failed}=0; # Set fields from parameters. my %params=@_; foreach my $field (keys %params) { if ($field eq 'readonly' || $field eq 'required' || $field eq 'backup') { # Convert from true/false strings to numbers. if (lc($params{$field}) eq "true") { $this->{$field}=1; next; } elsif (lc($params{$field}) eq "false") { $this->{$field}=0; next; } } elsif ($field=~/^(accept|reject)_/) { # Internally, store these as pre-compiled regexps. $this->{$field}=qr/$params{$field}/i; } $this->{$field}=$params{$field}; } # Name is a required field. unless (exists $this->{name}) { # Set to something since error function uses this field.. $this->{name}="(unknown)"; $this->error("no name specified"); } # Register in class data. $drivers{$this->{name}} = $this; # Other initialization. $this->init; return $this; } =head2 init Called when a new object of this class is instantiated. Override to add initialization code. =cut sub init {} =head2 error(message) Rather than ever dying on errors, drivers should instead call this method to state than an error was encountered. If the driver is required, it will be a fatal error. If not, the error message will merely be displayed to the user, the driver will be marked as failed, and debconf will continue on, "dazed and confuzed". =cut sub error { my $this=shift; if ($this->{required}) { warn('DbDriver "'.$this->{name}.'":', @_); exit 1; } else { warn('DbDriver "'.$this->{name}.'" warning:', @_); } } =head2 driver(drivername) This is a class method that allows any driver to be looked up by name. If any driver with the given name exists, it is returned. =cut sub driver { my $this=shift; my $name=shift; return $drivers{$name}; } =head2 accept(itemname, [type]) Return true if this driver will accept queries for the given item. Uses the various accept_* and reject_* fields to determine this. The type field should be passed when possible, giving the type of the item. If it is not passed, the function will try to look up the type in the item's template, but that may not always work, if the template is not yet set up. =cut sub accept { my $this=shift; my $name=shift; my $type=shift; return if $this->{failed}; if ((exists $this->{accept_name} && $name !~ /$this->{accept_name}/) || (exists $this->{reject_name} && $name =~ /$this->{reject_name}/)) { debug "db $this->{name}" => "reject $name"; return; } if (exists $this->{accept_type} || exists $this->{reject_type}) { if (! defined $type || ! length $type) { my $template = Debconf::Template->get($this->getfield($name, 'template')); return 1 unless $template; # no type to act on $type=$template->type || ''; } return if exists $this->{accept_type} && $type !~ /$this->{accept_type}/; return if exists $this->{reject_type} && $type =~ /$this->{reject_type}/; } return 1; } =head2 ispassword(itemname) Returns true if the item appears to hold a password. This is pretty messy; we have to dig up its template (unless it _is_ a template). =cut sub ispassword { my $this=shift; my $item=shift; my $template=$this->getfield($item, 'template'); return unless defined $template; $template=Debconf::Template->get($template); return unless $template; my $type=$template->type || ''; return 1 if $type eq 'password'; return 0; } =head1 ABSTRACT METHODS Subclasses must implement these methods. =head2 iterator Create an object of type Debconf::Iterator that can be used to iterate over each item in the db, and return it. Each subclass must implement this method. =head2 shutdown Save the entire database state, and closes down the driver's access to the database. Each subclass must implement this method. =head2 exists(itemname) Return true if the given item exists in the database. Each subclass must implement this method. =head2 addowner(itemname, ownername, type) Register an owner for the given item. Returns the owner name, or undef if this failed. Note that adding an owner can cause a new item to spring into existance. The type field is used to tell the DbDriver what type of item is being added (the DbDriver may decide to reject some types of items). Each subclass must implement this method. =head2 removeowner(itemname, ownername) Remove an owner from a item. Returns the owner name, or undef if removal failed. If the number of owners goes to zero, the item should be removed. Each subclass must implement this method. =head2 owners(itemname) Return a list of all owners of the item. Each subclass must implement this method. =head2 getfield(itemname, fieldname) Return the given field of the given item, or undef if getting that field failed. Each subclass must implement this method. =head2 setfield(itemname, fieldname, value) Set the given field the the given value, and return the value, or undef if setting failed. Each subclass must implement this method. =head2 removefield(itemname, fieldname) Remove the given field from the given item, if it exists. This is _not_ the same as setting the field to '', instead, it removes it from the list of fields. Returns true unless removing of the field failed, when it will return undef. =head2 fields(itemname) Return the fields present in the item. Each subclass must implement this method. =head2 getflag(itemname, flagname) Return 'true' if the given flag is set for the given item, "false" if not. Each subclass must implement this method. =head2 setflag(itemname, flagname, value) Set the given flag to the given value (will be one of "true" or "false"), and return the value. Or return undef if setting failed. Each subclass must implement this method. =head2 flags(itenname) Return the flags that are present for the item. Each subclass must implement this method. =head2 getvariable(itemname, variablename) Return the value of the given variable of the given item, or undef if there is no such variable. Each subclass must implement this method. =head2 setvariable(itemname, variablename, value) Set the given variable of the given item to the value, and return the value, or undef if setting failed. Each subclass must implement this method. =head2 variables(itemname) Return the variables that exist for the item. Each subclass must implement this method. =head1 AUTHOR Joey Hess =cut 1