NAME

Net::Analysis::Listener::Base - base class for event listeners

SYNOPSIS

This module should be subclassed as follows:

  package Net::Analysis::Listener::MyThing;

  use base 'Net::Analysis::Listener::Base';

  sub event_listener {
    my ($self, $args_hash) = @_;
    ... do something ...

    if (event_is_exciting($args_hash)) {
      $self->emit (name => 'my_event',
                   args => {what => 'listeners to this event will get'});
    }
  }

DESCRIPTION

This module is a virtual base class for Listeners. To create a new listener, just subclass this, and add methods. If you want to listen to an event, create a method with the name of that event - the dispatcher takes care of the rest.

If you want to store state between events (such as a hash of open sessions), stuff it into $self. Any configuration for your listener will also be exploded all over $<$self>, so take care. Subclasses can use anything in $self they want, except the key '_', which contains private stuff used by the base class.

You can emit events if you like; if you add new types of event, take care not to collide with existing ones (e.g. tcp_blah, http_blah). The best way to do this is to select a prefix for your event names based on your protocol.

INHERITED METHODS

You should just inherit these methods, you don't need to implement them. They're documented here for reference, so don't be put off - they can be safely ignored :)

new (dispatcher => $obj [, config => $hash] [, pos => 'first|last'])

Mandatory argument is the dispatcher object which will dispatch any events that originate from this module, or any that subclass from it.

Note that we immediately register this new object with the dispatcher; this will create circular references.

The config hash is optional. Standard key/val pairs are:

 * v => 0..3 (verbosity; 0==silent, 9==noisy)

The pos parameter is optional. It specifies if the listener sould catch events first, or last. Only one listener can be first, or last.

The rest of the hash varies on a per-listener basis.

The returned object has one reserved field: "$self-"{_}>. This is used for the behind-the-scenes plumbing. All other fields in $self are free for the subclass to use.

Note that the config hash is exploded over $self; that is, "$self-"{v}> will contain the verbosity value passed in via the config hash (or a default, if no config is passed in.)

emit (...)

This is a convenience wrapper on top of Net::Analysis::Dispatcher::emit_event. It takes exactly the same arguments. Please refer to that module for documentation.

EXPORT

None by default.

AUTHOR

Adam B. Worrall, <worrall@cpan.org>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.