NAME
   Object::Pluggable - A base class for creating plugin-enabled objects

SYNOPSIS
    # A simple POE Component that sends ping events to registered sessions
    # and plugins every second.

    {
        package SimplePoCo;

        use strict;
        use warnings;
        use base qw(Object::Pluggable);
        use POE;
        use Object::Pluggable::Constants qw(:ALL);

        sub spawn {
            my ($package, %opts) = @_;
            my $self = bless \%opts, $package;

            $self->_pluggable_init(
                prefix => 'simplepoco_',
                types  => [qw(EXAMPLE)],
                debug  => 1,
            );

            POE::Session->create(
                object_states => [
                    $self => { shutdown => '_shutdown' },
                    $self => [qw(_send_ping _start register unregister __send_event)],
                ],
            );

            return $self;
        }

        sub shutdown {
            my ($self) = @_;
            $poe_kernel->post($self->{session_id}, 'shutdown');
        }

        sub _pluggable_event {
            my ($self) = @_;
            $poe_kernel->post($self->{session_id}, '__send_event', @_);
        }

        sub _start {
            my ($kernel, $self) = @_[KERNEL, OBJECT];
            $self->{session_id} = $_[SESSION]->ID();

            if ($self->{alias}) {
                $kernel->alias_set($self->{alias});
            }
            else {
                $kernel->refcount_increment($self->{session_id}, __PACKAGE__);
            }

            $kernel->delay(_send_ping => $self->{time} || 300);
            return;
        }

        sub _shutdown {
             my ($kernel, $self) = @_[KERNEL, OBJECT];

             $self->_pluggable_destroy();
             $kernel->alarm_remove_all();
             $kernel->alias_remove($_) for $kernel->alias_list();
             $kernel->refcount_decrement($self->{session_id}, __PACKAGE__) if !$self->{alias};
             $kernel->refcount_decrement($_, __PACKAGE__) for keys %{ $self->{sessions} };

             return;
        }

        sub register {
            my ($kernel, $sender, $self) = @_[KERNEL, SENDER, OBJECT];
            my $sender_id = $sender->ID();
            $self->{sessions}->{$sender_id}++;

            if ($self->{sessions}->{$sender_id} == 1) {
                $kernel->refcount_increment($sender_id, __PACKAGE__);
                $kernel->yield(__send_event => 'simplepoco_registered', $sender_id);
            }

            return;
        }

        sub unregister {
            my ($kernel, $sender, $self) = @_[KERNEL, SENDER, OBJECT];
            my $sender_id = $sender->ID();
            my $record = delete $self->{sessions}->{$sender_id};

            if ($record) {
                $kernel->refcount_decrement($sender_id, __PACKAGE__);
                $kernel->yield(__send_event => 'simplepoco_unregistered', $sender_id);
            }

            return;
        }

        sub __send_event {
            my ($kernel, $self, $event, @args) = @_[KERNEL, OBJECT, ARG0..$#_];

            return 1 if $self->_pluggable_process(EXAMPLE => $event, \@args) == PLUGIN_EAT_ALL;
            $kernel->post($_, $event, @args) for keys %{ $self->{sessions} };
        }

        sub _send_ping {
            my ($kernel, $self) = @_[KERNEL, OBJECT];

            $kernel->yield(__send_event => 'simplepoco_ping', 'Wake up sleepy');
            $kernel->delay(_send_ping => $self->{time} || 1);
            return;
        }
    }

    {
        package SimplePoCo::Plugin;
        use strict;
        use warnings;
        use Object::Pluggable::Constants qw(:ALL);

        sub new {
            my $package = shift;
            return bless { @_ }, $package;
        }

        sub plugin_register {
            my ($self, $pluggable) = splice @_, 0, 2;
            print "Plugin added\n";
            $pluggable->plugin_register($self, 'EXAMPLE', 'all');
            return 1;
        }

        sub plugin_unregister {
            print "Plugin removed\n";
            return 1;
        }

        sub EXAMPLE_ping {
            my ($self, $pluggable) = splice @_, 0, 2;
            my $text = ${ $_[0] };
            print "Plugin got '$text'\n";
            return PLUGIN_EAT_NONE;
        }
    }

    use strict;
    use warnings;
    use POE;

    my $pluggable = SimplePoCo->spawn(
        alias => 'pluggable',
        time  => 1,
    );

    POE::Session->create(
        package_states => [
            main => [qw(_start simplepoco_registered simplepoco_ping)],
        ],
    );

    $poe_kernel->run();

    sub _start {
        my $kernel = $_[KERNEL];
        $kernel->post(pluggable => 'register');
        return;
    }

    sub simplepoco_registered {
        print "Main program registered for events\n";
        my $plugin = SimplePoCo::Plugin->new();
        $pluggable->plugin_add('TestPlugin', $plugin);
        return;
    }

    sub simplepoco_ping {
        my ($heap, $text) = @_[HEAP, ARG0];
        print "Main program got '$text'\n";
        $heap->{got_ping}++;
        $pluggable->shutdown() if $heap->{got_ping} == 3;
        return;
    }

DESCRIPTION
   Object::Pluggable is a base class for creating plugin enabled objects.
   It is a generic port of POE::Component::IRC's plugin system.

   If your object dispatches events to listeners, then Object::Pluggable
   may be a good fit for you.

   Basic use would involve subclassing Object::Pluggable, then overriding
   "_pluggable_event()" and inserting "_pluggable_process()" wherever you
   dispatch events from.

   Users of your object can then load plugins using the plugin methods
   provided to handle events generated by the object.

   You may also use plugin style handlers within your object as
   "_pluggable_process()" will attempt to process any events with local
   method calls first. The return value of these handlers has the same
   significance as the return value of 'normal' plugin handlers.

PRIVATE METHODS
   Subclassing Object::Pluggable gives your object the following 'private'
   methods:

 "_pluggable_init"
   This should be called on your object after initialisation, but before
   you want to start processing plugins. It accepts a number of
   argument/value pairs:

    'types', an arrayref of the types of events that your poco will support,
             OR a hashref with the event types as keys and their abbrevations
             (used as plugin event method prefixes) as values. This argument is
             mandatory.

    'prefix', the prefix for your events (default: 'pluggable_');
    'reg_prefix', the prefix for the register()/unregister() plugin methods
                  (default: 'plugin_');
    'debug', a boolean, if true, will cause a warning to be printed every time a
             plugin call fails.

   Notes: 'prefix' should probably end with a '_'. The types specify the
   prefixes for plugin handlers. You can specify as many different types as
   you require.

 "_pluggable_destroy"
   This should be called from any shutdown handler that your poco has. The
   method unloads any loaded plugins.

 "_pluggable_process"
   This should be called before events are dispatched to interested
   sessions. This gives pluggable a chance to discard events if requested
   to by a plugin.

   The first argument is a type, as specified to "_pluggable_init()".

    sub _dispatch {
        my ($self, $event, $type, @args) = @_;

        # stuff

        my $type = ...

        return 1 if $self->_pluggable_process($type, $event, \@args)) == PLUGIN_EAT_ALL;

        # dispatch event to interested sessions.
    }

   A reference to the argument array is passed. This allows the plugin
   system to mangle the arguments or even add new ones.

 "_pluggable_event"
   This method should be overridden in your class so that pipeline can
   dispatch events through your event dispatcher. Pipeline sends a prefixed
   'plugin_add' and 'plugin_del' event whenever plugins are added or
   removed, respectively. A prefixed 'plugin_error' event will be sent if a
   plugin a) raises an exception, b) fails to return a true value from its
   register/unregister methods, or c) fails to return a valid EAT constant
   from a handler.

    sub _pluggable_event {
        my $self = shift;
        $poe_kernel->post($self->{session_id}, '__send_event', @_);
    }

   There is an example of this in the SYNOPSIS.

