From 27b19f7804d23c2ef4c2fd38e0134cdfadae0987 Mon Sep 17 00:00:00 2001 From: Oliver Tappe Date: Thu, 2 Aug 2007 20:41:16 +0000 Subject: * added POD to ConfigDB, and did some fixes along the way git-svn-id: http://svn.openslx.org/svn/openslx/trunk@1306 95ad53e4-c205-0410-b2fa-d234c58c8868 --- config-db/OpenSLX/ConfigDB.pm | 1664 +++++++++++++++++++++++++++++++++++++-- config-db/OpenSLX/MetaDB/DBI.pm | 6 +- 2 files changed, 1582 insertions(+), 88 deletions(-) (limited to 'config-db') diff --git a/config-db/OpenSLX/ConfigDB.pm b/config-db/OpenSLX/ConfigDB.pm index 13aee505..85ac7113 100644 --- a/config-db/OpenSLX/ConfigDB.pm +++ b/config-db/OpenSLX/ConfigDB.pm @@ -19,19 +19,66 @@ $VERSION = 1; # API-version use Exporter; @ISA = qw(Exporter); -################################################################################ -### This module defines the data abstraction layer for the OpenSLX configuration -### database. -### Aim of this abstraction is to hide the details of the data layout and -### the peculiarities of individual database types behind a simple interface -### that offers straightforward access to and manipulation of the -### OpenSLX-systems and -clients (without the need to use SQL). -### The interface is divided into four parts: -### - data access methods (getting data) -### - data manipulation methods (adding, removing and changing data) -### - data aggregation methods (combining data in ways useful for apps) -### - support methods -################################################################################ +=pod + +=head1 NAME + +OpenSLX::ConfigDB - the configuration database API class for OpenSLX + +=head1 SYNOPSIS + + use OpenSLX::ConfigDB; + + openslxInit(); + + my $openslxDB = OpenSLX::ConfigDB->new(); + $openslxDB->connect(); + + # fetch a client by name: + my $defaultClient = $openslxDB->fetchClientByFilter({'name' => '<<>>'}) + + # fetch all systems: + my @systems = $openslxDB->fetchSystemByFilter(); + +=head1 DESCRIPTION + +This class defines the OpenSLX API to the config database (the data layer to +the outside world). + +The ConfigDB interface contains of five different parts: + +=over + +=item - L (connection handling) + +=item - L (getting data) + +=item - L (adding, removing and changing data) + +=item - L (getting info about the resulting +configurations after mixing individual client-, group- and system- +configurations). + +=item - L (useful helpers) + +=back + +=head1 Special Concepts + +=over + +=item C + +A filter is a hash-ref defining the filter criteria to be applied to a database +query. Each key of the filter corresponds to a DB column and the (hash-)value +contains the respective column value. + +[At a later stage, this will be improved to support a more structured approach +to filtering (with boolean operators and hierarchical expressions)]. + +=back + +=cut my @supportExports = qw( isAttribute mergeAttributes pushAttributes @@ -48,11 +95,25 @@ use OpenSLX::Utils; our $configDBInstance; -################################################################################ -### data access interface -################################################################################ +=head1 Methods + +=head2 Basic Methods + +=over + +=cut + +=item C + +Returns an object representing a database handle to the config database. +N.B. this class is implemented as a singleton, so several successive calls to +new will return the *same* object + +=cut + sub new -{ +{ # TODO: it would be better to allow new() to do what any caller expects and + # rename this to instance() or anything similar ... my $class = shift; if ($configDBInstance) { @@ -68,10 +129,35 @@ sub new sub DESTROY { my $self = shift; - + $configDBInstance = undef; } +=item C + +Tries to establish a connection to the database specified via the db-... +settings. +The global configuration hash C<%openslxConfig> contains further info about the +requested connection. When implementing this method, you may have to look at +the following entries in order to find out which database to connect to: + +=over + +=item C<$openslxConfig{'db-spec'}> + +Full specification of database, a special string defining the +precise database to connect to (this allows connecting to a database +that requires specifications which aren't cared for by the existing +C<%config>-entries). + +=item C<$openslxConfig{'db-name'}> + +The precise name of the database that should be connected (defaults to 'openslx'). + +=back + +=cut + sub connect ## no critic (ProhibitBuiltinHomonyms) { my $self = shift; @@ -83,7 +169,7 @@ sub connect ## no critic (ProhibitBuiltinHomonyms) my $dbType = $openslxConfig{'db-type'}; # name of underlying database module... - + my $dbModuleName = "OpenSLX/MetaDB/$dbType.pm"; my $dbModule = "OpenSLX::MetaDB::$dbType"; unless (eval { require $dbModuleName } ) { @@ -109,21 +195,27 @@ sub connect ## no critic (ProhibitBuiltinHomonyms) die _tr( 'Please use slxsettings if you want to switch to another db-type.'); } - + $self->{'db-type'} = $dbType; $self->{'meta-db'} = $metaDB; foreach my $tk (keys %{$DbSchema->{tables}}) { $metaDB->schemaDeclareTable($tk, $DbSchema->{tables}->{$tk}); } - + _checkAndUpgradeDBSchemaIfNecessary($metaDB); } $self->{connectedCount}++; - + return; } +=item C + +Tears down the connection to the database and cleans up. + +=cut + sub disconnect { my $self = shift; @@ -136,30 +228,79 @@ sub disconnect return; } -sub start_transaction +=item C + +Opens a database transaction - most useful if you want to make sure a couple of changes +apply as a whole or not at all. + +=cut + +sub startTransaction { my $self = shift; - $self->{'meta-db'}->start_transaction(); + $self->{'meta-db'}->startTransaction(); return; } -sub commit_transaction +=item C + +Commits a database transaction - so all changes done inside of this transaction will +be applied to the database. + +=cut + +sub commitTransaction { my $self = shift; - $self->{'meta-db'}->commit_transaction(); + $self->{'meta-db'}->commitTransaction(); return; } -sub rollback_transaction +=item C + +Revokes a database transaction - so all changes done inside of this transaction will +be undone. + +=cut + +sub rollbackTransaction { my $self = shift; - $self->{'meta-db'}->rollback_transaction(); + $self->{'meta-db'}->rollbackTransaction(); return; } +=head2 Data Access Methods + +=over + +=item C + +Fetches and returns information about all vendor-OSes that match the given +filter. + +=over + +=item Param C + +A hash-ref containing the filter criteria that shall be applied - default +is no filtering. See L for more info. + +=item Param C + +A string listing the columns that shall be returned - default is all columns. + +=item Return Value + +An array of hash-refs containing the resulting data rows. + +=back + +=cut + sub fetchVendorOSByFilter { my $self = shift; @@ -171,6 +312,28 @@ sub fetchVendorOSByFilter return wantarray() ? @vendorOS : shift @vendorOS; } +=item C + +Fetches and returns information the vendor-OSes with the given IDs. + +=over + +=item Param C + +An array of the vendor-OS-IDs you are interested in. + +=item Param C + +A string listing the columns that shall be returned - default is all columns. + +=item Return Value + +An array of hash-refs containing the resulting data rows. + +=back + +=cut + sub fetchVendorOSByID { my $self = shift; @@ -181,6 +344,30 @@ sub fetchVendorOSByID return wantarray() ? @vendorOS : shift @vendorOS; } +=item C + +Fetches and returns information about all exports that match the given +filter. + +=over + +=item Param C + +A hash-ref containing the filter criteria that shall be applied - default +is no filtering. See L for more info. + +=item Param C + +A string listing the columns that shall be returned - default is all columns. + +=item Return Value + +An array of hash-refs containing the resulting data rows. + +=back + +=cut + sub fetchExportByFilter { my $self = shift; @@ -191,6 +378,28 @@ sub fetchExportByFilter return wantarray() ? @exports : shift @exports; } +=item C + +Fetches and returns information the exports with the given IDs. + +=over + +=item Param C + +An array of the export-IDs you are interested in. + +=item Param C + +A string listing the columns that shall be returned - default is all columns. + +=item Return Value + +An array of hash-refs containing the resulting data rows. + +=back + +=cut + sub fetchExportByID { my $self = shift; @@ -201,6 +410,24 @@ sub fetchExportByID return wantarray() ? @exports : shift @exports; } +=item C + +Fetches the IDs of all exports that make use of the vendor-OS with the given ID. + +=over + +=item Param C + +ID of the vendor-OS whose exports shall be returned. + +=item Return Value + +An array of system-IDs. + +=back + +=cut + sub fetchExportIDsOfVendorOS { my $self = shift; @@ -209,6 +436,24 @@ sub fetchExportIDsOfVendorOS return $self->{'meta-db'}->fetchExportIDsOfVendorOS($vendorOSID); } +=item C + +Fetches the global info element specified by the given ID. + +=over + +=item Param C + +The name of the global info value you are interested in. + +=item Return Value + +The value of the requested global info. + +=back + +=cut + sub fetchGlobalInfo { my $self = shift; @@ -217,6 +462,30 @@ sub fetchGlobalInfo return $self->{'meta-db'}->fetchGlobalInfo($id); } +=item C + +Fetches and returns information about all systems that match the given filter. + +=over + +=item Param C<$filter> + +A hash-ref containing the filter criteria that shall be applied - default +is no filtering. See L for more info. + +=item Param C<$resultCols> [Optional] + +A comma-separated list of colunm names that shall be returned. If not defined, +all available data must be returned. + +=item Return Value + +An array of hash-refs containing the resulting data rows. + +=back + +=cut + sub fetchSystemByFilter { my $self = shift; @@ -227,6 +496,28 @@ sub fetchSystemByFilter return wantarray() ? @systems : shift @systems; } +=item C + +Fetches and returns information the systems with the given IDs. + +=over + +=item Param C + +An array of the system-IDs you are interested in. + +=item Param C + +A string listing the columns that shall be returned - default is all columns. + +=item Return Value + +An array of hash-refs containing the resulting data rows. + +=back + +=cut + sub fetchSystemByID { my $self = shift; @@ -237,6 +528,24 @@ sub fetchSystemByID return wantarray() ? @systems : shift @systems; } +=item C + +Fetches the IDs of all systems that make use of the export with the given ID. + +=over + +=item Param C + +ID of the export whose systems shall be returned. + +=item Return Value + +An array of system-IDs. + +=back + +=cut + sub fetchSystemIDsOfExport { my $self = shift; @@ -245,6 +554,25 @@ sub fetchSystemIDsOfExport return $self->{'meta-db'}->fetchSystemIDsOfExport($exportID); } +=item C + +Fetches the IDs of all systems that are used by the client with the given +ID. + +=over + +=item Param C + +ID of the client whose systems shall be returned. + +=item Return Value + +An array of system-IDs. + +=back + +=cut + sub fetchSystemIDsOfClient { my $self = shift; @@ -253,6 +581,25 @@ sub fetchSystemIDsOfClient return $self->{'meta-db'}->fetchSystemIDsOfClient($clientID); } +=item C + +Fetches the IDs of all systems that are part of the group with the given +ID. + +=over + +=item Param C + +ID of the group whose systems shall be returned. + +=item Return Value + +An array of system-IDs. + +=back + +=cut + sub fetchSystemIDsOfGroup { my $self = shift; @@ -261,6 +608,30 @@ sub fetchSystemIDsOfGroup return $self->{'meta-db'}->fetchSystemIDsOfGroup($groupID); } +=item C + +Fetches and returns information about all clients that match the given filter. + +=over + +=item Param C<$filter> + +A hash-ref containing the filter criteria that shall be applied - default +is no filtering. See L for more info. + +=item Param C<$resultCols> [Optional] + +A comma-separated list of colunm names that shall be returned. If not defined, +all available data must be returned. + +=item Return Value + +An array of hash-refs containing the resulting data rows. + +=back + +=cut + sub fetchClientByFilter { my $self = shift; @@ -270,6 +641,28 @@ sub fetchClientByFilter return wantarray() ? @clients : shift @clients; } +=item C + +Fetches and returns information the clients with the given IDs. + +=over + +=item Param C + +An array of the client-IDs you are interested in. + +=item Param C + +A string listing the columns that shall be returned - default is all columns. + +=item Return Value + +An array of hash-refs containing the resulting data rows. + +=back + +=cut + sub fetchClientByID { my $self = shift; @@ -280,6 +673,25 @@ sub fetchClientByID return wantarray() ? @clients : shift @clients; } +=item C + +Fetches the IDs of all clients that make use of the system with the given +ID. + +=over + +=item Param C + +ID of the system whose clients shall be returned. + +=item Return Value + +An array of client-IDs. + +=back + +=cut + sub fetchClientIDsOfSystem { my $self = shift; @@ -288,6 +700,25 @@ sub fetchClientIDsOfSystem return $self->{'meta-db'}->fetchClientIDsOfSystem($systemID); } +=item C + +Fetches the IDs of all clients that are part of the group with the given +ID. + +=over + +=item Param C + +ID of the group whose clients shall be returned. + +=item Return Value + +An array of client-IDs. + +=back + +=cut + sub fetchClientIDsOfGroup { my $self = shift; @@ -296,6 +727,30 @@ sub fetchClientIDsOfGroup return $self->{'meta-db'}->fetchClientIDsOfGroup($groupID); } +=item C + +Fetches and returns information about all groups that match the given filter. + +=over + +=item Param C<$filter> + +A hash-ref containing the filter criteria that shall be applied - default +is no filtering. See L for more info. + +=item Param C<$resultCols> [Optional] + +A comma-separated list of colunm names that shall be returned. If not defined, +all available data must be returned. + +=item Return Value + +An array of hash-refs containing the resulting data rows. + +=back + +=cut + sub fetchGroupByFilter { my $self = shift; @@ -306,6 +761,28 @@ sub fetchGroupByFilter return wantarray() ? @groups : shift @groups; } +=item C + +Fetches and returns information the groups with the given IDs. + +=over + +=item Param C + +An array of the group-IDs you are interested in. + +=item Param C + +A string listing the columns that shall be returned - default is all columns. + +=item Return Value + +An array of hash-refs containing the resulting data rows. + +=back + +=cut + sub fetchGroupByID { my $self = shift; @@ -316,6 +793,25 @@ sub fetchGroupByID return wantarray() ? @groups : shift @groups; } +=item C + +Fetches the IDs of all groups that contain the system with the given +ID. + +=over + +=item Param C + +ID of the system whose groups shall be returned. + +=item Return Value + +An array of client-IDs. + +=back + +=cut + sub fetchGroupIDsOfSystem { my $self = shift; @@ -324,6 +820,25 @@ sub fetchGroupIDsOfSystem return $self->{'meta-db'}->fetchGroupIDsOfSystem($systemID); } +=item C + +Fetches the IDs of all groups that contain the client with the given +ID. + +=over + +=item Param C + +ID of the client whose groups shall be returned. + +=item Return Value + +An array of client-IDs. + +=back + +=cut + sub fetchGroupIDsOfClient { my $self = shift; @@ -332,9 +847,26 @@ sub fetchGroupIDsOfClient return $self->{'meta-db'}->fetchGroupIDsOfClient($clientID); } -################################################################################ -### data manipulation interface -################################################################################ +=head2 Data Manipulation Methods + +=item C + +Adds one or more vendor-OS to the database. + +=over + +=item Param C + +An array-ref containing hash-refs with the data of the new vendor-OS(es). + +=item Return Value + +The IDs of the new vendor-OS(es), C if the creation failed. + +=back + +=cut + sub addVendorOS { my $self = shift; @@ -343,6 +875,24 @@ sub addVendorOS return $self->{'meta-db'}->addVendorOS($valRows); } +=item C + +Removes one or more vendor-OS from the database. + +=over + +=item Param C + +An array-ref containing the IDs of the vendor-OSes that shall be removed. + +=item Return Value + +C<1> if the vendorOS(es) could be removed, C if not. + +=back + +=cut + sub removeVendorOS { my $self = shift; @@ -351,6 +901,28 @@ sub removeVendorOS return $self->{'meta-db'}->removeVendorOS($vendorOSIDs); } +=item C + +Changes the data of one or more vendor-OS. + +=over + +=item Param C + +An array-ref containing the IDs of the vendor-OSes that shall be changed. + +=item Param C + +An array-ref containing hash-refs with the new data for the vendor-OS(es). + +=item Return Value + +C<1> if the vendorOS(es) could be changed, C if not. + +=back + +=cut + sub changeVendorOS { my $self = shift; @@ -360,35 +932,23 @@ sub changeVendorOS return $self->{'meta-db'}->changeVendorOS($vendorOSIDs, $valRows); } -sub incrementExportCounterForVendorOS -{ - my $self = shift; - my $id = shift; +=item C - $self->start_transaction(); - my $vendorOS = $self->fetchVendorOSByID($id); - return unless defined $vendorOS; - my $exportCounter = $vendorOS->{export_counter} + 1; - $self->changeVendorOS($id, {'export_counter' => $exportCounter}); - $self->commit_transaction(); +Adds one or more export to the database. - return $exportCounter; -} +=over -sub incrementGlobalCounter -{ - my $self = shift; - my $counterName = shift; +=item Param C - $self->start_transaction(); - my $value = $self->fetchGlobalInfo($counterName); - return unless defined $value; - my $newValue = $value + 1; - $self->changeGlobalInfo($counterName, $newValue); - $self->commit_transaction(); +An array-ref containing hash-refs with the data of the new export(s). - return $value; -} +=item Return Value + +The IDs of the new export(s), C if the creation failed. + +=back + +=cut sub addExport { @@ -398,6 +958,24 @@ sub addExport return $self->{'meta-db'}->addExport($valRows); } +=item C + +Removes one or more export from the database. + +=over + +=item Param C + +An array-ref containing the IDs of the exports that shall be removed. + +=item Return Value + +C<1> if the export(s) could be removed, C if not. + +=back + +=cut + sub removeExport { my $self = shift; @@ -406,6 +984,28 @@ sub removeExport return $self->{'meta-db'}->removeExport($exportIDs); } +=item C + +Changes the data of one or more export. + +=over + +=item Param C + +An array-ref containing the IDs of the exports that shall be changed. + +=item Param C + +An array-ref containing hash-refs with the new data for the export(s). + +=item Return Value + +C<1> if the export(s) could be changed, C if not. + +=back + +=cut + sub changeExport { my $self = shift; @@ -415,6 +1015,61 @@ sub changeExport return $self->{'meta-db'}->changeExport($exportIDs, $valRows); } +=item C + +Increments the global counter of the given name and returns the *old* value. + +=over + +=item Param C + +The name of the global counter that shall be bumped. + +=item Return Value + +The value the global counter had before it was incremented. + +=back + +=cut + +sub incrementGlobalCounter +{ + my $self = shift; + my $counterName = shift; + + $self->start_transaction(); + my $value = $self->fetchGlobalInfo($counterName); + return unless defined $value; + my $newValue = $value + 1; + $self->changeGlobalInfo($counterName, $newValue); + $self->commit_transaction(); + + return $value; +} + +=item C + +Sets the global info element specified by the given ID to the given value. + +=over + +=item Param C + +The ID specifying the global info you'd like to change. + +=item Param C + +The new value for the global info element. + +=item Return Value + +The value the global counter had before it was incremented. + +=back + +=cut + sub changeGlobalInfo { my $self = shift; @@ -424,6 +1079,24 @@ sub changeGlobalInfo return $self->{'meta-db'}->changeGlobalInfo($id, $value); } +=item C + +Adds one or more systems to the database. + +=over + +=item Param C + +An array-ref containing hash-refs with the data of the new system(s). + +=item Return Value + +The IDs of the new system(s), C if the creation failed. + +=back + +=cut + sub addSystem { my $self = shift; @@ -447,6 +1120,24 @@ sub addSystem return $self->{'meta-db'}->addSystem($valRows); } +=item C + +Removes one or more systems from the database. + +=over + +=item Param C + +An array-ref containing the IDs of the systems that shall be removed. + +=item Return Value + +C<1> if the system(s) could be removed, C if not. + +=back + +=cut + sub removeSystem { my $self = shift; @@ -460,6 +1151,28 @@ sub removeSystem return $self->{'meta-db'}->removeSystem($systemIDs); } +=item C + +Changes the data of one or more systems. + +=over + +=item Param C + +An array-ref containing the IDs of the systems that shall be changed. + +=item Param C + +An array-ref containing hash-refs with the new data for the system(s). + +=item Return Value + +C<1> if the system(s) could be changed, C if not. + +=back + +=cut + sub changeSystem { my $self = shift; @@ -469,6 +1182,29 @@ sub changeSystem return $self->{'meta-db'}->changeSystem($systemIDs, $valRows); } +=item C + +Specifies all clients that should offer the given system for booting. + +=over + +=item Param C + +The ID of the system whose clients you'd like to specify. + +=item Param C + +An array-ref containing the IDs of the clients that shall be connected to the +system. + +=item Return Value + +C<1> if the system/client references could be set, C if not. + +=back + +=cut + sub setClientIDsOfSystem { my $self = shift; @@ -480,6 +1216,29 @@ sub setClientIDsOfSystem ->setClientIDsOfSystem($systemID, \@uniqueClientIDs); } +=item C + +Add one or more clients to the set that should offer the given system for booting. + +=over + +=item Param C + +The ID of the system that you wish to add the clients to. + +=item Param C + +An array-ref containing the IDs of the new clients that shall be added to the +system. + +=item Return Value + +C<1> if the system/client references could be set, C if not. + +=back + +=cut + sub addClientIDsToSystem { my $self = shift; @@ -491,6 +1250,29 @@ sub addClientIDsToSystem return $self->setClientIDsOfSystem($systemID, \@clientIDs); } +=item C + +Removes the connection between the given clients and the given system. + +=over + +=item Param C + +The ID of the system you'd like to remove groups from. + +=item Param C + +An array-ref containing the IDs of the clients that shall be removed from the +system. + +=item Return Value + +C<1> if the system/client references could be set, C if not. + +=back + +=cut + sub removeClientIDsFromSystem { my $self = shift; @@ -505,6 +1287,29 @@ sub removeClientIDsFromSystem return $self->setClientIDsOfSystem($systemID, \@clientIDs); } +=item C + +Specifies all groups that should offer the given system for booting. + +=over + +=item Param C + +The ID of the system whose groups you'd like to specify. + +=item Param C + +An array-ref containing the IDs of the groups that shall be connected to the +system. + +=item Return Value + +C<1> if the system/group references could be set, C if not. + +=back + +=cut + sub setGroupIDsOfSystem { my $self = shift; @@ -515,6 +1320,29 @@ sub setGroupIDsOfSystem return $self->{'meta-db'}->setGroupIDsOfSystem($systemID, \@uniqueGroupIDs); } +=item C + +Add one or more groups to the set that should offer the given system for booting. + +=over + +=item Param C + +The ID of the system that you wish to add the groups to. + +=item Param C + +An array-ref containing the IDs of the new groups that shall be added to the +system. + +=item Return Value + +C<1> if the system/group references could be set, C if not. + +=back + +=cut + sub addGroupIDsToSystem { my $self = shift; @@ -526,6 +1354,29 @@ sub addGroupIDsToSystem return $self->setGroupIDsOfSystem($systemID, \@groupIDs); } +=item C + +Removes the connection between the given groups and the given system. + +=over + +=item Param C + +The ID of the system you'd like to remove groups from. + +=item Param C + +An array-ref containing the IDs of the groups that shall be removed from the +system. + +=item Return Value + +C<1> if the system/group references could be set, C if not. + +=back + +=cut + sub removeGroupIDsFromSystem { my $self = shift; @@ -540,6 +1391,24 @@ sub removeGroupIDsFromSystem return $self->setGroupIDsOfSystem($systemID, \@groupIDs); } +=item C + +Adds one or more clients to the database. + +=over + +=item Param C + +An array-ref containing hash-refs with the data of the new client(s). + +=item Return Value + +The IDs of the new client(s), C if the creation failed. + +=back + +=cut + sub addClient { my $self = shift; @@ -554,6 +1423,24 @@ sub addClient return $self->{'meta-db'}->addClient($valRows); } +=item C + +Removes one or more clients from the database. + +=over + +=item Param C + +An array-ref containing the IDs of the clients that shall be removed. + +=item Return Value + +C<1> if the client(s) could be removed, C if not. + +=back + +=cut + sub removeClient { my $self = shift; @@ -567,6 +1454,28 @@ sub removeClient return $self->{'meta-db'}->removeClient($clientIDs); } +=item C + +Changes the data of one or more clients. + +=over + +=item Param C + +An array-ref containing the IDs of the clients that shall be changed. + +=item Param C + +An array-ref containing hash-refs with the new data for the client(s). + +=item Return Value + +C<1> if the client(s) could be changed, C if not. + +=back + +=cut + sub changeClient { my $self = shift; @@ -576,6 +1485,29 @@ sub changeClient return $self->{'meta-db'}->changeClient($clientIDs, $valRows); } +=item C + +Specifies all systems that should be offered for booting by the given client. + +=over + +=item Param C + +The ID of the client whose systems you'd like to specify. + +=item Param C + +An array-ref containing the IDs of the systems that shall be connected to the +client. + +=item Return Value + +C<1> if the client/system references could be set, C if not. + +=back + +=cut + sub setSystemIDsOfClient { my $self = shift; @@ -587,6 +1519,29 @@ sub setSystemIDsOfClient ->setSystemIDsOfClient($clientID, \@uniqueSystemIDs); } +=item C + +Adds some systems to the set that should be offered for booting by the given client. + +=over + +=item Param C + +The ID of the client to which you'd like to add systems to. + +=item Param C + +An array-ref containing the IDs of the new systems that shall be added to the +client. + +=item Return Value + +C<1> if the client/system references could be set, C if not. + +=back + +=cut + sub addSystemIDsToClient { my $self = shift; @@ -598,6 +1553,29 @@ sub addSystemIDsToClient return $self->setSystemIDsOfClient($clientID, \@systemIDs); } +=item C + +Removes some systems from the set that should be offered for booting by the given client. + +=over + +=item Param C + +The ID of the client to which you'd like to remove systems from. + +=item Param C + +An array-ref containing the IDs of the systems that shall be removed from the +client. + +=item Return Value + +C<1> if the client/system references could be set, C if not. + +=back + +=cut + sub removeSystemIDsFromClient { my $self = shift; @@ -612,15 +1590,60 @@ sub removeSystemIDsFromClient return $self->setSystemIDsOfClient($clientID, \@systemIDs); } +=item C + +Specifies all groups that the given client shall be part of. + +=over + +=item Param C + +The ID of the client whose groups you'd like to specify. + +=item Param C + +An array-ref containing the IDs of the groups that the client should be part of. + +=item Return Value + +C<1> if the client/group references could be set, C if not. + +=back + +=cut + sub setGroupIDsOfClient { my $self = shift; my $clientID = shift; my $groupIDs = _aref(shift); - my @uniqueGroupIDs = _unique(@$groupIDs); - return $self->{'meta-db'}->setGroupIDsOfClient($clientID, \@uniqueGroupIDs); -} + my @uniqueGroupIDs = _unique(@$groupIDs); + return $self->{'meta-db'}->setGroupIDsOfClient($clientID, \@uniqueGroupIDs); +} + +=item C + +Adds the given client to the given groups. + +=over + +=item Param C + +The ID of the client that you'd like to add to the given groups. + +=item Param C + +An array-ref containing the IDs of the groups that shall be added to the +client. + +=item Return Value + +C<1> if the client/group references could be set, C if not. + +=back + +=cut sub addGroupIDsToClient { @@ -633,6 +1656,29 @@ sub addGroupIDsToClient return $self->setGroupIDsOfClient($clientID, \@groupIDs); } +=item C + +Removes the given client from the given groups. + +=over + +=item Param C + +The ID of the client that you'd like to remove from the given groups. + +=item Param C + +An array-ref containing the IDs of the groups that shall be removed from the +client. + +=item Return Value + +C<1> if the client/group references could be set, C if not. + +=back + +=cut + sub removeGroupIDsFromClient { my $self = shift; @@ -647,6 +1693,24 @@ sub removeGroupIDsFromClient return $self->setGroupIDsOfClient($clientID, \@groupIDs); } +=item C + +Adds one or more groups to the database. + +=over + +=item Param C + +An array-ref containing hash-refs with the data of the new group(s). + +=item Return Value + +The IDs of the new group(s), C if the creation failed. + +=back + +=cut + sub addGroup { my $self = shift; @@ -655,6 +1719,24 @@ sub addGroup return $self->{'meta-db'}->addGroup($valRows); } +=item C + +Removes one or more groups from the database. + +=over + +=item Param C + +An array-ref containing the IDs of the groups that shall be removed. + +=item Return Value + +C<1> if the group(s) could be removed, C if not. + +=back + +=cut + sub removeGroup { my $self = shift; @@ -668,6 +1750,28 @@ sub removeGroup return $self->{'meta-db'}->removeGroup($groupIDs); } +=item C + +Changes the data of one or more groups. + +=over + +=item Param C + +An array-ref containing the IDs of the groups that shall be changed. + +=item Param C + +An array-ref containing hash-refs with the new data for the group(s). + +=item Return Value + +C<1> if the group(s) could be changed, C if not. + +=back + +=cut + sub changeGroup { my $self = shift; @@ -677,6 +1781,28 @@ sub changeGroup return $self->{'meta-db'}->changeGroup($groupIDs, $valRows); } +=item C + +Specifies all clients that should be part of the given group. + +=over + +=item Param C + +The ID of the group whose clients you'd like to specify. + +=item Param C + +An array-ref containing the IDs of the clients that shall be part of the group. + +=item Return Value + +C<1> if the group/client references could be set, C if not. + +=back + +=cut + sub setClientIDsOfGroup { my $self = shift; @@ -687,6 +1813,28 @@ sub setClientIDsOfGroup return $self->{'meta-db'}->setClientIDsOfGroup($groupID, \@uniqueClientIDs); } +=item C + +Add some clients to the given group. + +=over + +=item Param C + +The ID of the group to which you'd like to add clients. + +=item Param C + +An array-ref containing the IDs of the clients that shall be added. + +=item Return Value + +C<1> if the group/client references could be set, C if not. + +=back + +=cut + sub addClientIDsToGroup { my $self = shift; @@ -698,6 +1846,28 @@ sub addClientIDsToGroup return $self->setClientIDsOfGroup($groupID, \@clientIDs); } +=item C + +Remove some clients from the given group. + +=over + +=item Param C + +The ID of the group from which you'd like to remove clients. + +=item Param C + +An array-ref containing the IDs of the clients that shall be removed. + +=item Return Value + +C<1> if the group/client references could be set, C if not. + +=back + +=cut + sub removeClientIDsFromGroup { my $self = shift; @@ -712,6 +1882,29 @@ sub removeClientIDsFromGroup return $self->setClientIDsOfGroup($groupID, \@clientIDs); } +=item C + +Specifies all systems that should be offered for booting by the given group. + +=over + +=item Param C + +The ID of the group whose systems you'd like to specify. + +=item Param C + +An array-ref containing the IDs of the systems that shall be connected to the +group. + +=item Return Value + +C<1> if the group/system references could be set, C if not. + +=back + +=cut + sub setSystemIDsOfGroup { my $self = shift; @@ -722,6 +1915,28 @@ sub setSystemIDsOfGroup return $self->{'meta-db'}->setSystemIDsOfGroup($groupID, \@uniqueSystemIDs); } +=item C + +Adds some systems to the set that should be offered for booting by the given group. + +=over + +=item Param C + +The ID of the group to which you'd like to add systems. + +=item Param C + +An array-ref containing the IDs of the systems that shall be added. + +=item Return Value + +C<1> if the group/system references could be set, C if not. + +=back + +=cut + sub addSystemIDsToGroup { my $self = shift; @@ -733,6 +1948,28 @@ sub addSystemIDsToGroup return $self->setSystemIDsOfGroup($groupID, \@systemIDs); } +=item C + +Removes some systems from the set that should be offered for booting by the given group. + +=over + +=item Param C + +The ID of the group from which you'd like to remove systems. + +=item Param C + +An array-ref containing the IDs of the systems that shall be removed. + +=item Return Value + +C<1> if the group/system references could be set, C if not. + +=back + +=cut + sub removeSystemIDsFromGroup { my $self = shift; @@ -747,6 +1984,20 @@ sub removeSystemIDsFromGroup return $self->setSystemIDsOfGroup($groupID, \@systemIDs); } +=item C + +Removes all data from the database - the tables stay, but they will be empty. + +=over + +=item Return Value + +none + +=back + +=cut + sub emptyDatabase { # clears all user-data from the database my $self = shift; @@ -772,12 +2023,29 @@ sub emptyDatabase return; } -################################################################################ -### data aggregation interface -################################################################################ +=head2 Data Aggregation Methods + +=item C + +merges default system attributes into the given system hash and pushes the default +client attributes on top of that. + +=over + +=item Param C + +The system whose attributes shall be merged into (completed). + +=item Return Value + +none + +=back + +=cut + sub mergeDefaultAttributesIntoSystem -{ # merge default system attributes into given system - # and push the default client attributes on top of that +{ my $self = shift; my $system = shift; @@ -789,8 +2057,26 @@ sub mergeDefaultAttributesIntoSystem return; } +=item C + +merges default and group configurations into the given client hash. + +=over + +=item Param C + +The client whose attributes shall be merged into (completed). + +=item Return Value + +none + +=back + +=cut + sub mergeDefaultAndGroupAttributesIntoClient -{ # merge default and group configurations into given client +{ my $self = shift; my $client = shift; @@ -814,9 +2100,27 @@ sub mergeDefaultAndGroupAttributesIntoClient return; } +=item C + +Returns an aggregated list of system-IDs that this client should offer for +booting (as indicated by itself, the default client and the client's groups) + +=over + +=item Param C + +The client whose aggregated systems you're interested in. + +=item Return Value + +A list of unqiue system-IDs. + +=back + +=cut + sub aggregatedSystemIDsOfClient -{ # return aggregated list of system-IDs this client should offer - # (as indicated by itself, the default client and the client's groups) +{ my $self = shift; my $client = shift; @@ -837,9 +2141,27 @@ sub aggregatedSystemIDsOfClient return _unique(@systemIDs); } +=item C + +Returns an aggregated list of client-IDs that offer this system for +booting (as indicated by itself, the default system and the system's groups) + +=over + +=item Param C + +The system whose aggregated clients you're interested in. + +=item Return Value + +A list of unqiue client-IDs. + +=back + +=cut + sub aggregatedClientIDsOfSystem -{ # return aggregated list of client-IDs this system is linked to - # (as indicated by itself, the default system and the system's groups). +{ my $self = shift; my $system = shift; @@ -868,9 +2190,28 @@ sub aggregatedClientIDsOfSystem return _unique(@clientIDs); } +=item C + +Returns aggregated information about the kernel and initialramfs +this system is using. + +=over + +=item Param C + +The system whose aggregated info you're interested in. + +=item Return Value + +A hash containing detailled info about the vendor-OS and export used by +this system, as well as the specific kernel-file and export-URI being used. + +=back + +=cut + sub aggregatedSystemFileInfoFor -{ # return aggregated information about the kernel and initialramfs - # this system is using +{ my $self = shift; my $system = shift; @@ -894,7 +2235,7 @@ sub aggregatedSystemFileInfoFor } $info->{'vendor-os'} = $vendorOS; - # check if the specified kernel file really exists (follow links while + # check if the specified kernel file really exists (follow links while # checking) and if not, find the newest kernel file that is available. my $kernelPath = "$openslxConfig{'private-path'}/stage1/$vendorOS->{name}/boot"; @@ -909,7 +2250,7 @@ sub aggregatedSystemFileInfoFor $kernelFile = $osSetupEngine->pickKernelFile($kernelPath); warn( _tr( - "setting kernel of system '%s' to '%s'!", + "setting kernel of system '%s' to '%s'!", $info->{name}, $kernelFile ) ); @@ -929,18 +2270,58 @@ sub aggregatedSystemFileInfoFor return $info; } -################################################################################ -### support interface -################################################################################ +=head2 Support Functions + +=item C + +Returns whether or not the given key is an exportable attribute. + +=over + +=item Param C + +The key to check. + +=item Return Value + +1 if the given key is indeed an attribute (currently, this means that +it starts with 'attr_'), 0 if not. + +=back + +=cut + sub isAttribute -{ # returns whether or not the given key is an exportable attribute +{ my $key = shift; return $key =~ m[^attr_]; } +=item C + +Copies all attributes from source that are unset in target over (source extends target). + +=over + +=item Param C + +The hash to be used as copy target. + +=item Param C + +The hash to be used as copy source. + +=item Return Value + +none + +=back + +=cut + sub mergeAttributes -{ # copies all attributes of source that are unset in target over +{ my $target = shift; my $source = shift; @@ -955,8 +2336,30 @@ sub mergeAttributes return; } +=item C + +Copies all attributes that are set in source into the target (source overrules target). + +=over + +=item Param C + +The hash to be used as copy target. + +=item Param C + +The hash to be used as copy source. + +=item Return Value + +none + +=back + +=cut + sub pushAttributes -{ # copies all attributes that are set in source into the target +{ my $target = shift; my $source = shift; @@ -970,9 +2373,27 @@ sub pushAttributes return; } +=item C + +Returns the given system's name as an external ID - worked into a +state that is usable as a filename. + +=over + +=item Param C + +The system you are interested in. + +=item Return Value + +The external ID (name) of the given system. + +=back + +=cut + sub externalIDForSystem -{ # returns given system's name as the external ID, worked into a - # state that is usable as a filename: +{ my $system = shift; return "default" if $system->{id} == 0; @@ -982,9 +2403,27 @@ sub externalIDForSystem return $name; } +=item C + +Returns the given client's MAC as an external ID - worked into a +state that is usable as a filename. + +=over + +=item Param C + +The client you are interested in. + +=item Return Value + +The external ID (MAC) of the given client. + +=back + +=cut + sub externalIDForClient -{ # returns given client's MAC as the external ID, worked into a - # state that is usable as a filename: +{ my $client = shift; return "default" if $client->{id} == 0; @@ -995,18 +2434,55 @@ sub externalIDForClient return "01-$mac"; } +=item C + +Returns the given client's name as an external ID - worked into a +state that is usable as a filename. + +=over + +=item Param C + +The client you are interested in. + +=item Return Value + +The external name of the given client. + +=back + +=cut + sub externalConfigNameForClient -{ # returns given client's name as the external ID, worked into a - # state that is usable as a filename: +{ my $client = shift; - return "default" if $client->{id} == 0; + return "default" if $client->{name} eq '<<>>'; my $name = $client->{name}; $name =~ tr[/][_]; return $name; } +=item C + +Returns the given attribute as it is referenced externally - without the +'attr'_-prefix. + +=over + +=item Param C + +The attribute you are interested in. + +=item Return Value + +The external name of the given attribute. + +=back + +=cut + sub externalAttrName { my $attr = shift; @@ -1016,6 +2492,24 @@ sub externalAttrName return $attr; } +=item C + +Returns the given variable as a placeholder - surrounded by '@@@' markers. + +=over + +=item Param C + +The variable you are interested in. + +=item Return Value + +The given variable as a placeholder string. + +=back + +=cut + sub generatePlaceholderFor { my $varName = shift; diff --git a/config-db/OpenSLX/MetaDB/DBI.pm b/config-db/OpenSLX/MetaDB/DBI.pm index 27d493f6..b80f3c0a 100644 --- a/config-db/OpenSLX/MetaDB/DBI.pm +++ b/config-db/OpenSLX/MetaDB/DBI.pm @@ -45,21 +45,21 @@ sub quote return $self->{'dbh'}->quote(@_); } -sub start_transaction +sub startTransaction { # default implementation passes on the request to the DBI my $self = shift; return $self->{'dbh'}->begin_work(); } -sub commit_transaction +sub commitTransaction { # default implementation passes on the request to the DBI my $self = shift; return $self->{'dbh'}->commit(); } -sub rollback_transaction +sub rollbackTransaction { # default implementation passes on the request to the DBI my $self = shift; -- cgit v1.2.3-55-g7522