libervia-pubsub: idavoll/iidavoll.py comparison

comparison idavoll/iidavoll.py @ 206:274a45d2a5ab

Implement root collection that includes all leaf nodes.

author	Ralph Meijer <ralphm@ik.nu>
date	Mon, 04 Aug 2008 13:47:10 +0000
parents	b4bf0a5ce50d
children

comparison

equal deleted inserted replaced

-:e6b710bf2b24
+:274a45d2a5ab
 """ Interface to a backend service of a pubsub service. """
 def __init__(storage):
 """
-@param storage: L{storage} object.
+@param storage: Object providing L{IStorage}.
 """
 def supportsPublisherAffiliation():
 """ Reports if the backend supports the publisher affiliation.
 def registerNotifier(observerfn, *args, **kwargs):
 """ Register callback which is called for notification. """
-def getNotificationList(nodeIdentifier, items):
+def getNotifications(nodeIdentifier, items):
 """
-Get list of entities to notify.
+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
 def getNode(nodeIdentifier):
 """
 Get Node.
 @param nodeIdentifier: NodeID of the desired node.
-@type nodeIdentifier: L{str}
+@type nodeIdentifier: C{str}
-@return: deferred that returns a L{Node} object.
+@return: deferred that returns a L{INode} providing object.
 """
 def getNodeIds():
 """
 Return all NodeIDs.
-@return: deferred that returns a list of NodeIDs (L{str}).
+@return: deferred that returns a list of NodeIDs (C{unicode}).
 """
-def createNode(nodeIdentifier, owner, config=None):
+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 nodeIdentifier: NodeID of the new node.
+@param entity: JID of the entity.
-@type nodeIdentifier: L{str}
+@type entity: L{JID<twisted.words.protocols.jabber.jid.JID>}
-@param owner: JID of the new nodes's owner.
+@return: deferred that returns a C{list} of tuples of the form
-@type owner: L{jid.JID}
+C{(nodeIdentifier, affiliation)}, where C{nodeIdentifier} is
-@param config: Configuration
+of the type L{unicode} and C{affiliation} is one of
-@return: deferred that fires on creation.
+C{'owner'}, C{'publisher'} and C{'outcast'}.
 """
-def deleteNode(nodeIdentifier):
+def getSubscriptions(entity):
 """
-Delete a node.
+Get all subscriptions for an entity.
-@param nodeIdentifier: NodeID of the new node.
-@type nodeIdentifier: L{str}
-@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.JID}
+@type entity: L{JID<twisted.words.protocols.jabber.jid.JID>}
-@return: deferred that returns a L{list} of tuples of the form
+@return: deferred that returns a C{list} of tuples of the form
-C{(nodeIdentifier, affiliation)}, where C{nodeIdentifier} is
-of the type L{str} 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.JID}
-@return: deferred that returns a L{list} of tuples of the form
 C{(nodeIdentifier, subscriber, state)}, where
-C{nodeIdentifier} is of the type L{str}, C{subscriber} of the
+C{nodeIdentifier} is of the type C{unicode}, C{subscriber} of
-type {jid.JID}, and C{state} is C{'subscribed'} or
+the type J{JID<twisted.words.protocols.jabber.jid.JID>}, and
-C{'pending'}.
+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):
 Get node's configuration.
 The configuration must at least have two options:
 C{pubsub#persist_items}, and C{pubsub#deliver_payloads}.
-@return: L{dict} of configuration options.
+@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: L{dict} of meta data.
+@return: C{dict} of meta data.
 """
 def setConfiguration(options):
 """
 def getAffiliation(entity):
 """
 Get affiliation of entity with this node.
 @param entity: JID of entity.
-@type entity: L{jid.JID}
+@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.JID}
+@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 addSubscription(subscriber, state):
+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.JID}
+@type subscriber: L{JID<twisted.words.protocols.jabber.jid.JID>}
 @param state: C{'subscribed'} or C{'pending'}
-@type state: L{str}
+@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.JID}
+@type subscriber: L{JID<twisted.words.protocols.jabber.jid.JID>}
 @return: deferred that fires on removal.
-"""
-def getSubscribers():
-"""
-Get list of subscribers to this node.
-Retrieves the list of entities that have a subscription to this
-node. That is, having the state C{'subscribed'}.
-@return: a deferred that returns a L{list} of L{jid.JID}s.
 """
 def isSubscribed(entity):
 """
 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.JID}
+@type subscriber: L{JID<twisted.words.protocols.jabber.jid.JID>}
-@return: deferred that returns a L{bool}.
+@return: deferred that returns a C{bool}.
 """
 def getAffiliations():
 """
 Get affiliations of entities with this node.
-@return: deferred that returns a L{list} of tuples (jid, affiliation),
+@return: deferred that returns a C{list} of tuples (jid, affiliation),
-where jid is a L(jid.JID) and affiliation is one of C{'owner'},
+where jid is a L(JID<twisted.words.protocols.jabber.jid.JID>)
+and affiliation is one of C{'owner'},
 C{'publisher'}, C{'outcast'}.
 """
 @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: L{list} of {domish.Element}
+@type items: C{list} of {domish.Element}
 @param publisher: JID of the publishing entity.
-@type publisher: L{jid.JID}
+@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: L{list} of item ids.
+@param itemIdentifiers: C{list} of item ids.
-@return: deferred that fires with a L{list} of ids of the items that
+@return: deferred that fires with a C{list} of ids of the items that
 were deleted
 """
 def getItems(maxItems=None):
 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 L{list} of found items.
+@return: deferred that fires with a C{list} of found items.
 """
 def getItemsById(itemIdentifiers):
 """
 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: L{list} of item ids.
+@param itemIdentifiers: C{list} of item ids.
-@return: deferred that fires with a L{list} of found items.
+@return: deferred that fires with a C{list} of found items.
 """
 def purge():
 """

Mercurial > libervia-pubsub

comparison idavoll/iidavoll.py @ 206:274a45d2a5ab