NAME
Muldis::DB::Interface - Common public API for Muldis::DB Engines
VERSION
This document describes Muldis::DB::Interface version 0.3.0 for Perl 5.
It also describes the same-number versions for Perl 5 of Muldis::DB::Interface::DBMS ("DBMS"), Muldis::DB::Interface::HostGateVar ("HostGateVar"), and Muldis::DB::Interface::HostGateRtn ("HostGateRtn").
It also describes the same-number versions for Perl 5 of Muldis::DB::Engine::Role, Muldis::DB::Engine::Role::DBMS, Muldis::DB::Engine::Role::HostGateVar, and Muldis::DB::Engine::Role::HostGateRtn.
SYNOPSIS
use Muldis::DB::Interface;
# Instantiate a Muldis::DB DBMS / virtual machine.
my $dbms = Muldis::DB::Interface::new_dbms({
'engine_name' => 'Muldis::DB::Engine::Example',
'dbms_config' => {},
});
# TODO: Create or connect to a repository and work with it.This documentation is pending.
DESCRIPTION
This documentation is pending.
INTERFACE
The interface of Muldis::DB::Interface is fundamentally object-oriented; you use it by creating objects from its member classes, usually invoking new() on the appropriate class name, and then invoking methods on those objects. All of their attributes are private, so you must use accessor methods.
Muldis::DB::Interface also provides the not-exportable wrapper subroutine Muldis::DB::new_dbms for the Muldis::DB::Interface::DBMS constructor, which has identical parameters, and exists solely as syntactic sugar. Similarly, the DBMS methods new_var and prepare exist purely as syntactic sugar over the HostGateVar and HostGateRtn constructors. TODO: Reimplement these as lexical aliases or compile-time macros instead, to avoid the overhead of extra routine calls.
The usual way that Muldis::DB::Interface indicates a failure is to throw an exception; most often this is due to invalid input. If an invoked routine simply returns, you can assume that it has succeeded, even if the return value is undefined.
The Muldis::DB::Interface::DBMS Class
This documentation is pending.
The Muldis::DB::Interface::HostGateVar Class
This documentation is pending.
The Muldis::DB::Interface::HostGateRtn Class
This documentation is pending.
The Muldis::DB::Engine::Role(|::\w+) Roles
This "Muldis::DB" file also defines a few roles that the public interface classes of all Engine modules must implement, and explicitly declare that they are doing so.
The initial Engine class, which users specify in the $engine_name argument to the Muldis::DB::Interface::DBMS constructor, must compose the Muldis::DB::Engine::Role, and implement the new_dbms submethod. The DBMS Engine object returned by new_dbms must compose the Muldis::DB::Engine::Role::DBMS role, and implement the methods new_var and prepare. The HostGateVar Engine object returned by new_var must compose the Muldis::DB::Engine::Role::HostGateVar role, and implement the methods fetch_ast and store_ast. The HostGateRtn Engine object returned by new_var must compose the Muldis::DB::Engine::Role::HostGateRtn role, and implement the methods bind_host_params and execute.
The Muldis::DB Interface classes don't just validate user input on behalf of Engines (allowing them to be simpler), but they also validate each requested Engine's APIs and results, to some extent, on behalf of users (so an application can more gracefully handle a bad Engine); the Engine Role roles exist to help with the latter kind of validation, and they mainly just declare shims for the required (sub|)methods, which die on invocation if the Engine didn't declare its own versions; they don't presently contain any actual functionality for Engines to use.
DIAGNOSTICS
This documentation is pending.
CONFIGURATION AND ENVIRONMENT
This documentation is pending.
DEPENDENCIES
This file requires any version of Perl 5.x.y that is at least 5.8.1.
It also requires these Perl 5 classes that are in the current distribution: Muldis::DB::Literal-(0.3.0).
INCOMPATIBILITIES
None reported.
SEE ALSO
Go to Muldis::DB for the majority of distribution-internal references, and Muldis::DB::SeeAlso for the majority of distribution-external references.
BUGS AND LIMITATIONS
The Muldis::DB framework for Perl 5 is built according to certain old-school or traditional Perl-5-land design principles, including that there are no explicit attempts in code to enforce privacy of the framework's internals, besides not documenting them as part of the public API. (The Muldis::DB framework for Perl 6 is different.) That said, you should still respect that privacy and just use the public API that Muldis::DB provides. If you bypass the public API anyway, as Perl 5 allows, you do so at your own peril.
This documentation is pending.
AUTHOR
Darren Duncan (perl@DarrenDuncan.net)
LICENSE AND COPYRIGHT
This file is part of the Muldis::DB framework.
Muldis::DB is Copyright © 2002-2007, Darren Duncan.
See the LICENSE AND COPYRIGHT of Muldis::DB for details.
ACKNOWLEDGEMENTS
The ACKNOWLEDGEMENTS in Muldis::DB apply to this file too.