Ignore:
Timestamp:
Apr 22, 2009, 5:04:03 PM (12 years ago)
Author:
Ralph Meijer <ralphm@…>
Branch:
default
Convert:
svn:b33ecbfc-034c-dc11-8662-000475d9059e/trunk@171
Message:

Provide PubSubResource?, modeled after Twisted Web resources.

Author: ralphm.
Fixes #47.

This should make it rather easy to make publish-subscribe enabled services.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wokkel/iwokkel.py

    r48 r59  
    278278                             C{list} of L{domish.Element})
    279279        """
     280
    280281
    281282    def notifyDelete(service, nodeIdentifier, subscribers,
     
    527528        @type nodeIdentifier: C{unicode}
    528529        """
     530
     531
     532
     533class IPubSubResource(Interface):
     534
     535    def locateResource(request):
     536        """
     537        Locate a resource that will handle the request.
     538
     539        @param request: The publish-subscribe request.
     540        @type request: L{wokkel.pubsub.PubSubRequest}
     541        """
     542
     543
     544    def getInfo(requestor, service, nodeIdentifier):
     545        """
     546        Get node type and meta data.
     547
     548        @param requestor: The entity the request originated from.
     549        @type requestor: L{jid.JID}
     550        @param service: The publish-subscribe service entity.
     551        @type service: L{jid.JID}
     552        @param nodeIdentifier: Identifier of the node to request the info for.
     553        @type nodeIdentifier: L{unicode}
     554        @return: A deferred that fires with a dictionary. If not empty,
     555                 it must have the keys C{'type'} and C{'meta-data'} to keep
     556                 respectively the node type and a dictionary with the meta
     557                 data for that node.
     558        @rtype: L{defer.Deferred}
     559        """
     560
     561
     562    def getNodes(requestor, service, nodeIdentifier):
     563        """
     564        Get all nodes contained by this node.
     565
     566        @param requestor: The entity the request originated from.
     567        @type requestor: L{jid.JID}
     568        @param service: The publish-subscribe service entity.
     569        @type service: L{jid.JID}
     570        @param nodeIdentifier: Identifier of the node to request the childs for.
     571        @type nodeIdentifier: L{unicode}
     572        @return: A deferred that fires with a list of child node identifiers.
     573        @rtype: L{defer.Deferred}
     574        """
     575
     576
     577    def getConfigurationOptions():
     578        """
     579        Retrieve all known node configuration options.
     580
     581        The returned dictionary holds the possible node configuration options
     582        by option name. The value of each entry represents the specifics for
     583        that option in a dictionary:
     584
     585         - C{'type'} (C{str}): The option's type (see
     586           L{Field<wokkel.data_form.Field>}'s doc string for possible values).
     587         - C{'label'} (C{unicode}): A human readable label for this option.
     588         - C{'options'} (C{dict}): Optional list of possible values for this
     589           option.
     590
     591        Example::
     592
     593            {
     594            "pubsub#persist_items":
     595                {"type": "boolean",
     596                 "label": "Persist items to storage"},
     597            "pubsub#deliver_payloads":
     598                {"type": "boolean",
     599                 "label": "Deliver payloads with event notifications"},
     600            "pubsub#send_last_published_item":
     601                {"type": "list-single",
     602                 "label": "When to send the last published item",
     603                 "options": {
     604                     "never": "Never",
     605                     "on_sub": "When a new subscription is processed"}
     606                }
     607            }
     608
     609        @rtype: C{dict}.
     610        """
     611
     612
     613    def publish(request):
     614        """
     615        Called when a publish request has been received.
     616
     617        @param request: The publish-subscribe request.
     618        @type request: L{wokkel.pubsub.PubSubRequest}
     619        @return: deferred that fires on success.
     620        @rtype: L{defer.Deferred}
     621        """
     622
     623
     624    def subscribe(request):
     625        """
     626        Called when a subscribe request has been received.
     627
     628        @param request: The publish-subscribe request.
     629        @type request: L{wokkel.pubsub.PubSubRequest}
     630        @return: A deferred that fires with a
     631                 L{Subscription<wokkel.pubsub.Subscription>}.
     632        @rtype: L{defer.Deferred}
     633        """
     634
     635
     636    def unsubscribe(request):
     637        """
     638        Called when a subscribe request has been received.
     639
     640        @param request: The publish-subscribe request.
     641        @type request: L{wokkel.pubsub.PubSubRequest}
     642        @return: A deferred that fires with C{None} when unsubscription has
     643                 succeeded.
     644        @rtype: L{defer.Deferred}
     645        """
     646
     647
     648    def subscriptions(request):
     649        """
     650        Called when a subscriptions retrieval request has been received.
     651
     652        @param request: The publish-subscribe request.
     653        @type request: L{wokkel.pubsub.PubSubRequest}
     654        @return: A deferred that fires with a C{list} of subscriptions as
     655                 L{Subscription<wokkel.pubsub.Subscription>}.
     656        @rtype: L{defer.Deferred}
     657        """
     658
     659
     660    def affiliations(request):
     661        """
     662        Called when a affiliations retrieval request has been received.
     663
     664        @param request: The publish-subscribe request.
     665        @type request: L{wokkel.pubsub.PubSubRequest}
     666        @return: A deferred that fires with a C{list} of affiliations as
     667                 C{tuple}s of (node identifier as C{unicode}, affiliation state
     668                 as C{str}). The affiliation can be C{'owner'}, C{'publisher'},
     669                 or C{'outcast'}.
     670        @rtype: L{defer.Deferred}
     671        """
     672
     673
     674    def create(request):
     675        """
     676        Called when a node creation request has been received.
     677
     678        @param request: The publish-subscribe request.
     679        @type request: L{wokkel.pubsub.PubSubRequest}
     680        @return: A deferred that fires with a C{unicode} that represents
     681                 the identifier of the new node.
     682        @rtype: L{defer.Deferred}
     683        """
     684
     685
     686    def default(request):
     687        """
     688        Called when a default node configuration request has been received.
     689
     690        @param request: The publish-subscribe request.
     691        @type request: L{wokkel.pubsub.PubSubRequest}
     692        @return: A deferred that fires with a C{dict} representing the default
     693                 node configuration. Keys are C{str}s that represent the
     694                 field name. Values can be of types C{unicode}, C{int} or
     695                 C{bool}.
     696        @rtype: L{defer.Deferred}
     697        """
     698
     699
     700    def configureGet(request):
     701        """
     702        Called when a node configuration retrieval request has been received.
     703
     704        @param request: The publish-subscribe request.
     705        @type request: L{wokkel.pubsub.PubSubRequest}
     706        @return: A deferred that fires with a C{dict} representing the node
     707                 configuration. Keys are C{str}s that represent the field name.
     708                 Values can be of types C{unicode}, C{int} or C{bool}.
     709        @rtype: L{defer.Deferred}
     710        """
     711
     712
     713    def configureSet(request):
     714        """
     715        Called when a node configuration change request has been received.
     716
     717        @param request: The publish-subscribe request.
     718        @type request: L{wokkel.pubsub.PubSubRequest}
     719        @return: A deferred that fires with C{None} when the node's
     720                 configuration has been changed.
     721        @rtype: L{defer.Deferred}
     722        """
     723
     724
     725    def items(request):
     726        """
     727        Called when a items retrieval request has been received.
     728
     729        @param request: The publish-subscribe request.
     730        @type request: L{wokkel.pubsub.PubSubRequest}
     731        @return: A deferred that fires with a C{list} of L{pubsub.Item}.
     732        @rtype: L{defer.Deferred}
     733        """
     734
     735
     736    def retract(request):
     737        """
     738        Called when a item retraction request has been received.
     739
     740        @param request: The publish-subscribe request.
     741        @type request: L{wokkel.pubsub.PubSubRequest}
     742        @return: A deferred that fires with C{None} when the given items have
     743                 been retracted.
     744        @rtype: L{defer.Deferred}
     745        """
     746
     747
     748    def purge(request):
     749        """
     750        Called when a node purge request has been received.
     751
     752        @param request: The publish-subscribe request.
     753        @type request: L{wokkel.pubsub.PubSubRequest}
     754        @return: A deferred that fires with C{None} when the node has been
     755                 purged.
     756        @rtype: L{defer.Deferred}
     757        """
     758
     759
     760    def delete(request):
     761        """
     762        Called when a node deletion request has been received.
     763
     764        @param request: The publish-subscribe request.
     765        @type request: L{wokkel.pubsub.PubSubRequest}
     766        @return: A deferred that fires with C{None} when the node has been
     767                 deleted.
     768        @rtype: L{defer.Deferred}
     769        """
Note: See TracChangeset for help on using the changeset viewer.