NAME

       Rose::DB::Registry - Data source registry.

SYNOPSIS

         use Rose::DB::Registry;

         $registry = Rose::DB::Registry->new;

         $registry->add_entry(
           domain   => 'development',
           type     => 'main',
           driver   => 'Pg',
           database => 'dev_db',
           host     => 'localhost',
           username => 'devuser',
           password => 'mysecret',
           server_time_zone => 'UTC');

         $entry = Rose::DB::Registry::Entry->new(
           domain   => 'production',
           type     => 'main',
           driver   => 'Pg',
           database => 'big_db',
           host     => 'dbserver.acme.com',
           username => 'dbadmin',
           password => 'prodsecret',
           server_time_zone => 'UTC');

         $registry->add_entry($entry);

         $entry = $registry->entry(domain => 'development', type => 'main');

         $registry->entry_exists(domain => 'foo', type => 'bar'); # false

         $registry->delete_entry(domain => 'development', type => 'main');

         ...

DESCRIPTION

       Rose::DB::Registry objects manage information about Rose::DB data sources.  Each data
       source has a corresponding Rose::DB::Registry::Entry object that contains its information.
       The registry entries are organized in a two-level namespace based on a "domain" and a
       "type."  See the Rose::DB documentation for more information on data source domains and
       types.

       Rose::DB::Registry inherits from, and follows the conventions of, Rose::Object.  See the
       Rose::Object documentation for more information.

CONSTRUCTOR

       new PARAMS
           Constructs a Rose::DB::Registry object based on PARAMS, where PARAMS are name/value
           pairs.  Any object method is a valid parameter name.

OBJECT METHODS

       add_entries ENTRY1 [, ENTRY2, ...]
           Add registry entries.  Each ENTRY must be either a Rose::DB::Registry::Entry-derived
           object or  reference to a hash of name/value pairs.  The name/value pairs must be
           valid arguments for Rose::DB::Registry::Entry's constructor.

           Each ENTRY must have a defined domain and type, either in the
           Rose::DB::Registry::Entry-derived object or in the name/value pairs.  A fatal error
           will occur if these values are not defined.

           If a registry entry for the specified domain and type already exists, then the new
           entry will overwrite it.  If you want to know beforehand whether or not an entry
           exists under a specific domain and type, use the entry_exists method.

           Returns a list (in list context) or reference to an array (in scalar context) of
           Rose::DB::Registry::Entry objects added.

       add_entry ENTRY
           Add a registry entry.  ENTRY must be either a Rose::DB::Registry::Entry-derived object
           or a list of name/value pairs.  The name/value pairs must be valid arguments for
           Rose::DB::Registry::Entry's constructor.

           The ENTRY must have a defined domain and type, either in the
           Rose::DB::Registry::Entry-derived object or in the name/value pairs.  A fatal error
           will occur if these values are not defined.

           If a registry entry for the specified domain and type already exists, then the new
           entry will overwrite it.  If you want to know beforehand whether or not an entry
           exists under a specific domain and type, use the entry_exists method.

           Returns the Rose::DB::Registry::Entry object added.

       dump
           Returns a reference to a hash containing information about all registered data
           sources.  The hash is structured like this:

               {
                 domain1 =>
                 {
                   type1 =>
                   {
                     # Rose::DB::Registry::Entry attributes
                     # generated by its dump() method
                     driver   => ...,
                     database => ...,
                     host     => ...,
                     ...
                   },

                   type2 =>
                   {
                     ...
                   },
                   ...
                 },

                 domain2 =>
                 {
                   ...
                 },

                 ...
               }

           All the registry entry attribute values are copies, not the actual values.

       delete_domain DOMAIN
           Delete an entire domain, including all the registry entries under that domain.

       delete_entry PARAMS
           Delete the registry entry specified by PARAMS, where PARAMS must be name/value pairs
           with defined values for "domain" and "type".  A fatal error will occur if either one
           is missing or undefined.

           If the specified entry does not exist, undef is returned.  Otherwise, the deleted
           entry is returned.

       entry PARAMS
           Get the registry entry specified by PARAMS, where PARAMS must be name/value pairs with
           defined values for "domain" and "type".  A fatal error will occur if either one is
           missing or undefined.  If the specified entry does not exist, undef is returned.

       entry_exists PARAMS
           Returns true if the registry entry specified by PARAMS exists, false otherwise.
           PARAMS must be name/value pairs with defined values for "domain" and "type".  A fatal
           error will occur if either one is missing or undefined.

       registered_types DOMAIN
           Returns a list (in list context) or reference to an array (in scalar context) of the
           names of all registered types under the domain named DOMAIN.

       registered_domains
           Returns a list (in list context) or reference to an array (in scalar context) of the
           names of all registered domains.

AUTHOR

       John C. Siracusa (siracusa@gmail.com)

LICENSE

       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This program is free
       software; you can redistribute it and/or modify it under the same terms as Perl itself.