view idavoll/storage.py @ 162:84cfe9fe38c5

Comply with the access model 'open'. Currently, the only implemented access model is 'open', so we should not check for the subscription of the requestor for item retrieval. We do reject outcasts.
author Ralph Meijer <ralphm@ik.nu>
date Wed, 06 Sep 2006 12:57:53 +0000
parents 5191ba7c4df8
children
line wrap: on
line source

# Copyright (c) 2003-2006 Ralph Meijer
# See LICENSE for details.

from zope.interface import Interface
from twisted.words.protocols.jabber import jid
from twisted.words.xish import domish

class Error(Exception):
    msg = None

class NodeNotFound(Error):
    pass

class NodeExists(Error):
    pass

class SubscriptionNotFound(Error):
    pass

class SubscriptionExists(Error):
    pass

class IStorage(Interface):
    """ Storage interface """

    def get_node(self, node_id):
        """ Get Node.

        @param node_id: NodeID of the desired node.
        @type node_id: L{str}
        @return: deferred that returns a L{Node} object.
        """

    def get_node_ids(self):
        """ Return all NodeIDs.
        
        @return: deferred that returns a list of NodeIDs (L{str}).
        """

    def create_node(self, node_id, owner, config = None, type='leaf'):
        """ Create new node.

        The implementation should make sure, the passed owner JID is stripped
        of the resource (e.g. using C{owner.userhostJID()}).

        @param node_id: NodeID of the new node.
        @type node_id: L{str}
        @param owner: JID of the new nodes's owner. 
        @type owner: L{jid.JID}
        @param config: Configuration
        @param type: Node type. Can be either C{'leaf'} or C{'collection'}.
        @return: deferred that fires on creation.
        """

    def delete_node(self, node_id):
        """ Delete a node.

        @param node_id: NodeID of the new node.
        @type node_id: L{str}
        @return: deferred that fires on deletion.
        """

    def get_affiliations(self, 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}
        @return: deferred that returns a L{list} of tuples of the form
                 C{(node_id, affiliation)}, where C{node_id} is of the type
                 L{str} and C{affiliation} is one of C{'owner'}, C{'publisher'}
                 and C{'outcast'}.
        """

    def get_subscriptions(self, 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{(node_id, subscriber, state)}, where C{node_id} is of the
                 type L{str}, C{subscriber} of the type {jid.JID}, and
                 C{state} is C{'subscribed'} or C{'pending'}.
        """


class INode(Interface):
    """ Interface to the class of objects that represent nodes. """

    def get_type(self):
        """ Get node's type.
        
        @return: C{'leaf'} or C{'collection'}.
        """

    def get_configuration(self):
        """ 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.
        """

    def get_meta_data(self):
        """ 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.
        """

    def set_configuration(self, 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 get_affiliation(self, entity):
        """ Get affiliation of entity with this node.

        @param entity: JID of entity.
        @type entity: L{jid.JID}
        @return: deferred that returns C{'owner'}, C{'publisher'}, C{'outcast'}
                 or C{None}.
        """

    def get_subscription(self, subscriber):
        """ Get subscription to this node of subscriber.

        @param subscriber: JID of the new subscriptions' entity.
        @type subscriber: L{jid.JID}
        @return: deferred that returns the subscription state (C{'subscribed'},
                 C{'pending'} or C{None}).
        """

    def add_subscription(self, subscriber, state):
        """ Add new subscription to this node with given state.

        @param subscriber: JID of the new subscriptions' entity.
        @type subscriber: L{jid.JID}
        @param state: C{'subscribed'} or C{'pending'}
        @type state: L{str}
        @return: deferred that fires on subscription.
        """

    def remove_subscription(self, subscriber):
        """ Remove subscription to this node.

        @param subscriber: JID of the subscriptions' entity.
        @type subscriber: L{jid.JID}
        @return: deferred that fires on removal.
        """

    def get_subscribers(self):
        """ 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 is_subscribed(self, 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.JID}
        @return: deferred that returns a L{bool}.
        """

    def get_affiliations(self):
        """ Get affiliations of entities with this node.

        @return: deferred that returns a L{list} of tuples (jid, affiliation),
        where jid is a L(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 store_items(self, 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: L{list} of {domish.Element}
        @param publisher: JID of the publishing entity.
        @type publisher: L{jid.JID}
        @return: deferred that fires upon success.
        """

    def remove_items(self, item_ids):
        """ Remove items by id
        
        @param item_ids: L{list} of item ids.
        @return: deferred that fires with a L{list} of ids of the items that
                 were deleted
        """

    def get_items(self, max_items=None):
        """ Get items.

        If C{max_items} is not given, all items in the node are returned,
        just like C{get_items_by_id}. Otherwise, C{max_items} limits
        the returned items to a maximum of that number of most recently
        published items.
       
        @param max_items: if given, a natural number (>0) that limits the
                          returned number of items.
        @return: deferred that fires with a L{list} of found items.
        """

    def get_items_by_id(self, item_ids):
        """ 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 item_ids: L{list} of item ids.
        @return: deferred that fires with a L{list} of found items.
        """

    def purge(self):
        """ Purge node of all items in persistent storage.
        
        @return: deferred that fires when the node has been purged.
        """


class ISubscription(Interface):
    """ """