eBox uses GConf to store its configuration, the development framework provides a wrapper around the original perl bindings. GConf gives us an easy API for storing and retrieving typed configuration values organized hierarchically. It also lets us define limited schemas for certain configuration keys, setting their type and default values.
The development framework defines a wrapper around the GConf API
that provides some extra features. The wrapper is implemented as child
class for EBox::Module, so all modules that want
to use GConf inherit from EBox::GConfModule. Its
children automatically get these features:
Automatic backups: the first time a key's value is changed,
a backup of the configuration tree for the whole module is made.
When the configuration is saved, the backup is automatically
deleted, when the configuration changes are revoked the backup is
automatically restored. EBox::GConfModule
implements the makeBackup,
restoreBackup and
revokeConfig methods
defined in EBox::Module, so
EBox::GConfModule children do not need to
implement them unless they have really special requirements or
store part of their configuration outside of GConf.
Error handling: GConf errors are handled by the wrapper class, it translates them into internal exceptions.
Read-only and read-write instances: when the module is instantiated in read-only mode, the wrapper class uses a copy of the configuration to avoid seeing unsaved changes. It also prevents calls to methods that write to GConf.
Namespace boundary checks: the wrapper checks all gconf keys used by the module to see if they are in its namespace. This ensures that the keys for a module are only directly read or written to by the module itself (as long as all modules use the wrapper class).
Relative pathnames: methods in the wrapper class take both absolute and relative pathnames for gconf keys. The root of a module's namespace changes depending on the type of instance (read-only of read-write) and the type of key (normal or status) being accessed. For this reason it is best to use relative pathnames when calling the wrapper class methods, they translate the relative path to an absolute one automatically.
Status namespace: the is certain information that's not
given by the user and needs to be written at any time, even by
read-only instances. This kind of information is not subject to
configuration saving and revoking. It is status information,
like the name servers or IP address given to the system by an
external DHCP server. A separate namespace is provided for this
kind of information, and again it is automatically kept out of the
backup/save/revoke operations mentioned earlier. The methods use to
access this namespace are identical to the usual ones, they just
have the prefix st_ in their names.
Recursive retrieval of directories: there are two
methods in EBox::GConfModule that
allow easy retrievals of whole directory structures.
hash_from_dir takes a directory as
an argument and returns a hash with all the keys under it.
array_from_dir takes a directory as
an argument and returns an array of hashes as returned by
hash_from_dir for each one of its
subdirectories.
This is a list of the most important methods in
EBox::GConfModule:
all_dirsGiven a key it returns all directories within.
all_dirs_baseGiven a key it returns all directories within, removing any leading directory component.
all_entriesGiven a key it returns all entries within. Entries are all those keys which are not directories, hence they contain a value.
all_entries_baseGiven a key it returns all entries within, removing any leading directory component. Entries are all those keys which are not directories, hence they contain a value.
array_from_dirGiven a key it returns an array using a hash reference to
contain in each element the directories under the key. Also, the
hash contains the key _dir which tells
you the directory's name.
dir_existsGiven a key referencing a directory it returns
true if it exists.
get_boolReturns the value of a boolean key.
get_intReturns the value of a integer key.
get_listReturns an array containing the list referenced by the key.
get_stringReturns the value of a string key.
get_unique_idIt generates a unique random identifier with a leading
prefix in the root of the module's
namespace, if directory is passed, it will
be added to the path. Note that it does not create the entry, it
just returns a unique identifier, so it is up to you to create
the proper entry.
hash_from_dirIt returns a hash containing all the entries in the directory referenced by the key.
isReadOnlyIt returns true if the current
EBox::GConfModule instance you are
accessing is read-only.
makeBackupIt dumps your current configuration to file.
restoreBackupIt restores the last backup.
revokeConfigAll changes done since your first write or delete will be dismissed.
set_boolIt sets a key with a boolean
value.
set_intIt sets a key with an integer
value.
set_listIt sets a list of
typevalues in
value.
set_stringIt sets values of
type in key.
Let's see some examples from the above functions.
Example 3.5. Getting and using a unique identifier
my $id = $self->get_unique_id('p', 'printers');
$self->set_string("printers/$id/name", $name);
$self->set_bool("printers/$id/configured", undef);