diff options
Diffstat (limited to 'src/config-db/OpenSLX/MetaDB/Base.pm')
-rw-r--r-- | src/config-db/OpenSLX/MetaDB/Base.pm | 1220 |
1 files changed, 1220 insertions, 0 deletions
diff --git a/src/config-db/OpenSLX/MetaDB/Base.pm b/src/config-db/OpenSLX/MetaDB/Base.pm new file mode 100644 index 00000000..f1fbd0f5 --- /dev/null +++ b/src/config-db/OpenSLX/MetaDB/Base.pm @@ -0,0 +1,1220 @@ +# Copyright (c) 2006, 2007 - OpenSLX GmbH +# +# This program is free software distributed under the GPL version 2. +# See http://openslx.org/COPYING +# +# If you have any feedback please consult http://openslx.org/feedback and +# send your suggestions, praise, or complaints to feedback@openslx.org +# +# General information about OpenSLX can be found at http://openslx.org/ +# ----------------------------------------------------------------------------- +# Base.pm +# - provides empty base of the OpenSLX MetaDB API. +# ----------------------------------------------------------------------------- +package OpenSLX::MetaDB::Base; + +use strict; +use warnings; + +our $VERSION = 1.01; # API-version . implementation-version + +use OpenSLX::Basics; + +################################################################################ +### basic functions +################################################################################ +sub new +{ + confess "Don't create OpenSLX::MetaDB::Base - objects directly!"; +} + +sub connect ## no critic (ProhibitBuiltinHomonyms) +{ +} + +sub disconnect +{ +} + +sub quote +{ +} + +################################################################################ +### data access interface +################################################################################ +sub fetchVendorOSByFilter +{ +} + +sub fetchVendorOSByID +{ +} + +sub fetchExportByFilter +{ +} + +sub fetchExportByID +{ +} + +sub fetchExportIDsOfVendorOS +{ +} + +sub fetchSystemByFilter +{ +} + +sub fetchSystemByID +{ +} + +sub fetchSystemIDsOfExport +{ +} + +sub fetchSystemIDsOfClient +{ +} + +sub fetchSystemIDsOfGroup +{ +} + +sub fetchClientByFilter +{ +} + +sub fetchClientByID +{ +} + +sub fetchClientIDsOfSystem +{ +} + +sub fetchClientIDsOfGroup +{ +} + +sub fetchGroupByFilter +{ +} + +sub fetchGroupByID +{ +} + +sub fetchGroupIDsOfClient +{ +} + +sub fetchGroupIDsOfSystem +{ +} + +################################################################################ +### data manipulation interface +################################################################################ +sub generateNextIdForTable +{ # some DBs (CSV for instance) aren't able to generate any IDs, so we + # offer an alternative way (by pre-specifying IDs for INSERTs). + # NB: if this method is called without a tablename, it returns: + # 1 if this backend requires manual ID generation + # 0 if not. + return; +} + +sub addVendorOS +{ +} + +sub removeVendorOS +{ +} + +sub changeVendorOS +{ +} + +sub addExport +{ +} + +sub removeExport +{ +} + +sub changeExport +{ +} + +sub addSystem +{ +} + +sub removeSystem +{ +} + +sub changeSystem +{ +} + +sub setClientIDsOfSystem +{ +} + +sub setGroupIDsOfSystem +{ +} + +sub addClient +{ +} + +sub removeClient +{ +} + +sub changeClient +{ +} + +sub setSystemIDsOfClient +{ +} + +sub setGroupIDsOfClient +{ +} + +sub addGroup +{ +} + +sub removeGroup +{ +} + +sub changeGroup +{ +} + +sub setClientIDsOfGroup +{ +} + +sub setSystemIDsOfGroup +{ +} + +################################################################################ +### schema related functions +################################################################################ +sub schemaFetchDBVersion +{ +} + +sub schemaSetDBVersion +{ +} + +sub schemaCreate +{ +} + +sub schemaUpgradeToCurrent +{ +} + +sub schemaConvertTypeDescrToNative +{ +} + +sub schemaAddTable +{ +} + +sub schemaDropTable +{ +} + +sub schemaRenameTable +{ +} + +sub schemaAddColumns +{ +} + +sub schemaDropColumns +{ +} + +sub schemaChangeColumns +{ +} + +1; +################################################################################ + +=pod + +=head1 NAME + +OpenSLX::MetaDB::Base - the base class for all MetaDB drivers + +=head1 SYNOPSIS + + package OpenSLX::MetaDB::coolnewDB; + + use vars qw(@ISA $VERSION); + @ISA = ('OpenSLX::MetaDB::Base'); + $VERSION = 1.01; + + my $superVersion = $OpenSLX::MetaDB::Base::VERSION; + if ($superVersion < $VERSION) { + croak _tr('Unable to load module <%s> (Version <%s> required)', + 'OpenSLX::MetaDB::Base', $VERSION); + } + + use coolnewDB; + + sub new + { + my $class = shift; + my $self = {}; + return bless $self, $class; + } + + sub connectConfigDB + { + my $self = shift; + + my $dbName = $openslxConfig{'db-name'}; + vlog(1, "trying to connect to coolnewDB-database <$dbName>"); + $self->{'dbh'} = ... # get connection handle from coolnewDB + } + + sub disconnectConfigDB + { + my $self = shift; + + $self->{'dbh'}->disconnect; + } + + # override all methods of OpenSLX::MetaDB::Base in order to implement + # a full MetaDB driver + ... + +I<The synopsis above outlines a class that implements a +MetaDB driver for the (imaginary) database B<coolnewDB>> + +=head1 DESCRIPTION + +This class defines the MetaDB interface for the OpenSLX. + +Aim of the MetaDB abstraction is to make it possible to use a large set +of different databases (from CSV-files to a fullblown Oracle-installation) +transparently. + +While OpenSLX::ConfigDB represents the data layer to the outside world, each +implementation of OpenSLX::MetaDB::Base provides a backend for a specific database. + +This way, the different OpenSLX-scripts do not have to burden +themselves with any DB-specific details, they just request the data they want +from the ConfigDB-layer and that in turn creates and communicates with the +appropriate MetaDB driver in order to connect to the database and fetch and/or +change the data as instructed. + +The MetaDB interface contains of four different parts: + +=over + +=item - L<basic methods> (connection handling and utilities) + +=item - L<data access methods> (getting data) + +=item - L<data manipulation methods> (adding, removing and changing data) + +=item - L<schema related methods> (migrating between different DB-versions) + +=back + +In order to implement a MetaDB driver for a specific database, you need +to inherit from B<OpenSLX::MetaDB::Base> and implement the full interface. As this +is quite some work, it might be wiser to actually inherit your driver from +B<L<OpenSLX::MetaDB::DBI|OpenSLX::MetaDB::DBI>>, which is a default implementation for SQL databases. + +If there is a DBD-driver for the database your new MetaDB driver wants to talk +to then all you need to do is inherit from B<OpenSLX::MetaDB::DBI> and then +reimplement L<C<connectConfigDB>> (and maybe some other methods in order to +improve efficiency). + +=head1 Special Concepts + +=over + +=item C<Filters> + +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 + +=head1 Methods + +=head2 Basic Methods + +The following basic methods need to be implemented in a MetaDB driver: + +=over + +=item C<connectConfigDB()> + +Tries to establish a connection to the DBMS that this MetaDB driver deals with. +The global configuration hash C<%config> 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<$config{'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<$config{'db-name'}> + +The precise name of the database that should be connected (defaults to 'openslx'). + +=back + +=item C<disconnectConfigDB()> + +Tears down the connection to the DBMS that this MetaDB driver deals with and +cleans up. + +=item C<quote(string)> + +Returns the given string quoted such that it can be used in SQL-statements +(with respect to the corresponding DBMS). + +This usually involves putting +single quotes around the string and escaping any single quote characters +enclosed in the given string with a backslash. + +=back + +=head2 Data Access Methods + +The following methods need to be implemented in a MetaDB driver in order to +allow the user to access data: + +=over + +=item C<fetchVendorOSByFilter([%$filter], [$resultCols])> + +Fetches and returns information about all vendor-OSes 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</"Filters"> for more info. + +=item Param C<resultCols> + +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 + +=item C<fetchVendorOSByID(@$ids, [$resultCols])> + +Fetches and returns information the vendor-OSes with the given IDs. + +=over + +=item Param C<ids> + +An array of the vendor-OS-IDs you are interested in. + +=item Param C<resultCols> + +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 + +=item C<fetchExportByFilter([%$filter], [$resultCols])> + +Fetches and returns information about all exports 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</"Filters"> for more info. + +=item Param C<resultCols> + +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 + +=item C<fetchExportByID(@$ids, [$resultCols])> + +Fetches and returns information the exports with the given IDs. + +=over + +=item Param C<ids> + +An array of the export-IDs you are interested in. + +=item Param C<resultCols> + +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 + +=item C<fetchExportIDsOfVendorOS($id)> + +Fetches the IDs of all exports that make use of the vendor-OS with the given ID. + +=over + +=item Param C<id> + +ID of the vendor-OS whose exports shall be returned. + +=item Return Value + +An array of system-IDs. + +=back + +=item C<fetchSystemByFilter([%$filter], [$resultCols])> + +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</"Filters"> 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 + +=item C<fetchSystemByID(@$ids, [$resultCols])> + +Fetches and returns information the systems with the given IDs. + +=over + +=item Param C<ids> + +An array of the system-IDs you are interested in. + +=item Param C<resultCols> + +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 + +=item C<fetchSystemIDsOfExport($id)> + +Fetches the IDs of all systems that make use of the export with the given ID. + +=over + +=item Param C<id> + +ID of the export whose systems shall be returned. + +=item Return Value + +An array of system-IDs. + +=back + +=item C<fetchSystemIDsOfClient($id)> + +Fetches the IDs of all systems that are used by the client with the given +ID. + +=over + +=item Param C<id> + +ID of the client whose systems shall be returned. + +=item Return Value + +An array of system-IDs. + +=back + +=item C<fetchSystemIDsOfGroup($id)> + +Fetches the IDs of all systems that are part of the group with the given +ID. + +=over + +=item Param C<id> + +ID of the group whose systems shall be returned. + +=item Return Value + +An array of system-IDs. + +=back + +=item C<fetchClientByFilter([%$filter], [$resultCols])> + +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</"Filters"> 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 + +=item C<fetchClientByID(@$ids, [$resultCols])> + +Fetches and returns information the clients with the given IDs. + +=over + +=item Param C<ids> + +An array of the client-IDs you are interested in. + +=item Param C<resultCols> + +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 + +=item C<fetchClientIDsOfSystem($id)> + +Fetches the IDs of all clients that make use of the system with the given +ID. + +=over + +=item Param C<id> + +ID of the system whose clients shall be returned. + +=item Return Value + +An array of client-IDs. + +=back + +=item C<fetchClientIDsOfGroup($id)> + +Fetches the IDs of all clients that are part of the group with the given +ID. + +=over + +=item Param C<id> + +ID of the group whose clients shall be returned. + +=item Return Value + +An array of client-IDs. + +=back + + + +=item C<fetchGroupByFilter([%$filter], [$resultCols])> + +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</"Filters"> 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 + + + +=item C<fetchGroupByID(@$ids, [$resultCols])> + +Fetches and returns information the groups with the given IDs. + +=over + +=item Param C<ids> + +An array of the group-IDs you are interested in. + +=item Param C<resultCols> + +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 + + + +=item C<fetchGroupIDsOfClient($id)> + +Fetches the IDs of all groups that contain the client with the given +ID. + +=over + +=item Param C<id> + +ID of the client whose groups shall be returned. + +=item Return Value + +An array of client-IDs. + +=back + + + +=item C<fetchGroupIDsOfSystem($id)> + +Fetches the IDs of all groups that contain the system with the given +ID. + +=over + +=item Param C<id> + +ID of the system whose groups shall be returned. + +=item Return Value + +An array of client-IDs. + +=back + + + +=head2 Data Manipulation Methods + +The following methods need to be implemented in a MetaDB driver in order to +allow the user to access change the underlying: + + + +=item C<addVendorOS(@$valRows)> + +Adds one or more vendor-OS to the database. + +=over + +=item Param C<valRows> + +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<undef> if the creation failed. + +=back + + + +=item C<removeVendorOS(@$vendorOSIDs)> + +Removes one or more vendor-OS from the database. + +=over + +=item Param C<vendorOSIDs> + +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<undef> if not. + +=back + + + +=item C<changeVendorOS(@$vendorOSIDs, @$valRows)> + +Changes the data of one or more vendor-OS. + +=over + +=item Param C<vendorOSIDs> + +An array-ref containing the IDs of the vendor-OSes that shall be changed. + +=item Param C<valRows> + +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<undef> if not. + +=back + + + +=item C<addExport(@$valRows)> + +Adds one or more export to the database. + +=over + +=item Param C<valRows> + +An array-ref containing hash-refs with the data of the new export(s). + +=item Return Value + +The IDs of the new export(s), C<undef> if the creation failed. + +=back + + + +=item C<removeExport(@$exportIDs)> + +Removes one or more export from the database. + +=over + +=item Param C<exportIDs> + +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<undef> if not. + +=back + + + +=item C<changeExport(@$exportIDs, @$valRows)> + +Changes the data of one or more export. + +=over + +=item Param C<vendorOSIDs> + +An array-ref containing the IDs of the exports that shall be changed. + +=item Param C<valRows> + +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<undef> if not. + +=back + + + +=item C<addSystem(@$valRows)> + +Adds one or more systems to the database. + +=over + +=item Param C<valRows> + +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<undef> if the creation failed. + +=back + + + +=item C<removeSystem(@$systemIDs)> + +Removes one or more systems from the database. + +=over + +=item Param C<systemIDs> + +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<undef> if not. + +=back + + + +=item C<changeSystem(@$systemIDs, @$valRows)> + +Changes the data of one or more systems. + +=over + +=item Param C<systemIDs> + +An array-ref containing the IDs of the systems that shall be changed. + +=item Param C<valRows> + +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<undef> if not. + +=back + + + +=item C<setClientIDsOfSystem($systemID, @$clientIDs)> + +Specifies all clients that should offer the given system for booting. + +=over + +=item Param C<systemID> + +The ID of the system whose clients you'd like to specify. + +=item Param C<clientIDs> + +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<undef> if not. + +=back + + + +=item C<setGroupIDsOfSystem($systemID, @$groupIDs)> + +Specifies all groups that should offer the given system for booting. + +=over + +=item Param C<systemID> + +The ID of the system whose groups you'd like to specify. + +=item Param C<clientIDs> + +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<undef> if not. + +=back + + + +=item C<addClient(@$valRows)> + +Adds one or more clients to the database. + +=over + +=item Param C<valRows> + +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<undef> if the creation failed. + +=back + + + +=item C<removeClient(@$clientIDs)> + +Removes one or more clients from the database. + +=over + +=item Param C<clientIDs> + +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<undef> if not. + +=back + + + +=item C<changeClient(@$clientIDs, @$valRows)> + +Changes the data of one or more clients. + +=over + +=item Param C<clientIDs> + +An array-ref containing the IDs of the clients that shall be changed. + +=item Param C<valRows> + +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<undef> if not. + +=back + + + +=item C<setSystemIDsOfClient($clientID, @$clientIDs)> + +Specifies all systems that should be offered for booting by the given client. + +=over + +=item Param C<clientID> + +The ID of the client whose systems you'd like to specify. + +=item Param C<systemIDs> + +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<undef> if not. + +=back + + + +=item C<setGroupIDsOfClient($clientID, @$groupIDs)> + +Specifies all groups that the given client shall be part of. + +=over + +=item Param C<clientID> + +The ID of the client whose groups you'd like to specify. + +=item Param C<groupIDs> + +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<undef> if not. + +=back + + + +=item C<addGroup(@$valRows)> + +Adds one or more groups to the database. + +=over + +=item Param C<valRows> + +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<undef> if the creation failed. + +=back + + + +=item C<removeGroup(@$groupIDs)> + +Removes one or more groups from the database. + +=over + +=item Param C<groupIDs> + +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<undef> if not. + +=back + + + +=item C<changeGroup(@$groupIDs, @$valRows)> + +Changes the data of one or more groups. + +=over + +=item Param C<groupIDs> + +An array-ref containing the IDs of the groups that shall be changed. + +=item Param C<valRows> + +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<undef> if not. + +=back + + + +=item C<setClientIDsOfGroup($groupID, @$clientIDs)> + +Specifies all clients that should be part of the given group. + +=over + +=item Param C<groupID> + +The ID of the group whose clients you'd like to specify. + +=item Param C<clientIDs> + +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<undef> if not. + +=back + + + +=item C<setSystemIDsOfGroup($groupID, @$groupIDs)> + +Specifies all systems that should be offered for booting by the given group. + +=over + +=item Param C<groupID> + +The ID of the group whose systems you'd like to specify. + +=item Param C<systemIDs> + +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<undef> if not. + +=back + + + + + +=head2 Schema Related Methods + +The following methods need to be implemented in a MetaDB driver in order to +be able to automatically adjust to new database schema versions (by adding +and/or removing tables and table-columns). + +=cut |