NAME

DJabberd::Component - Abstract class representing a component in DJabberd

SYNOPSIS

    package MyPackage::DJabberd::MyComponent;
    use base DJabberd::Component;
    
    # Example of a component which accepts XEP-0050 Ad-Hoc Commands
    
    sub finalize {
        my ($self, $opts) = @_;
        
        # Let the parent class finalize
        $self->SUPER::finalize;
        
        $self->register_iq_handler(
            "set-{http://jabber.org/protocol/commands}command",
            sub { $self->handle_adhoc_command(@_) },
        );
    }
    
    sub handle_adhoc_command {
        my ($self, $vhost, $stanza) = @_;
        
        # handle the DJabberd::IQ stanza in $stanza,
        # or send some kind of error response.
    }

This class provides a parent class for all DJabberd components. Components that inherit from this class can then be used directly by the server as delivery plugins, or used directly by other classes.

See DJabberd::Component::Example for an example component implementation.

USAGE

This class is a specialization of DJabberd::Agent which is aimed at those wishing to create "components", which are software agents that handle an entire XMPP domain, including all of the nodes within that domain.

In most cases, users of this class will use the API exposed by DJabberd::Agent. However, there is some special behaviour to note and some additional methods that are not part of the basic agent class.

handles_destination($self, $to_jid, $vhost)

This class provides an overriden version of this method which responds with a true value if and only if the domain of the JID given matches the domain of the component itself. It is unlikely that you will need to override this.

handle_stanza($self, $vhost, $stanza)

The overriden version of this method has special behavior when dealing with stanzas that are addressed to nodes within the domain handled by your component. (That is, jids of the form user@example.com, rather than just example.com.)

When such a stanza is received, the get_node method will be called to retrieve an object representing that node.

If you wish to do low-level handling of all incoming stanzas, you may override this method. As with DJabberd::Agent, overriding this method will disable all of the higher-level handler methods unless you delegate to the overriden method.

If you would like to preserve the higher-level handler methods but not handle nodes as separate objects, you may like to override this method to call the original version from DJabberd::Agent as follows:

    sub handle_stanza {
        $self->DJabberd::Agent::handle_stanza(@_);
    }

With this method in place, the get_node method will no longer be used and all suitable stanzas will be passed to this instance's own handler methods regardless of the destination JID's node name.

get_node($self, $nodename)

Called when this class wants to find an agent to handle a given node within this component's domain.

Most normal implementations of this method will return an instance of a subclass of DJabberd::Agent::Node, but really any DJabberd::Agent subclass will do as long as it'll accept stanzas addressed to the nodename given.

vcard($self)

The overriden version of this method will return a vCard where the full name is set to the domain name of the component. Subclasses may override this to do something more fancy.

identities($self)

The overriden version of this method returns a single, generic identity which indicates that the component is a "branch" in the Service Discovery tree. This is included because some clients seem to get a little upset if a JID supports disco but has no identities.

SEE ALSO

See also DJabberd::Agent, DJabberd::Agent::Node.

COPYRIGHT

Copyright 2007-2008 Martin Atkins

This module is part of the DJabberd distribution and is covered by the distribution's overall licence.