=head1 NAME

Cpanel::TaskQueue::PluginManager - Supplies support for loading the Queue task processing plugins.

=head1 VERSION

This document describes C<Cpanel::TaskQueue::PluginManager> version 0.307.

=head1 SYNOPSIS

   use Cpanel::TaskQueue::PluginManager;

   # Loads the modules found in '/usr/local/cpanel/Cpanel/TaskQueue/Plugin' assuming their
   #  names are Cpanel::TaskQueue::Plugin::*.
   Cpanel::TaskQueuePlugin::Manager::load_plugins( '/usr/local/cpanel', 'Cpanel::TaskQueue::Plugin' );

   # If you have multiple directories and/or namespaces, you can use the convenience method
   #   Smart enough not to try to reload any that already match.
   Cpanel::TaskQueue::PluginManager::load_all_plugins(
       directories => [ '/usr/local/cpanel', '.', '/home/fred/tasks' ],
       namespaces => [ 'Cpanel::TaskQueue::Plugin', 'MyHandlers' ]
    );

    my @loaded = Cpanel::TaskQueue::PluginManager::list_loaded_plugins();

=head1 DESCRIPTION

This module wraps up the logic to load any modules located in a particular
directory as plugins for the L<Cpanel::TaskQueue> class. It also registers them
with that class.

=head1 INTERFACE

The interface for this module consists of three functions.

=over 4

=item Cpanel::TaskQueue::PluginManager::load_plugins( $dir, $namespace )

This function loads all modules described by the supplied parameters and attempts to
register them with C<Cpanel::TaskQueue>. The two required parameters are

=over 4

=item I<root_dir>

The I<root_dir> required parameter defines a directory used to find plugins. I<root_dir>
must be in C<@INC> in order for perl to load the plugin modules.

=item I<namespace>

This parameter specifies the namespace in which to find the plugin module. The
namespace is needed to properly resolve the name of the module.

=back

The actual directory where the plugin modules are located is made by combining
the I<root_dir> and I<namespace> the same way Perl does. The '::' characters in
the namespace are replaced with path separators. This relative path is combined
with the I<root_dir> to create the actual path we search.

=item Cpanel::TaskQueue::PluginManager::load_all_plugins( directories => $dirs, namespaces => $ns )

This function helps to deal with distributed sets of plugins. It requires two
named arguments:

=over 4

=item I<directories>

A reference to an array of root directories. These directories are used as the
I<root_dir> parameter to the C<load_plugins> method.

=item I<namespaces>

A reference to an array of namespaces. These namespaces are used as the I<namespace>
parameter to the C<load_plugins> method.

=back

This method just calls the C<load_plugins> function with every combination of
directory and namespace supplied. This allows multiple directories (maybe system,
site, and special) to be searched for plugins. The plugins may also be separated
into multiple namespaces (maybe C<Cpanel::TaskQueue::Plugin>, C<Site::Tasks>,
C<Cpanel::Backup::Tasks>).

Using the examples above, would generate 9 different locations to search for
plugins and load any found in those locations.

=item Cpanel::TaskQueue::PluginManager::load_plugin_by_name( $module_name )

Loads only the plugin defined by the specified full Perl module name. The
directory containing the module must already be part of the Perl path.

Returns a true value is successful and a false value otherwise.

=item Cpanel::TaskQueue::PluginManager::list_loaded_plugins()

Returns a list of the names of the loaded plugins in no particular order.

=item Cpanel::TaskQueue::PluginManager::get_plugins_hash()

Returns a reference to a hash listing the loaded plugins. The hash maps the
module names of loaded plugins to an anonymous array of the commands that the
module provides.

=back

=head1 DIAGNOSTICS

=over

=item C<< No directory list supplied. >>

C<load_all_plugins> was called without a I<directories> parameter.

=item C<< No namepsace list supplied. >>

C<load_all_plugins> was called without a I<namespaces> parameter.

=item C<< No directory supplied for finding plugins. >>

C<load_plugins> was called without the required I<rootdir> parameter.

=item C<< Supplied directory '%s' does not exist. >>

The root directory parameter passed to C<load_plugins> was not a valid directory.

=item C<< Supplied directory '%s' not part of Perl's include path. >>

The root directory parameter passed to C<load_plugins> is not part of Perl's
include path. Plugins in that directory will not be able to be loaded.

=item C<< No namespace for plugins specified. >>

C<load_plugins> was called without the required I<namespace> parameter.

=item C<< Namespace '%s' not a valid Perl namespace. >>

The string passed to C<load_plugins> as a namespace is not a valid namespace.

=item C<< Failed to load '%s' plugin: %s >>

Attempting to load the named plugin module failed for the reason given.

=item C<< Plugin '%s' not registered, no 'to_register' method. >>

The named plugin does not supply the C<to_register> package method. Without
this method, we cannot register the plugin with the C<Cpanel::TaskQueue>
module.

This may mean that the named module is intended to be a C<TaskQueue> plugin. 

=item C<< Plugin '%s': invalid registration entry >>

The C<to_register> package method of the named plugin returned data that was
inconsistent with registering a C<TaskQueue> plugin. This method is expected to
return a list of arrayrefs. Each of these arrayrefs should be a two item list.

Either the named module is not a C<TaskQueue> plugin or the C<to_register> method
needs to be fixed.

=item C<< Plugin '%s' register failed: %s >>

Registering a command returned by C<to_register> failed for the reason given.

=back

=head1 CONFIGURATION AND ENVIRONMENT

Cpanel::TaskQueue::PluginManager requires no configuration files or environment
variables.

=head1 DEPENDENCIES

Cpanel::TaskQeue

=head1 SEE ALSO

Cpanel::TaskQueue::TaskProcessor

=head1 INCOMPATIBILITIES

None reported.

=head1 BUGS AND LIMITATIONS

At present, this module does not have any support for enabling/disabling individual
plugins.  That will probably be an important feature at some point.

=head1 AUTHOR

G. Wade Johnson  C<< wade@cpanel.net >>

=head1 LICENCE AND COPYRIGHT

Copyright (c) 2009, CPanel. All rights reserved.

This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See L<perlartistic>.

=head1 DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.