callbacks results from the CPAN

DJabberd

=head1 NAME

DJabberd::Agent - Abstract base class representing a software agent that talks XMPP

=head1 SYNOPSIS

New agents are created by making a sub-class of this class. C<set_config_...> methods can
be provided to add configuration options, which will then be supported both on this class's
constructor and in a configuration file when adding your agent to a VHost as a delivery plugin.

    package MyAgent;
    
    use base qw(DJabberd::Agent);
    
    sub handles_destination {
        my ($self, $to_jid, $vhost) = @_;
        
        return ($to_jid->domain eq 'example.com' && $to_jid->node eq 'blah') ? 1 : 0;
    }
    
    sub handle_message {
        my ($self, $vhost, $stanza) = @_;
        my $response = $stanza->make_response();
        my $message = $self->{message} || "Hello, world!";
        $response->set_raw("<body>".DJabberd::Util::exml($message)."</body>");
        $response->deliver($vhost);
    }
    
    sub set_config_message {
        my ($self, $message) = @_;
        $self->{message} = $message;
    }

The following example shows how you might load the above agent class as a plugin:

    <Plugin MyAgent>
        Message Kumquats are groovy!
    </Plugin>

It is also possible to use an instance directly as an object, to delegate stanza handling
from another delivery plugin:

    my $agent = MyAgent->new(
        message => "Kumquats are groovy!",
    );
    $agent->handle_stanza($vhost, $stanza);

In this case, the caller will need to handle the delivery hook callbacks itself
in an appropriate manner, but it can be assumed that a call to C<handle_stanza>
will always "deliver" the stanza in some sense.

=head1 DESCRIPTION

This module is the basis for several other higher-level DJabberd classes which provide
an API for creating software agents that communicate over XMPP. This includes components
which serve an entire domain (see L<DJabberd::Component>) and bot-like nodes which
respond only to a specific node name in a domain (see L<DJabberd::Agent::Node>).

It is unlikely that other classes will inherit from this class directly. Most users
should inherit from one of the higher-level subclasses depending on what sort of
agent they wish to create. This class provides the basic machinery for handling
stanzas which all agents can use.

=head1 API

The API of this class is normally used by overriding certain methods in a subclass.
In many cases it is useful for these overriding methods to call into the base class
versions to get certain useful default functionality.

The C<handles_destination> method is the most important methods for inheritors to
override, since incoming stanzas will only be delivered to your class if this
method returns true the given destination JID.

It is assumed that if a true value is returned from this method you will handle the
incoming stanza in one way or another; this implies that in most cases you should
reply with some sort of error message if the stanza is unnacceptable in some way.

The more specialized abstract subclasses of this class will generally implement
C<handles_destination> in a way that is appropriate for their role, so users
of these subclasses will not need to override this method.

=cut

package DJabberd::Agent;
use base qw(DJabberd::Delivery);
use strict;
use warnings;
use DJabberd::Util qw(exml);
use DJabberd::JID;
use DJabberd::Log;

our $logger = DJabberd::Log->get_logger();

=head2 handle_stanza($self, $vhost, $stanza)

This method is the "entry point" of this class, and is called when a stanza is received
which this agent expressed a desire to handle. The default implementation dispatches
to one of the higher-level C<handle_...> methods depending on the type of stanza that
has been recieved. At present, only IQ, Message and Presence stanzas are supported.

Inheritors can override this method to do low-level stanza processing, but unless
the version from this class is invoked the higher-level processing methods will
cease to operate.

Callers that are using an agent instance as an object directly rather than having
it attached to a VHost as a plugin will generally call this method directly to
delegate stanza processing. In this case, it is the caller's responsibility to ensure
that the stanza is suitable for this agent; for example, the caller could make a call
( run in 0.982 second using v1.01-cache-2.11-cpan-75ffa21a3d4 )