NAME

       POE::Component::Jabber::Protocol - A base class for implementing protocol differences

SYNOPSIS

       Inherit from this base class when implementing specifc protocol extentions that may exist
       when writing to support various other jabber server implementations.

DESCRIPTION

       PCJ::Protocol is the base class used when differences between authentication or other
       connection initialization methods require special processing.

       A prime example is JABBER(tm) vs. XMPP. The Jabber protocol uses a much different method
       to authenticate (ie. using the iq:auth namespace) than XMPP which uses SASL. While the
       rest of the protocol is substantially unchanged, these differences mean they must be
       accounted. In the 1.x versions of PCJ, this was solved by having different duplicate
       classes in the same domain with these differences manifest. It led to lots of headaches if
       there was a problem because it then needed to be fixed in four places.

       The solution is to keep the core aspect of PCJ immutable, while loading separate
       individual Protocol classes that then implement the details for each specific dialect.

       As an end developer, if you wish to add support for another dialect (ie.  support another
       jabber server implementation that does service management differently), subclass from this
       module and then add your entry into the ProtocolFactory.

       Also be aware that PCJ uses object_states to construct its own session.  Protocol
       subclassees are expected to fit smoothly into that. See the METHOD get_states() for more
       information.

       And remember when you are finished handling the protocol specifics and the connection is
       finished, fire off the PCJ_INIT_FINISHED status, and call relinquish_states() from the
       $_[HEAP] object to return control back to the PCJ Core. (Yes, you read that correctly,
       $_[HEAP] is actually the PCJ object).

       If in doubt, please see the source code for the other Protocol subclasses (ie.  XMPP.pm,
       J14.pm, etc).

METHODS

       At a bare minimum, some methods must be implemented by the end developer. These will be
       indicated with a MANDATORY flag.

       new() [OPTIONAL]
           new() provides a default constructor. It returns a hash reference blessed into the
           provided class

       get_version() [MANDATORY]
           get_version() is used by PCJ to populate the 'version' attribute in the opening
           <stream:stream/>. For XMPP enabled clients, this must return '1.0'. For legacy Jabber
           connections, it should return '0.9' but it isn't required. For all other applications,
           see the appropriate RFC for details on what version it expects.

       get_xmlns() [MANDATORY]
           get_xmlns() is used by PCJ to populate the default XML namespace attribute in the
           opening <stream:stream/>. Please feel free to use the constants in
           POE::Filter::XML::NS to provide this.

       get_states() [MANDATORY]
           get_states is used by PCJ to fill its object_states with the Protocol states.  An
           array reference containing event names should be returned that corespond one-to-one
           with the methods you implement in your subclass. Or if a mapping is required, a hash
           reference should be returned that includes the mapping. See POE::Session for more
           detail on object_states.

       get_input_event() [MANDATORY]
           get_input_event() returns the main entry point event into the Protocol subclass. This
           is then used by PCJ to assign the event to the Wheel, so that the Protocol's events
           get fired from Wheel events.

       get_error_event() [OPTIONAL]
           get_error_event() returns the event to be called when an error occurs in the Wheel.
           Typically, this isn't required for Protocol subclasses, but is available if needed.

       get_flushed_event() [OPTIONAL]
           get_flushed_event() returns the event to be called when the flushed event occurs in
           the Wheel. Typically, this isn't required for Protocol subclasses, but is available if
           needed.

NOTES

       Here are some quick tips to keep in mind when subclassing:

       Protocol subclassees execute within the same Session space as PCJ $_[HEAP] contains the
       PCJ object.  If you need storage space, use $_[OBJECT] (ie. yourself).  Send status
       events. See PCJ::Status Don't forget to send PCJ_READY.  And don't forget to call
       $_[HEAP]->relinquish_states() when finished.  When in doubt, use the source!

AUTHOR

       Copyright (c) 2007-2009 Nicholas Perez. Distributed under the GPL.