root/trunk/RBTelepathy/RBTelepathy/Connection.py

#!/usr/bin/env python
##~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
##~ License 
##~ 
##- The RuneBlade Foundation library is intended to ease some 
##- aspects of writing intricate Jabber, XML, and User Interface (wxPython, etc.) 
##- applications, while providing the flexibility to modularly change the 
##- architecture. Enjoy.
##~ 
##~ Copyright (C) 2002  TechGame Networks, LLC.
##~ 
##~ This library is free software; you can redistribute it and/or
##~ modify it under the terms of the BSD style License as found in the 
##~ LICENSE file included with this distribution.
##~ 
##~ TechGame Networks, LLC can be reached at:
##~ 3578 E. Hartsel Drive #211
##~ Colorado Springs, Colorado, USA, 80920
##~
##~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

"""
A Connection is the intermediatary between packet handlers and the
protocol.  OnStreamPacket distributes inbound packets based on packet type
and namespace to the registered packet handler.  Packet handlers
registrations are managed with the LoadHandler and UnloadHandler methods.
In this way, new features and functionality can be added within the
framework by simply extending the packet handler table.

The Connection is also the central repository for sharing state information
between packet handlers.  So, common information like login id can be found
here, or a few steps from here.

Related Packages:
    Packet
    Stream
"""

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#~ Imports 
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

from __future__ import generators
import logging
import weakref

import ErrorTypes

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#~ Definitions 
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

class Connection(object):
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    #~ Constants / Variables / Etc. 
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    log = logging.getLogger('Connection')
    StreamPacketHandlers = {}
    RoutedPacketHandlers = {}

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    #~ Public Methods 
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def __init__(self):
        self.StreamPacketHandlers = self.StreamPacketHandlers.copy()
        self.RoutedPacketHandlers = self.RoutedPacketHandlers.copy()

    #~ Connection Operations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def LoadDefaultHandlers(self):
        pass

    def Shutdown(self, *args, **kw):
        raise NotImplementedError

    def SendPacket(self, *args, **kw):
        raise NotImplementedError

    #~ Handler Management ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    
    def LoadHandler(self, HandlerFactory, *args, **kw):
        try:
            connection = weakref.proxy(self)
            handler = HandlerFactory(connection, *args, **kw)
            self.protocol.packetbuilder.AddElementFactories(handler.ElementFactories)
            for key in handler.StreamPacketHandlers:
                self.StreamPacketHandlers[key] = handler
            for key in handler.RoutedPacketHandlers:
                self.RoutedPacketHandlers[key] = handler
            return handler
        except ErrorTypes.RBTelepathyError, e: 
            raise
        except:
            self.log.critical('Unexpected error loading handler %r', HandlerFactory, exc_info=1)
            raise

    def UnloadHandler(self, handler):
        try:
            self.protocol.packetbuilder.RemoveElementFactories(handler.ElementFactories)
            for key in handler.StreamPacketHandlers:
                try: del self.StreamPacketHandlers[key]
                except KeyError: pass
            for key in handler.RoutedPacketHandlers:
                try: del self.RoutedPacketHandlers[key]
                except KeyError: pass
        except ErrorTypes.RBTelepathyError, e: 
            raise
        except:
            self.log.critical('Unexpected error unloading handler %r', handler, exc_info=1)
            raise

    #~ Event Methods ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def OnRoutedPacket(self, packet, *args, **kw):
        self.log.debug('Received Routed packet (%s, %s)', packet.namespace, packet.node)

        # Lookup our packet handler
        for nodeidx in self._GetPacketHandlerIndices((packet.namespace, packet.node)):
            packethandler = self.RoutedPacketHandlers.get(nodeidx, None)
            if packethandler is not None: break
        else:
            raise ErrorTypes.RoutedHandlerError("No RoutedPacketHandler for (%s, %s)" % (packet.namespace, packet.node))

        return packethandler.OnRoutedPacket(packet, *args, **kw)

    def OnStreamPacket(self, packet, *args, **kw):
        self.log.debug('Received Stream packet (%s, %s)', packet.namespace, packet.node)

        # Lookup our packet handler
        for nodeidx in self._GetPacketHandlerIndices((packet.namespace, packet.node)):
            packethandler = self.StreamPacketHandlers.get(nodeidx, None)
            if packethandler is not None: break
        else:
            raise ErrorTypes.PacketHandlerError("No StreamPacketHandler for (%s, %s)" % (packet.namespace, packet.node))

        return packethandler.OnStreamPacket(packet, *args, **kw)

    def OnShutdown(self, how):
        self.log.debug('Stream shutdown by "%s"', how)

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    #~ Protected Methods 
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def _GetPacketHandlerIndices(self, (namespace, node)):
        yield (namespace, node)
        yield (namespace, )
        yield node
        yield None