/ 
cPanel-TaskQueue-0.606
River stage zero No dependents
/ cPanel::TaskQueue::PluginManager

NAME

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

VERSION

This document describes cPanel::TaskQueue::PluginManager version 0.606.

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();

DESCRIPTION

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

INTERFACE

The interface for this module consists of three functions.

cPanel::TaskQueue::PluginManager::load_plugins( $dir, $namespace )

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

root_dir

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

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.

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

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:

directories

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

namespaces

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

This method just calls the 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 cPanel::TaskQueue::Plugin, Site::Tasks, cPanel::Backup::Tasks).

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

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.

cPanel::TaskQueue::PluginManager::list_loaded_plugins()

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

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.

DIAGNOSTICS

No directory list supplied.

load_all_plugins was called without a directories parameter.

No namepsace list supplied.

load_all_plugins was called without a namespaces parameter.

No directory supplied for finding plugins.

load_plugins was called without the required rootdir parameter.

Supplied directory '%s' does not exist.

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

Supplied directory '%s' not part of Perl's include path.

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

No namespace for plugins specified.

load_plugins was called without the required namespace parameter.

Namespace '%s' not a valid Perl namespace.

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

Failed to load '%s' plugin: %s

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

Plugin '%s' not registered, no 'to_register' method.

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

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

Plugin '%s': invalid registration entry

The to_register package method of the named plugin returned data that was inconsistent with registering a 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 TaskQueue plugin or the to_register method needs to be fixed.

Plugin '%s' register failed: %s

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

CONFIGURATION AND ENVIRONMENT

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

DEPENDENCIES

cPanel::TaskQeue

SEE ALSO

cPanel::TaskQueue::TaskProcessor

INCOMPATIBILITIES

None reported.

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.

AUTHOR

G. Wade Johnson wade@cpanel.net

LICENCE AND COPYRIGHT

Copyright (c) 2014, cPanel, Inc. All rights reserved.

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

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.