libervia-pubsub: sat_pubsub/iidavoll.py comparison

comparison sat_pubsub/iidavoll.py @ 232:923281d4c5bc

renamed idavoll directory to sat_pubsub

author	Goffi <goffi@goffi.org>
date	Thu, 17 May 2012 12:48:14 +0200
parents	idavoll/iidavoll.py@274a45d2a5ab
children	564ae55219e1

comparison

equal deleted inserted replaced

-:d99047cd90f9
+:923281d4c5bc
+# 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>}
+"""

Mercurial > libervia-pubsub

comparison sat_pubsub/iidavoll.py @ 232:923281d4c5bc