source: wokkel/iwokkel.py @ 30:68535ae85c8d

Last change on this file since 30:68535ae85c8d was 30:68535ae85c8d, checked in by Ralph Meijer <ralphm@…>, 13 years ago

Add support for pubsub collections.

File size: 18.2 KB
Line 
1# Copyright (c) 2003-2008 Ralph Meijer
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
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
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
43        This should setup L{xmlstream} and call L{connectionMade}.
44
45        @type xs: L{XmlStream<twisted.words.protocols.jabber.XmlStream>}
46        """
47
48    def connectionMade():
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
62        exchanged over the XML stream L{xmlstream}. This method can be
63        used to setup observers for incoming stanzas.
64        """
65
66    def connectionLost(reason):
67        """
68        The XML stream has been closed.
69
70        Subsequent use of L{parent.send} will result in data being queued
71        until a new connection has been established.
72
73        @type reason: L{twisted.python.failure.Failure}
74        """
75
76
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        """
102
103
104class IDisco(Interface):
105    """
106    Interface for XMPP service discovery.
107    """
108
109    def getDiscoInfo(requestor, target, nodeIdentifier=''):
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}
115        @param target: The target entity to which the request is made.
116        @type target: L{jid.JID}
117        @param nodeIdentifier: The optional identifier of the node at this
118                               entity to retrieve the identify and features of.
119                               The default is C{''}, meaning the root node.
120        @type nodeIdentifier: C{unicode}
121        """
122
123    def getDiscoItems(requestor, target, nodeIdentifier=''):
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}
129        @param target: The target entity to which the request is made.
130        @type target: L{jid.JID}
131        @param nodeIdentifier: The optional identifier of the node at this
132                               entity to retrieve the identify and features of.
133                               The default is C{''}, meaning the root node.
134        @type nodeIdentifier: C{unicode}
135        """
136
137
138class IPubSubClient(Interface):
139
140    def itemsReceived(event):
141        """
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.
147
148        @param event: The items event.
149        @type event: L{ItemsEvent<wokkel.pubsub.ItemsEvent>}
150        """
151
152
153    def deleteReceived(event):
154        """
155        Called when a deletion notification has been received for a node.
156
157        @param event: The items event.
158        @type event: L{ItemsEvent<wokkel.pubsub.DeleteEvent>}
159        """
160
161
162    def purgeReceived(event):
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
169        @param event: The items event.
170        @type event: L{ItemsEvent<wokkel.pubsub.PurgeEvent>}
171        """
172
173    def createNode(service, nodeIdentifier=None):
174        """
175        Create a new publish subscribe node.
176
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}
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
190    def deleteNode(service, nodeIdentifier):
191        """
192        Delete a node.
193
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}
198        @rtype: L{defer.Deferred}
199        """
200
201    def subscribe(service, nodeIdentifier, subscriber):
202        """
203        Subscribe to a node with a given JID.
204
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}
209        @param subscriber: JID to subscribe to the node.
210        @type subscriber: L{jid.JID}
211        @rtype: L{defer.Deferred}
212        """
213
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
227    def publish(service, nodeIdentifier, items=[]):
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
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.
240        @type items: L{list} of L{Item}
241        @rtype: L{defer.Deferred}
242        """
243
244
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
255    def notifyPublish(service, nodeIdentifier, notifications):
256        """
257        Send out notifications for a publish event.
258
259        @param service: The entity the notifications will originate from.
260        @type service: L{jid.JID}
261        @param nodeIdentifier: The identifier of the node that was published
262                               to.
263        @type nodeIdentifier: C{unicode}
264        @param notifications: The notifications as tuples of subscriber and
265                              the list of items to be notified.
266        @type notifications: C{list} of (L{jid.JID}, C{list} of
267                             L{domish.Element})
268        """
269
270    def notifyDelete(service, nodeIdentifier, recipients):
271        """
272        Send out node deletion notifications.
273
274        @param service: The entity the notifications will originate from.
275        @type service: L{jid.JID}
276        @param nodeIdentifier: The identifier of the node that was deleted.
277        @type nodeIdentifier: C{unicode}
278        @param recipients: The entities that the notification is sent to.
279        @type notifications: C{list} of L{jid.JID}
280        """
281
282    def publish(requestor, service, nodeIdentifier, items):
283        """
284        Called when a publish request has been received.
285
286        @param requestor: The entity the request originated from.
287        @type requestor: L{jid.JID}
288        @param service: The entity the request was addressed to.
289        @type service: L{jid.JID}
290        @param nodeIdentifier: The identifier of the node to publish to.
291        @type nodeIdentifier: C{unicode}
292        @param items: The items to be published as L{domish} elements.
293        @type items: C{list} of C{domish.Element}
294        @return: deferred that fires on success.
295        @rtype: L{defer.Deferred}
296        """
297
298    def subscribe(requestor, service, nodeIdentifier, subscriber):
299        """
300        Called when a subscribe request has been received.
301
302        @param requestor: The entity the request originated from.
303        @type requestor: L{jid.JID}
304        @param service: The entity the request was addressed to.
305        @type service: L{jid.JID}
306        @param nodeIdentifier: The identifier of the node to subscribe to.
307        @type nodeIdentifier: C{unicode}
308        @param subscriber: The entity to be subscribed.
309        @type subscriber: L{jid.JID}
310        @return: A deferred that fires with a C{str} representing the
311                 subscription state, C{'subscribed'} or C{'pending'}.
312        @rtype: L{defer.Deferred}
313        """
314
315    def unsubscribe(requestor, service, nodeIdentifier, subscriber):
316        """
317        Called when a subscribe request has been received.
318
319        @param requestor: The entity the request originated from.
320        @type requestor: L{jid.JID}
321        @param service: The entity the request was addressed to.
322        @type service: L{jid.JID}
323        @param nodeIdentifier: The identifier of the node to unsubscribe from.
324        @type nodeIdentifier: C{unicode}
325        @param subscriber: The entity to be unsubscribed.
326        @type subscriber: L{jid.JID}
327        @return: A deferred that fires with C{None} when unsubscription has
328                 succeeded.
329        @rtype: L{defer.Deferred}
330        """
331
332    def subscriptions(requestor, service):
333        """
334        Called when a subscriptions retrieval request has been received.
335
336        @param requestor: The entity the request originated from.
337        @type requestor: L{jid.JID}
338        @param service: The entity the request was addressed to.
339        @type service: L{jid.JID}
340        @return: A deferred that fires with a C{list} of suscriptions as
341                 C{tuple}s of (node identifier as C{unicode}, subscriber as
342                 L{jid.JID}, subscription state as C{str}). The subscription
343                 state can be C{'subscribed'} or C{'pending'}.
344        @rtype: L{defer.Deferred}
345        """
346
347    def affiliations(requestor, service):
348        """
349        Called when a affiliations retrieval request has been received.
350
351        @param requestor: The entity the request originated from.
352        @type requestor: L{jid.JID}
353        @param service: The entity the request was addressed to.
354        @type service: L{jid.JID}
355        @return: A deferred that fires with a C{list} of affiliations as
356                 C{tuple}s of (node identifier as C{unicode}, affiliation state
357                 as C{str}). The affiliation can be C{'owner'}, C{'publisher'},
358                 or C{'outcast'}.
359        @rtype: L{defer.Deferred}
360        """
361
362    def create(requestor, service, nodeIdentifier):
363        """
364        Called when a node creation request has been received.
365
366        @param requestor: The entity the request originated from.
367        @type requestor: L{jid.JID}
368        @param service: The entity the request was addressed to.
369        @type service: L{jid.JID}
370        @param nodeIdentifier: The suggestion for the identifier of the node to
371                               be created. If the request did not include a
372                               suggestion for the node identifier, the value
373                               is C{None}.
374        @type nodeIdentifier: C{unicode} or C{NoneType}
375        @return: A deferred that fires with a C{unicode} that represents
376                 the identifier of the new node.
377        @rtype: L{defer.Deferred}
378        """
379
380    def getConfigurationOptions():
381        """
382        Retrieve all known node configuration options.
383
384        The returned dictionary holds the possible node configuration options
385        by option name. The value of each entry represents the specifics for
386        that option in a dictionary:
387
388        - C{'type'} (C{str}): The option's type (see
389          L{Field<wokkel.data_form.Field>}'s doc string for possible values).
390        - C{'label'} (C{unicode}): A human readable label for this option.
391        - C{'options'} (C{dict}): Optional list of possible values for this
392          option.
393
394        Example::
395
396            {
397            "pubsub#persist_items":
398                {"type": "boolean",
399                 "label": "Persist items to storage"},
400            "pubsub#deliver_payloads":
401                {"type": "boolean",
402                 "label": "Deliver payloads with event notifications"},
403            "pubsub#send_last_published_item":
404                {"type": "list-single",
405                 "label": "When to send the last published item",
406                 "options": {
407                     "never": "Never",
408                     "on_sub": "When a new subscription is processed"}
409                }
410            }
411
412        @rtype: C{dict}.
413        """
414
415    def getDefaultConfiguration(requestor, service):
416        """
417        Called when a default node configuration request has been received.
418
419        @param requestor: The entity the request originated from.
420        @type requestor: L{jid.JID}
421        @param service: The entity the request was addressed to.
422        @type service: L{jid.JID}
423        @return: A deferred that fires with a C{dict} representing the default
424                 node configuration. Keys are C{str}s that represent the
425                 field name. Values can be of types C{unicode}, C{int} or
426                 C{bool}.
427        @rtype: L{defer.Deferred}
428        """
429
430    def getConfiguration(requestor, service, nodeIdentifier):
431        """
432        Called when a node configuration retrieval request has been received.
433
434        @param requestor: The entity the request originated from.
435        @type requestor: L{jid.JID}
436        @param service: The entity the request was addressed to.
437        @type service: L{jid.JID}
438        @param nodeIdentifier: The identifier of the node to retrieve the
439                               configuration from.
440        @type nodeIdentifier: C{unicode}
441        @return: A deferred that fires with a C{dict} representing the node
442                 configuration. Keys are C{str}s that represent the field name.
443                 Values can be of types C{unicode}, C{int} or C{bool}.
444        @rtype: L{defer.Deferred}
445        """
446
447    def setConfiguration(requestor, service, nodeIdentifier, options):
448        """
449        Called when a node configuration change request has been received.
450
451        @param requestor: The entity the request originated from.
452        @type requestor: L{jid.JID}
453        @param service: The entity the request was addressed to.
454        @type service: L{jid.JID}
455        @param nodeIdentifier: The identifier of the node to change the
456                               configuration of.
457        @type nodeIdentifier: C{unicode}
458        @return: A deferred that fires with C{None} when the node's
459                 configuration has been changed.
460        @rtype: L{defer.Deferred}
461        """
462
463    def items(requestor, service, nodeIdentifier, maxItems, itemIdentifiers):
464        """
465        Called when a items retrieval request has been received.
466
467        @param requestor: The entity the request originated from.
468        @type requestor: L{jid.JID}
469        @param service: The entity the request was addressed to.
470        @type service: L{jid.JID}
471        @param nodeIdentifier: The identifier of the node to retrieve items
472                               from.
473        @type nodeIdentifier: C{unicode}
474        """
475
476    def retract(requestor, service, nodeIdentifier, itemIdentifiers):
477        """
478        Called when a item retraction request has been received.
479
480        @param requestor: The entity the request originated from.
481        @type requestor: L{jid.JID}
482        @param service: The entity the request was addressed to.
483        @type service: L{jid.JID}
484        @param nodeIdentifier: The identifier of the node to retract items
485                               from.
486        @type nodeIdentifier: C{unicode}
487        """
488
489    def purge(requestor, service, nodeIdentifier):
490        """
491        Called when a node purge request has been received.
492
493        @param requestor: The entity the request originated from.
494        @type requestor: L{jid.JID}
495        @param service: The entity the request was addressed to.
496        @type service: L{jid.JID}
497        @param nodeIdentifier: The identifier of the node to be purged.
498        @type nodeIdentifier: C{unicode}
499        """
500
501    def delete(requestor, service, nodeIdentifier):
502        """
503        Called when a node deletion request has been received.
504
505        @param requestor: The entity the request originated from.
506        @type requestor: L{jid.JID}
507        @param service: The entity the request was addressed to.
508        @type service: L{jid.JID}
509        @param nodeIdentifier: The identifier of the node to be delete.
510        @type nodeIdentifier: C{unicode}
511        """
Note: See TracBrowser for help on using the repository browser.