--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/sat_pubsub/iidavoll.py	Thu May 17 12:48:14 2012 +0200
@@ -0,0 +1,585 @@
+# Copyright (c) 2003-2008 Ralph Meijer
+# See LICENSE for details.
+
+"""
+Interfaces for idavoll.
+"""
+
+from zope.interface import Attribute, Interface
+
+class IBackendService(Interface):
+    """ Interface to a backend service of a pubsub service. """
+
+
+    def __init__(storage):
+        """
+        @param storage: Object providing L{IStorage}.
+        """
+
+
+    def supportsPublisherAffiliation():
+        """ Reports if the backend supports the publisher affiliation.
+
+        @rtype: C{bool}
+        """
+
+
+    def supportsOutcastAffiliation():
+        """ Reports if the backend supports the publisher affiliation.
+
+        @rtype: C{bool}
+        """
+
+
+    def supportsPersistentItems():
+        """ Reports if the backend supports persistent items.
+
+        @rtype: C{bool}
+        """
+
+
+    def getNodeType(nodeIdentifier):
+        """ Return type of a node.
+
+        @return: a deferred that returns either 'leaf' or 'collection'
+        """
+
+
+    def getNodes():
+        """ Returns list of all nodes.
+
+        @return: a deferred that returns a C{list} of node ids.
+        """
+
+
+    def getNodeMetaData(nodeIdentifier):
+        """ Return meta data for a node.
+
+        @return: a deferred that returns a C{list} of C{dict}s with the
+                 metadata.
+        """
+
+
+    def createNode(nodeIdentifier, requestor):
+        """ Create a node.
+
+        @return: a deferred that fires when the node has been created.
+        """
+
+
+    def registerPreDelete(preDeleteFn):
+        """ Register a callback that is called just before a node deletion.
+
+        The function C{preDeletedFn} is added to a list of functions to be
+        called just before deletion of a node. The callback C{preDeleteFn} is
+        called with the C{nodeIdentifier} that is about to be deleted and
+        should return a deferred that returns a list of deferreds that are to
+        be fired after deletion. The backend collects the lists from all these
+        callbacks before actually deleting the node in question.  After
+        deletion all collected deferreds are fired to do post-processing.
+
+        The idea is that you want to be able to collect data from the node
+        before deleting it, for example to get a list of subscribers that have
+        to be notified after the node has been deleted. To do this,
+        C{preDeleteFn} fetches the subscriber list and passes this list to a
+        callback attached to a deferred that it sets up. This deferred is
+        returned in the list of deferreds.
+        """
+
+
+    def deleteNode(nodeIdentifier, requestor):
+        """ Delete a node.
+
+        @return: a deferred that fires when the node has been deleted.
+        """
+
+
+    def purgeNode(nodeIdentifier, requestor):
+        """ Removes all items in node from persistent storage """
+
+
+    def subscribe(nodeIdentifier, subscriber, requestor):
+        """ Request the subscription of an entity to a pubsub node.
+
+        Depending on the node's configuration and possible business rules, the
+        C{subscriber} is added to the list of subscriptions of the node with id
+        C{nodeIdentifier}. The C{subscriber} might be different from the
+        C{requestor}, and if the C{requestor} is not allowed to subscribe this
+        entity an exception should be raised.
+
+        @return: a deferred that returns the subscription state
+        """
+
+
+    def unsubscribe(nodeIdentifier, subscriber, requestor):
+        """ Cancel the subscription of an entity to a pubsub node.
+
+        The subscription of C{subscriber} is removed from the list of
+        subscriptions of the node with id C{nodeIdentifier}. If the
+        C{requestor} is not allowed to unsubscribe C{subscriber}, an an
+        exception should be raised.
+
+        @return: a deferred that fires when unsubscription is complete.
+        """
+
+
+    def getSubscribers(nodeIdentifier):
+        """ Get node subscriber list.
+
+        @return: a deferred that fires with the list of subscribers.
+        """
+
+
+    def getSubscriptions(entity):
+        """ Report the list of current subscriptions with this pubsub service.
+
+        Report the list of the current subscriptions with all nodes within this
+        pubsub service, for the C{entity}.
+
+        @return: a deferred that returns the list of all current subscriptions
+                 as tuples C{(nodeIdentifier, subscriber, subscription)}.
+        """
+
+
+    def getAffiliations(entity):
+        """ Report the list of current affiliations with this pubsub service.
+
+        Report the list of the current affiliations with all nodes within this
+        pubsub service, for the C{entity}.
+
+        @return: a deferred that returns the list of all current affiliations
+                 as tuples C{(nodeIdentifier, affiliation)}.
+        """
+
+
+    def publish(nodeIdentifier, items, requestor):
+        """ Publish items to a pubsub node.
+
+        @return: a deferred that fires when the items have been published.
+        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
+        """
+
+
+    def registerNotifier(observerfn, *args, **kwargs):
+        """ Register callback which is called for notification. """
+
+
+    def getNotifications(nodeIdentifier, items):
+        """
+        Get notification list.
+
+        This method is called to discover which entities should receive
+        notifications for the given items that have just been published to the
+        given node.
+
+        The notification list contains tuples (subscriber, subscriptions,
+        items) to result in one notification per tuple: the given subscriptions
+        yielded the given items to be notified to this subscriber.  This
+        structure is needed allow for letting the subscriber know which
+        subscriptions yielded which notifications, while catering for
+        collection nodes and content-based subscriptions.
+
+        To minimize the amount of notifications per entity, implementers
+        should take care that if all items in C{items} were yielded
+        by the same set of subscriptions, exactly one tuple is for this
+        subscriber is returned, so that the subscriber would get exactly one
+        notification. Alternatively, one tuple per subscription combination.
+
+        @param nodeIdentifier: The identifier of the node the items were
+                               published to.
+        @type nodeIdentifier: C{unicode}.
+        @param items: The list of published items as
+                      L{Element<twisted.words.xish.domish.Element>}s.
+        @type items: C{list}
+        @return: The notification list as tuples of
+                 (L{JID<twisted.words.protocols.jabber.jid.JID>},
+                  C{list} of L{Subscription<wokkel.pubsub.Subscription>},
+                  C{list} of L{Element<twisted.words.xish.domish.Element>}.
+        @rtype: C{list}
+        """
+
+
+    def getItems(nodeIdentifier, requestor, maxItems=None, itemIdentifiers=[]):
+        """ Retrieve items from persistent storage
+
+        If C{maxItems} is given, return the C{maxItems} last published
+        items, else if C{itemIdentifiers} is not empty, return the items
+        requested.  If neither is given, return all items.
+
+        @return: a deferred that returns the requested items
+        """
+
+
+    def retractItem(nodeIdentifier, itemIdentifier, requestor):
+        """ Removes item in node from persistent storage """
+
+
+
+class IStorage(Interface):
+    """
+    Storage interface.
+    """
+
+
+    def getNode(nodeIdentifier):
+        """
+        Get Node.
+
+        @param nodeIdentifier: NodeID of the desired node.
+        @type nodeIdentifier: C{str}
+        @return: deferred that returns a L{INode} providing object.
+        """
+
+
+    def getNodeIds():
+        """
+        Return all NodeIDs.
+
+        @return: deferred that returns a list of NodeIDs (C{unicode}).
+        """
+
+
+    def createNode(nodeIdentifier, owner, config):
+        """
+        Create new node.
+
+        The implementation should make sure, the passed owner JID is stripped
+        of the resource (e.g. using C{owner.userhostJID()}). The passed config
+        is expected to have values for the fields returned by
+        L{getDefaultConfiguration}, as well as a value for
+        C{'pubsub#node_type'}.
+
+        @param nodeIdentifier: NodeID of the new node.
+        @type nodeIdentifier: C{unicode}
+        @param owner: JID of the new nodes's owner.
+        @type owner: L{JID<twisted.words.protocols.jabber.jid.JID>}
+        @param config: Node configuration.
+        @type config: C{dict}
+        @return: deferred that fires on creation.
+        """
+
+
+    def deleteNode(nodeIdentifier):
+        """
+        Delete a node.
+
+        @param nodeIdentifier: NodeID of the new node.
+        @type nodeIdentifier: C{unicode}
+        @return: deferred that fires on deletion.
+        """
+
+
+    def getAffiliations(entity):
+        """
+        Get all affiliations for entity.
+
+        The implementation should make sure, the passed owner JID is stripped
+        of the resource (e.g. using C{owner.userhostJID()}).
+
+        @param entity: JID of the entity.
+        @type entity: L{JID<twisted.words.protocols.jabber.jid.JID>}
+        @return: deferred that returns a C{list} of tuples of the form
+                 C{(nodeIdentifier, affiliation)}, where C{nodeIdentifier} is
+                 of the type L{unicode} and C{affiliation} is one of
+                 C{'owner'}, C{'publisher'} and C{'outcast'}.
+        """
+
+
+    def getSubscriptions(entity):
+        """
+        Get all subscriptions for an entity.
+
+        The implementation should make sure, the passed owner JID is stripped
+        of the resource (e.g. using C{owner.userhostJID()}).
+
+        @param entity: JID of the entity.
+        @type entity: L{JID<twisted.words.protocols.jabber.jid.JID>}
+        @return: deferred that returns a C{list} of tuples of the form
+                 C{(nodeIdentifier, subscriber, state)}, where
+                 C{nodeIdentifier} is of the type C{unicode}, C{subscriber} of
+                 the type J{JID<twisted.words.protocols.jabber.jid.JID>}, and
+                 C{state} is C{'subscribed'}, C{'pending'} or
+                 C{'unconfigured'}.
+        """
+
+
+    def getDefaultConfiguration(nodeType):
+        """
+        Get the default configuration for the given node type.
+
+        @param nodeType: Either C{'leaf'} or C{'collection'}.
+        @type nodeType: C{str}
+        @return: The default configuration.
+        @rtype: C{dict}.
+        @raises: L{idavoll.error.NoCollections} if collections are not
+                 supported.
+        """
+
+
+
+class INode(Interface):
+    """
+    Interface to the class of objects that represent nodes.
+    """
+
+    nodeType = Attribute("""The type of this node. One of {'leaf'},
+                           {'collection'}.""")
+    nodeIdentifier = Attribute("""The node identifer of this node""")
+
+
+    def getType():
+        """
+        Get node's type.
+
+        @return: C{'leaf'} or C{'collection'}.
+        """
+
+
+    def getConfiguration():
+        """
+        Get node's configuration.
+
+        The configuration must at least have two options:
+        C{pubsub#persist_items}, and C{pubsub#deliver_payloads}.
+
+        @return: C{dict} of configuration options.
+        """
+
+
+    def getMetaData():
+        """
+        Get node's meta data.
+
+        The meta data must be a superset of the configuration options, and
+        also at least should have a C{pubsub#node_type} entry.
+
+        @return: C{dict} of meta data.
+        """
+
+
+    def setConfiguration(options):
+        """
+        Set node's configuration.
+
+        The elements of {options} will set the new values for those
+        configuration items. This means that only changing items have to
+        be given.
+
+        @param options: a dictionary of configuration options.
+        @returns: a deferred that fires upon success.
+        """
+
+
+    def getAffiliation(entity):
+        """
+        Get affiliation of entity with this node.
+
+        @param entity: JID of entity.
+        @type entity: L{JID<twisted.words.protocols.jabber.jid.JID>}
+        @return: deferred that returns C{'owner'}, C{'publisher'}, C{'outcast'}
+                 or C{None}.
+        """
+
+
+    def getSubscription(subscriber):
+        """
+        Get subscription to this node of subscriber.
+
+        @param subscriber: JID of the new subscriptions' entity.
+        @type subscriber: L{JID<twisted.words.protocols.jabber.jid.JID>}
+        @return: deferred that returns the subscription state (C{'subscribed'},
+                 C{'pending'} or C{None}).
+        """
+
+
+    def getSubscriptions(state=None):
+        """
+        Get list of subscriptions to this node.
+
+        The optional C{state} argument filters the subscriptions to their
+        state.
+
+        @param state: Subscription state filter. One of C{'subscribed'},
+                      C{'pending'}, C{'unconfigured'}.
+        @type state: C{str}
+        @return: a deferred that returns a C{list} of
+                 L{wokkel.pubsub.Subscription}s.
+        """
+
+
+    def addSubscription(subscriber, state, config):
+        """
+        Add new subscription to this node with given state.
+
+        @param subscriber: JID of the new subscriptions' entity.
+        @type subscriber: L{JID<twisted.words.protocols.jabber.jid.JID>}
+        @param state: C{'subscribed'} or C{'pending'}
+        @type state: C{str}
+        @param config: Subscription configuration.
+        @param config: C{dict}
+        @return: deferred that fires on subscription.
+        """
+
+
+    def removeSubscription(subscriber):
+        """
+        Remove subscription to this node.
+
+        @param subscriber: JID of the subscriptions' entity.
+        @type subscriber: L{JID<twisted.words.protocols.jabber.jid.JID>}
+        @return: deferred that fires on removal.
+        """
+
+
+    def isSubscribed(entity):
+        """
+        Returns whether entity has any subscription to this node.
+
+        Only returns C{True} when the subscription state (if present) is
+        C{'subscribed'} for any subscription that matches the bare JID.
+
+        @param subscriber: bare JID of the subscriptions' entity.
+        @type subscriber: L{JID<twisted.words.protocols.jabber.jid.JID>}
+        @return: deferred that returns a C{bool}.
+        """
+
+
+    def getAffiliations():
+        """
+        Get affiliations of entities with this node.
+
+        @return: deferred that returns a C{list} of tuples (jid, affiliation),
+                 where jid is a L(JID<twisted.words.protocols.jabber.jid.JID>)
+                 and affiliation is one of C{'owner'},
+        C{'publisher'}, C{'outcast'}.
+        """
+
+
+
+class ILeafNode(Interface):
+    """
+    Interface to the class of objects that represent leaf nodes.
+    """
+
+    def storeItems(items, publisher):
+        """
+        Store items in persistent storage for later retrieval.
+
+        @param items: The list of items to be stored. Each item is the
+                      L{domish} representation of the XML fragment as defined
+                      for C{<item/>} in the
+                      C{http://jabber.org/protocol/pubsub} namespace.
+        @type items: C{list} of {domish.Element}
+        @param publisher: JID of the publishing entity.
+        @type publisher: L{JID<twisted.words.protocols.jabber.jid.JID>}
+        @return: deferred that fires upon success.
+        """
+
+
+    def removeItems(itemIdentifiers):
+        """
+        Remove items by id.
+
+        @param itemIdentifiers: C{list} of item ids.
+        @return: deferred that fires with a C{list} of ids of the items that
+                 were deleted
+        """
+
+
+    def getItems(maxItems=None):
+        """
+        Get items.
+
+        If C{maxItems} is not given, all items in the node are returned,
+        just like C{getItemsById}. Otherwise, C{maxItems} limits
+        the returned items to a maximum of that number of most recently
+        published items.
+
+        @param maxItems: if given, a natural number (>0) that limits the
+                          returned number of items.
+        @return: deferred that fires with a C{list} of found items.
+        """
+
+
+    def getItemsById(itemIdentifiers):
+        """
+        Get items by item id.
+
+        Each item in the returned list is a unicode string that
+        represent the XML of the item as it was published, including the
+        item wrapper with item id.
+
+        @param itemIdentifiers: C{list} of item ids.
+        @return: deferred that fires with a C{list} of found items.
+        """
+
+
+    def purge():
+        """
+        Purge node of all items in persistent storage.
+
+        @return: deferred that fires when the node has been purged.
+        """
+
+
+
+class IGatewayStorage(Interface):
+
+    def addCallback(service, nodeIdentifier, callback):
+        """
+        Register a callback URI.
+
+        The registered HTTP callback URI will have an Atom Entry documented
+        POSTed to it upon receiving a notification for the given pubsub node.
+
+        @param service: The XMPP entity that holds the node.
+        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
+        @param nodeIdentifier: The identifier of the publish-subscribe node.
+        @type nodeIdentifier: C{unicode}.
+        @param callback: The callback URI to be registered.
+        @type callback: C{str}.
+        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
+        """
+
+    def removeCallback(service, nodeIdentifier, callback):
+        """
+        Remove a registered callback URI.
+
+        The returned deferred will fire with a boolean that signals wether or
+        not this was the last callback unregistered for this node.
+
+        @param service: The XMPP entity that holds the node.
+        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
+        @param nodeIdentifier: The identifier of the publish-subscribe node.
+        @type nodeIdentifier: C{unicode}.
+        @param callback: The callback URI to be unregistered.
+        @type callback: C{str}.
+        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
+        """
+
+    def getCallbacks(service, nodeIdentifier):
+        """
+        Get the callbacks registered for this node.
+
+        Returns a deferred that fires with the set of HTTP callback URIs
+        registered for this node.
+
+        @param service: The XMPP entity that holds the node.
+        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
+        @param nodeIdentifier: The identifier of the publish-subscribe node.
+        @type nodeIdentifier: C{unicode}.
+        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
+        """
+
+
+    def hasCallbacks(service, nodeIdentifier):
+        """
+        Return wether there are callbacks registered for a node.
+
+        @param service: The XMPP entity that holds the node.
+        @type service: L{JID<twisted.words.protocols.jabber.jid.JID>}
+        @param nodeIdentifier: The identifier of the publish-subscribe node.
+        @type nodeIdentifier: C{unicode}.
+        @returns: Deferred that fires with a boolean.
+        @rtype: L{Deferred<twisted.internet.defer.Deferred>}
+        """