PUBLIC METHODS
   Subclassing Object::Pluggable gives your object the following public
   methods:

 "pipeline"
   Returns the Object::Pluggable::Pipeline object.

 "plugin_add"
   Accepts two arguments:

    The alias for the plugin
    The actual plugin object
    Any number of extra arguments

   The alias is there for the user to refer to it, as it is possible to
   have multiple plugins of the same kind active in one Object::Pluggable
   object.

   This method goes through the pipeline's "push()" method, which will call
   "$plugin->plugin_register($pluggable, @args)".

   Returns the number of plugins now in the pipeline if plugin was
   initialized, "undef"/an empty list if not.

 "plugin_del"
   Accepts the following arguments:

    The alias for the plugin or the plugin object itself
    Any number of extra arguments

   This method goes through the pipeline's "remove()" method, which will
   call "$plugin->plugin_unregister($pluggable, @args)".

   Returns the plugin object if the plugin was removed, "undef"/an empty
   list if not.

 "plugin_get"
   Accepts the following arguments:

    The alias for the plugin

   This method goes through the pipeline's "get()" method.

   Returns the plugin object if it was found, "undef"/an empty list if not.

 "plugin_list"
   Takes no arguments.

   Returns a hashref of plugin objects, keyed on alias, or an empty list if
   there are no plugins loaded.

 "plugin_order"
   Takes no arguments.

   Returns an arrayref of plugin objects, in the order which they are
   encountered in the pipeline.

 "plugin_register"
   Accepts the following arguments:

    The plugin object
    The type of the hook (the hook types are specified with _pluggable_init()'s 'types')
    The event name[s] to watch

   The event names can be as many as possible, or an arrayref. They
   correspond to the prefixed events and naturally, arbitrary events too.

   You do not need to supply events with the prefix in front of them, just
   the names.

   It is possible to register for all events by specifying 'all' as an
   event.

   Returns 1 if everything checked out fine, "undef"/an empty list if
   something is seriously wrong.

 "plugin_unregister"
   Accepts the following arguments:

    The plugin object
    The type of the hook (the hook types are specified with _pluggable_init()'s 'types')
    The event name[s] to unwatch

   The event names can be as many as possible, or an arrayref. They
   correspond to the prefixed events and naturally, arbitrary events too.

   You do not need to supply events with the prefix in front of them, just
   the names.

   It is possible to register for all events by specifying 'all' as an
   event.

   Returns 1 if all the event name[s] was unregistered, undef if some was
   not found.

PLUGINS
   The basic anatomy of a pluggable plugin is:

    # Import the constants, of course you could provide your own
    # constants as long as they map correctly.
    use Object::Pluggable::Constants qw( :ALL );

    # Our constructor
    sub new {
        ...
    }

    # Required entry point for pluggable plugins
    sub plugin_register {
        my($self, $pluggable) = @_;

        # Register events we are interested in
        $pluggable->plugin_register($self, 'SERVER', qw(something whatever));

        # Return success
        return 1;
    }

    # Required exit point for pluggable
    sub plugin_unregister {
        my($self, $pluggable) = @_;

        # Pluggable will automatically unregister events for the plugin

        # Do some cleanup...

        # Return success
        return 1;
    }

    sub _default {
        my($self, $pluggable, $event) = splice @_, 0, 3;

        print "Default called for $event\n";

        # Return an exit code
        return PLUGIN_EAT_NONE;
    }

   As shown in the example above, a plugin's "_default" subroutine (if
   present) is called if the plugin receives an event for which it has no
   handler.

   The special exit code CONSTANTS are documented in
   Object::Pluggable::Constants. You could provide your own as long as the
   values match up, though.

TODO
   Better documentation >:]

AUTHOR
   Chris 'BinGOs' Williams <[email protected]>

LICENSE
   Copyright "(c)" Chris Williams, Apocalypse, Hinrik Örn Sigurðsson and
   Jeff Pinyan

   This module may be used, modified, and distributed under the same terms
   as Perl itself. Please see the license that came with your Perl
   distribution for details.

KUDOS
   APOCAL for writing the original POE::Component::IRC plugin system.

   japhy for writing POE::Component::IRC::Pipeline which improved on it.

   All the happy chappies who have contributed to POE::Component::IRC over
   the years (yes, it has been years) refining and tweaking the plugin
   system.

   The initial idea was heavily borrowed from X-Chat, BIG thanks go out to
   the genius that came up with the EAT_* system :)

SEE ALSO
   POE::Component::IRC

   Object::Pluggable::Pipeline

   Both POE::Component::Client::NNTP and POE::Component::Server::NNTP use
   this module as a base, examination of their source may yield further
   understanding.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.