Provided by: libbadger-perl_0.16-2_all 
NAME
Badger::Hub - central repository of shared resources
SYNOPSIS
use Badger::Hub;
# do the happy badger dance!
INTRODUCTION
This documentation describes the "Badger::Hub" object. A hub sits in the middle of a
Badger application, providing a central point of access to the various other modules,
components and sub-system that an application uses.
You generally don't need to worry about the "Badger::Hub" if you're just a casual user of
the Badger modules. It will primarily be of interest to developers who are building their
own badger-powered applications or extensions.
At present this module is quite basic. It will be developed further in due course.
DESCRIPTION
A "Badger::Hub" object is a central repository of shared resources for a Badger
application. The hub sits in the middle of an application and provides access to all the
individual components and larger sub-systems that may be required. It automatically loads
and instantiates these other modules on demand and caches then for subsequent use.
Components
The Badger::Hub base class currently has two components:
filesystem => Badger::Filesystem
codecs => Badger::Codecs
An "AUTOLOAD" method allows you to access any component by name. It will be loaded and
instantiated automatically. The "AUTOLOAD" method also generates the missing method so
that you can avoid the overhead of the "AUTOLOAD" method the next time you call it.
my $filesystem = $hub->filesystem;
You can add your own component to a hub and they will be available in the same way.
$hub->components( fuzzbox => 'My::Module::Fuzzbox' );
my $fuzzbox = $hub->fuzzbox;
Delegates
As well as accessing components directly, you can also make use of delegate methods that
get forwarded onto a component. For example, the hub "file()" method is just a short cut
to the "file()" method of the "filesystem" component (implemented by Badger::Filesystem).
$file = $hub->file('/path/to/file'); # the short cut
$file = $hub->filesystem->file('/path/to/file'); # the long way
You can easily define your own delegate methods.
$hub->delegates( warm_fuzz => 'fuzzbox' );
$fuzzed = $hub->warm_fuzz; # the short way
$fuzzed = $hub->fuzzbox->warm_fuzz; # the long way.
Subclassing Badger::Hub
You can subclass Badger::Hub to define your own collection of components and delegate
methods, as shown in the example below.
package My::Hub;
use Badger::Class
version => 0.01,
debug => 0,
base => 'Badger::Hub';
our $COMPONENTS = {
fuzzbox => 'My::Module::Fuzzbox',
flanger => 'My::Module::Flanger',
};
our $DELEGATES = {
warm_fuzz => 'fuzzbox',
dirty_noise => 'fuzzbox',
wide_flange => 'flanger',
wet_flange => 'flanger',
};
Circular References are a Good Thing
In some cases, sub-systems instantiated by a Badger::Hub will also maintain a reference
back to the hub. This allows them to access other sub-systems and components that they
require.
Note that this behaviour implicitly creates circular references between the hub and its
delegates. This is intentional. It ensures that the hub and delegates keep each other
alive until the hub is explicitly destroyed and the references are freed. Having the hub
stick around for as long as possible is usually a Good Thing. It acts as a singleton
providing a central point of access to the resources that your application uses (which is
a fancy way of saying it's like a global variable).
+-----+ +-----------+
| HUB |----->| COMPONENT |
| |<-----| |
+-----+ +-----------+
If you manually create a hub for whatever reason (and the cases where you would need to
are few and far between) then you are responsible for calling the destroy() method when
you're done with it. This will manually break the circular references and free up any
memory used by the hub and any delegates it is using. If you don't call the destroy()
method then the hub will remain alive until the end of the program when the memory will be
freed as usual. In most cases this is perfectly acceptable.
However, you generally don't need to worry about any of this because you wouldn't normally
create a hub manually. Instead, you would leave it up to the Badger façade (or "front-
end") module to do that behind the scenes. When you create a Badger module it implicitly
creates a "Badger::Hub" to use. When the Badger object goes out of scope its "DESTROY"
method automatically calls the hub's destroy method.
sub foo {
my $badger = Badger->new;
my $hub = $badger->hub;
# do something
# $badger object is freed here, that calls $hub->destroy
}
Because there is no reference from the hub back to the Badger façade object you don't have
to worry about circular references. The Badger object is correctly freed and that ensures
the hub gets cleaned up.
+--------+ +-----+ +-----------+
| BADGER |----->| HUB |----->| COMPONENT |
| | | |<-----| |
+--------+ +-----+ +-----------+
If you call "Badger" methods as class methods then they are forwarded to a prototype
object (effectively a singleton object). That in turn will use a prototype hub object.
In this case, both the "Badger" and "Badger::Hub" objects will exist until the end of the
program. This ensures that your class methods all Do the right Thing without you having
to worry about creating a Badger object.
# class method creates Badger prototype, which creates Badger::Hub
# prototype, which loads, instantiates and caches Badger::Filesystem
# which can then fetch the file
my $file = Badger->file('/path/to/file');
# later... reuse same Badger, Badger::Hub and Badger::Filesystem
my $dir = Badger->dir('/path/to/dir');
METHODS
new()
Constructor method used to create a new hub object.
$hub = Badger::Hub->new();
components()
This method can be used to get or set entries in the components table for the hub.
Components are other modules that the hub can delegate to.
# get components hash ref
my $comps = $hub->components;
# add new components
$hub->components({
fuzzbox => 'My::Module::Fuzzbox',
flanger => 'My::Module::Flanger',
});
component($name)
This method returns a single entry from the components table.
print $hub->component('fuzzbox'); # My::Module::Fuzzbox
delegates()
This method can be used to get or set entries in the delegates table for the hub. This
specifies which hub methods should be delegated to components.
# get delegates hash ref
my $delegs = $hub->delegates;
# add new delegates
$hub->delegates({
warm_fuzz => 'fuzzbox',
dirty_noise => 'fuzzbox',
wide_flange => 'flanger',
wet_flange => 'flanger',
});
delegate($name)
This method returns a single entry from the delegates table.
print $hub->delegate('warm_fuzz'); # fuzzbox
destroy()
This method can be manually called to destroy the hub and any components that it is using.
INTERNAL METHODS
construct($component,\%params)
This method configures and instantiates a component. The first argument is the component
name. This is mapped to a module via the component() method and the module is loaded. A
list of named parameters, or a reference to a hash array of named parameters may follow. A
reference to the hub is added to these as the "hub" item before forwarding them to the
constructor method for the component. The component is then cached for subsequent use.
# calling the construct() method like this...
$hub->construct( fuzzbox => { volume => 11 } );
# ...results in code equivalent to this:
use Your::Module::Fuzzbox;
Your::Module::Fuzzbox->new({ volume => 11, hub => $hub });
auto_can($name)
This method is installed as an auto_can handler which is called to resolved undefined
methods. If the method called matches the name of a component then it calls
auto_component() to generate a method to access the component. If it matches the name of
a delegate method then it calls auto_delegate() to generate a delegate method.
auto_component($name,$module)
This method generates a component method named $name which accesses an instance of the
$module component module.
auto_delegate($name,$component)
This method generates a delegate method named $name which delegates to the $name method of
the $component component.
config()
This method returns a reference to a Badger::Config object representing the configuration
for the hub. This is still marked experimental.
AUTHOR
Andy Wardley <http://wardley.org/>
COPYRIGHT
Copyright (C) 2001-2009 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.