source: wokkel/iwokkel.py @ 43:0a525d09169d

Last change on this file since 43:0a525d09169d was 43:0a525d09169d, checked in by Ralph Meijer <ralphm@…>, 13 years ago

Add support for sending and receiving node delete notifications with redirect.

File size: 18.6 KB
RevLine 
[10]1# Copyright (c) 2003-2008 Ralph Meijer
[1]2# See LICENSE for details.
3
4"""
5Wokkel interfaces.
6"""
7
8from zope.interface import Attribute, Interface
9
10class IXMPPHandler(Interface):
11    """
12    Interface for XMPP protocol handlers.
13
14    Objects that provide this interface can be added to a stream manager to
15    handle of (part of) an XMPP extension protocol.
16    """
17
18    manager = Attribute("""XML stream manager""")
19    xmlstream = Attribute("""The managed XML stream""")
20
[4]21    def setHandlerParent(parent):
22        """
23        Set the parent of the handler.
24
25        @type parent: L{IXMPPHandlerCollection}
26        """
27
28    def disownHandlerParent(parent):
29        """
30        Remove the parent of the handler.
31
32        @type parent: L{IXMPPHandlerCollection}
33        """
34
[1]35    def makeConnection(xs):
36        """
37        A connection over the underlying transport of the XML stream has been
38        established.
39
40        At this point, no traffic has been exchanged over the XML stream
41        given in C{xs}.
42
[16]43        This should setup L{xmlstream} and call L{connectionMade}.
[1]44
45        @type xs: L{XmlStream<twisted.words.protocols.jabber.XmlStream>}
46        """
47
[16]48    def connectionMade():
[1]49        """
50        Called after a connection has been established.
51
52        This method can be used to change properties of the XML Stream, its
53        authenticator or the stream manager prior to stream initialization
54        (including authentication).
55        """
56
57    def connectionInitialized():
58        """
59        The XML stream has been initialized.
60
61        At this point, authentication was successful, and XML stanzas can be
[16]62        exchanged over the XML stream L{xmlstream}. This method can be
[1]63        used to setup observers for incoming stanzas.
64        """
65
66    def connectionLost(reason):
67        """
68        The XML stream has been closed.
69
[16]70        Subsequent use of L{parent.send} will result in data being queued
[1]71        until a new connection has been established.
72
73        @type reason: L{twisted.python.failure.Failure}
74        """
75
[15]76
[4]77class IXMPPHandlerCollection(Interface):
78    """
79    Collection of handlers.
80
81    Contain several handlers and manage their connection.
82    """
83
84    def __iter__():
85        """
86        Get an iterator over all child handlers.
87        """
88
89    def addHandler(handler):
90        """
91        Add a child handler.
92
93        @type handler: L{IXMPPHandler}
94        """
95
96    def removeHandler(handler):
97        """
98        Remove a child handler.
99
100        @type handler: L{IXMPPHandler}
101        """
[1]102
[15]103
[1]104class IDisco(Interface):
105    """
106    Interface for XMPP service discovery.
107    """
108
[30]109    def getDiscoInfo(requestor, target, nodeIdentifier=''):
[1]110        """
111        Get identity and features from this entity, node.
112
113        @param requestor: The entity the request originated from.
114        @type requestor: L{jid.JID}
[6]115        @param target: The target entity to which the request is made.
116        @type target: L{jid.JID}
[1]117        @param nodeIdentifier: The optional identifier of the node at this
118                               entity to retrieve the identify and features of.
[30]119                               The default is C{''}, meaning the root node.
[1]120        @type nodeIdentifier: C{unicode}
121        """
122
[30]123    def getDiscoItems(requestor, target, nodeIdentifier=''):
[1]124        """
125        Get contained items for this entity, node.
126
127        @param requestor: The entity the request originated from.
128        @type requestor: L{jid.JID}
[6]129        @param target: The target entity to which the request is made.
130        @type target: L{jid.JID}
[1]131        @param nodeIdentifier: The optional identifier of the node at this
132                               entity to retrieve the identify and features of.
[30]133                               The default is C{''}, meaning the root node.
[1]134        @type nodeIdentifier: C{unicode}
135        """
136
[2]137
138class IPubSubClient(Interface):
139
[27]140    def itemsReceived(event):
[2]141        """
[13]142        Called when an items notification has been received for a node.
143
144        An item can be an element named C{item} or C{retract}. Respectively,
145        they signal an item being published or retracted, optionally
146        accompanied with an item identifier in the C{id} attribute.
[2]147
[27]148        @param event: The items event.
149        @type event: L{ItemsEvent<wokkel.pubsub.ItemsEvent>}
[2]150        """
151
[27]152
153    def deleteReceived(event):
[13]154        """
155        Called when a deletion notification has been received for a node.
156
[27]157        @param event: The items event.
158        @type event: L{ItemsEvent<wokkel.pubsub.DeleteEvent>}
[13]159        """
160
[27]161
162    def purgeReceived(event):
[13]163        """
164        Called when a purge notification has been received for a node.
165
166        Upon receiving this notification all items associated should be
167        considered retracted.
168
[27]169        @param event: The items event.
170        @type event: L{ItemsEvent<wokkel.pubsub.PurgeEvent>}
[13]171        """
172
[6]173    def createNode(service, nodeIdentifier=None):
[2]174        """
175        Create a new publish subscribe node.
176
[6]177        @param service: The publish-subscribe service entity.
178        @type service: L{jid.JID}
179        @param nodeIdentifier: Optional suggestion for the new node's
180                               identifier. If omitted, the creation of an
181                               instant node will be attempted.
182        @type nodeIdentifier: L{unicode}
[2]183        @return: a deferred that fires with the identifier of the newly created
184                 node. Note that this can differ from the suggested identifier
185                 if the publish subscribe service chooses to modify or ignore
186                 the suggested identifier.
187        @rtype: L{defer.Deferred}
188        """
189
[6]190    def deleteNode(service, nodeIdentifier):
[2]191        """
192        Delete a node.
193
[6]194        @param service: The publish-subscribe service entity.
195        @type service: L{jid.JID}
196        @param nodeIdentifier: Identifier of the node to be deleted.
197        @type nodeIdentifier: L{unicode}
[2]198        @rtype: L{defer.Deferred}
199        """
200
[6]201    def subscribe(service, nodeIdentifier, subscriber):
[2]202        """
203        Subscribe to a node with a given JID.
204
[6]205        @param service: The publish-subscribe service entity.
206        @type service: L{jid.JID}
207        @param nodeIdentifier: Identifier of the node to subscribe to.
208        @type nodeIdentifier: L{unicode}
[2]209        @param subscriber: JID to subscribe to the node.
210        @type subscriber: L{jid.JID}
211        @rtype: L{defer.Deferred}
212        """
213
[10]214    def unsubscribe(service, nodeIdentifier, subscriber):
215        """
216        Unsubscribe from a node with a given JID.
217
218        @param service: The publish-subscribe service entity.
219        @type service: L{jid.JID}
220        @param nodeIdentifier: Identifier of the node to unsubscribe from.
221        @type nodeIdentifier: L{unicode}
222        @param subscriber: JID to unsubscribe from the node.
223        @type subscriber: L{jid.JID}
224        @rtype: L{defer.Deferred}
225        """
226
[6]227    def publish(service, nodeIdentifier, items=[]):
[2]228        """
229        Publish to a node.
230
231        Node that the C{items} parameter is optional, because so-called
232        transient, notification-only nodes do not use items and publish
233        actions only signify a change in some resource.
234
[6]235        @param service: The publish-subscribe service entity.
236        @type service: L{jid.JID}
237        @param nodeIdentifier: Identifier of the node to publish to.
238        @type nodeIdentifier: L{unicode}
239        @param items: List of item elements.
[2]240        @type items: L{list} of L{Item}
241        @rtype: L{defer.Deferred}
242        """
243
244
[1]245class IPubSubService(Interface):
246    """
247    Interface for an XMPP Publish Subscribe Service.
248
249    All methods that are called as the result of an XMPP request are to
250    return a deferred that fires when the requested action has been performed.
251    Alternatively, exceptions maybe raised directly or by calling C{errback}
252    on the returned deferred.
253    """
254
[6]255    def notifyPublish(service, nodeIdentifier, notifications):
[1]256        """
257        Send out notifications for a publish event.
258
[6]259        @param service: The entity the notifications will originate from.
260        @type service: L{jid.JID}
[1]261        @param nodeIdentifier: The identifier of the node that was published
262                               to.
263        @type nodeIdentifier: C{unicode}
[31]264        @param notifications: The notifications as tuples of subscriber, the
265                              list of subscriptions and the list of items to be
266                              notified.
[1]267        @type notifications: C{list} of (L{jid.JID}, C{list} of
[31]268                             L{Subscription<wokkel.pubsub.Subscription>},
269                             C{list} of L{domish.Element})
[1]270        """
271
[43]272    def notifyDelete(service, nodeIdentifier, subscribers,
273                     redirectURI=None):
[15]274        """
275        Send out node deletion notifications.
276
277        @param service: The entity the notifications will originate from.
278        @type service: L{jid.JID}
279        @param nodeIdentifier: The identifier of the node that was deleted.
280        @type nodeIdentifier: C{unicode}
[43]281        @param subscribers: The subscribers for which a notification should
282                            be sent out.
283        @type subscribers: C{list} of L{jid.JID}
284        @param redirectURI: Optional XMPP URI of another node that subscribers
285                            are redirected to.
286        @type redirectURI: C{str}
[15]287        """
288
[6]289    def publish(requestor, service, nodeIdentifier, items):
[1]290        """
291        Called when a publish request has been received.
292
293        @param requestor: The entity the request originated from.
294        @type requestor: L{jid.JID}
[6]295        @param service: The entity the request was addressed to.
296        @type service: L{jid.JID}
[1]297        @param nodeIdentifier: The identifier of the node to publish to.
298        @type nodeIdentifier: C{unicode}
299        @param items: The items to be published as L{domish} elements.
300        @type items: C{list} of C{domish.Element}
301        @return: deferred that fires on success.
302        @rtype: L{defer.Deferred}
303        """
304
[6]305    def subscribe(requestor, service, nodeIdentifier, subscriber):
[1]306        """
307        Called when a subscribe request has been received.
308
309        @param requestor: The entity the request originated from.
310        @type requestor: L{jid.JID}
[6]311        @param service: The entity the request was addressed to.
312        @type service: L{jid.JID}
[1]313        @param nodeIdentifier: The identifier of the node to subscribe to.
314        @type nodeIdentifier: C{unicode}
315        @param subscriber: The entity to be subscribed.
316        @type subscriber: L{jid.JID}
[31]317        @return: A deferred that fires with a
318                 L{Subscription<wokkel.pubsub.Subscription>}.
[1]319        @rtype: L{defer.Deferred}
320        """
321
[6]322    def unsubscribe(requestor, service, nodeIdentifier, subscriber):
[1]323        """
324        Called when a subscribe request has been received.
325
326        @param requestor: The entity the request originated from.
327        @type requestor: L{jid.JID}
[6]328        @param service: The entity the request was addressed to.
329        @type service: L{jid.JID}
[1]330        @param nodeIdentifier: The identifier of the node to unsubscribe from.
331        @type nodeIdentifier: C{unicode}
332        @param subscriber: The entity to be unsubscribed.
333        @type subscriber: L{jid.JID}
334        @return: A deferred that fires with C{None} when unsubscription has
335                 succeeded.
336        @rtype: L{defer.Deferred}
337        """
338
[6]339    def subscriptions(requestor, service):
[1]340        """
341        Called when a subscriptions retrieval request has been received.
342
343        @param requestor: The entity the request originated from.
344        @type requestor: L{jid.JID}
[6]345        @param service: The entity the request was addressed to.
346        @type service: L{jid.JID}
[31]347        @return: A deferred that fires with a C{list} of subscriptions as
348                 L{Subscription<wokkel.pubsub.Subscription>}.
[1]349        @rtype: L{defer.Deferred}
350        """
351
[6]352    def affiliations(requestor, service):
[1]353        """
354        Called when a affiliations retrieval request has been received.
355
356        @param requestor: The entity the request originated from.
357        @type requestor: L{jid.JID}
[6]358        @param service: The entity the request was addressed to.
359        @type service: L{jid.JID}
[1]360        @return: A deferred that fires with a C{list} of affiliations as
361                 C{tuple}s of (node identifier as C{unicode}, affiliation state
362                 as C{str}). The affiliation can be C{'owner'}, C{'publisher'},
363                 or C{'outcast'}.
364        @rtype: L{defer.Deferred}
365        """
366
[6]367    def create(requestor, service, nodeIdentifier):
[1]368        """
369        Called when a node creation request has been received.
370
371        @param requestor: The entity the request originated from.
372        @type requestor: L{jid.JID}
[6]373        @param service: The entity the request was addressed to.
374        @type service: L{jid.JID}
[1]375        @param nodeIdentifier: The suggestion for the identifier of the node to
376                               be created. If the request did not include a
377                               suggestion for the node identifier, the value
378                               is C{None}.
379        @type nodeIdentifier: C{unicode} or C{NoneType}
380        @return: A deferred that fires with a C{unicode} that represents
381                 the identifier of the new node.
382        @rtype: L{defer.Deferred}
383        """
384
[25]385    def getConfigurationOptions():
386        """
387        Retrieve all known node configuration options.
388
389        The returned dictionary holds the possible node configuration options
390        by option name. The value of each entry represents the specifics for
391        that option in a dictionary:
392
393        - C{'type'} (C{str}): The option's type (see
394          L{Field<wokkel.data_form.Field>}'s doc string for possible values).
395        - C{'label'} (C{unicode}): A human readable label for this option.
396        - C{'options'} (C{dict}): Optional list of possible values for this
397          option.
398
399        Example::
400
401            {
402            "pubsub#persist_items":
403                {"type": "boolean",
404                 "label": "Persist items to storage"},
405            "pubsub#deliver_payloads":
406                {"type": "boolean",
407                 "label": "Deliver payloads with event notifications"},
408            "pubsub#send_last_published_item":
409                {"type": "list-single",
410                 "label": "When to send the last published item",
411                 "options": {
412                     "never": "Never",
413                     "on_sub": "When a new subscription is processed"}
414                }
415            }
416
417        @rtype: C{dict}.
418        """
419
[43]420    def getDefaultConfiguration(requestor, service, nodeType):
[1]421        """
422        Called when a default node configuration request has been received.
423
424        @param requestor: The entity the request originated from.
425        @type requestor: L{jid.JID}
[6]426        @param service: The entity the request was addressed to.
427        @type service: L{jid.JID}
[43]428        @param nodeType: The type of node for which the configuration is
429                         retrieved, C{'leaf'} or C{'collection'}.
430        @type nodeType: C{str}
[1]431        @return: A deferred that fires with a C{dict} representing the default
432                 node configuration. Keys are C{str}s that represent the
433                 field name. Values can be of types C{unicode}, C{int} or
434                 C{bool}.
435        @rtype: L{defer.Deferred}
436        """
437
[6]438    def getConfiguration(requestor, service, nodeIdentifier):
[1]439        """
440        Called when a node configuration retrieval request has been received.
441
442        @param requestor: The entity the request originated from.
443        @type requestor: L{jid.JID}
[6]444        @param service: The entity the request was addressed to.
445        @type service: L{jid.JID}
[1]446        @param nodeIdentifier: The identifier of the node to retrieve the
447                               configuration from.
448        @type nodeIdentifier: C{unicode}
449        @return: A deferred that fires with a C{dict} representing the node
450                 configuration. Keys are C{str}s that represent the field name.
451                 Values can be of types C{unicode}, C{int} or C{bool}.
452        @rtype: L{defer.Deferred}
453        """
454
[6]455    def setConfiguration(requestor, service, nodeIdentifier, options):
[1]456        """
457        Called when a node configuration change request has been received.
458
459        @param requestor: The entity the request originated from.
460        @type requestor: L{jid.JID}
[6]461        @param service: The entity the request was addressed to.
462        @type service: L{jid.JID}
[1]463        @param nodeIdentifier: The identifier of the node to change the
464                               configuration of.
465        @type nodeIdentifier: C{unicode}
466        @return: A deferred that fires with C{None} when the node's
467                 configuration has been changed.
468        @rtype: L{defer.Deferred}
469        """
470
[6]471    def items(requestor, service, nodeIdentifier, maxItems, itemIdentifiers):
[1]472        """
473        Called when a items retrieval request has been received.
474
475        @param requestor: The entity the request originated from.
476        @type requestor: L{jid.JID}
[6]477        @param service: The entity the request was addressed to.
478        @type service: L{jid.JID}
[1]479        @param nodeIdentifier: The identifier of the node to retrieve items
480                               from.
481        @type nodeIdentifier: C{unicode}
482        """
483
[6]484    def retract(requestor, service, nodeIdentifier, itemIdentifiers):
[1]485        """
486        Called when a item retraction request has been received.
487
488        @param requestor: The entity the request originated from.
489        @type requestor: L{jid.JID}
[6]490        @param service: The entity the request was addressed to.
491        @type service: L{jid.JID}
[1]492        @param nodeIdentifier: The identifier of the node to retract items
493                               from.
494        @type nodeIdentifier: C{unicode}
495        """
496
[6]497    def purge(requestor, service, nodeIdentifier):
[1]498        """
499        Called when a node purge request has been received.
500
501        @param requestor: The entity the request originated from.
502        @type requestor: L{jid.JID}
[6]503        @param service: The entity the request was addressed to.
504        @type service: L{jid.JID}
[1]505        @param nodeIdentifier: The identifier of the node to be purged.
506        @type nodeIdentifier: C{unicode}
507        """
508
[6]509    def delete(requestor, service, nodeIdentifier):
[1]510        """
511        Called when a node deletion request has been received.
512
513        @param requestor: The entity the request originated from.
514        @type requestor: L{jid.JID}
[6]515        @param service: The entity the request was addressed to.
516        @type service: L{jid.JID}
[1]517        @param nodeIdentifier: The identifier of the node to be delete.
518        @type nodeIdentifier: C{unicode}
519        """
Note: See TracBrowser for help on using the repository browser.