Mercurial > libervia-pubsub
annotate 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 |
| rev | line source |
|---|---|
|
155
5191ba7c4df8
Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
152
diff
changeset
|
1 # Copyright (c) 2003-2006 Ralph Meijer |
|
5191ba7c4df8
Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
152
diff
changeset
|
2 # See LICENSE for details. |
|
5191ba7c4df8
Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
152
diff
changeset
|
3 |
| 107 | 4 from zope.interface import Interface |
| 111 | 5 from twisted.words.protocols.jabber import jid |
| 152 | 6 from twisted.words.xish import domish |
| 107 | 7 |
| 8 class Error(Exception): | |
| 9 msg = None | |
| 10 | |
| 11 class NodeNotFound(Error): | |
| 12 pass | |
| 13 | |
| 14 class NodeExists(Error): | |
| 15 pass | |
| 16 | |
|
119
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
17 class SubscriptionNotFound(Error): |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
18 pass |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
19 |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
20 class SubscriptionExists(Error): |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
21 pass |
| 107 | 22 |
| 23 class IStorage(Interface): | |
| 111 | 24 """ Storage interface """ |
| 107 | 25 |
| 26 def get_node(self, node_id): | |
| 111 | 27 """ Get Node. |
| 28 | |
| 29 @param node_id: NodeID of the desired node. | |
| 30 @type node_id: L{str} | |
| 31 @return: deferred that returns a L{Node} object. | |
| 32 """ | |
| 107 | 33 |
| 34 def get_node_ids(self): | |
| 111 | 35 """ Return all NodeIDs. |
| 36 | |
| 37 @return: deferred that returns a list of NodeIDs (L{str}). | |
| 38 """ | |
| 107 | 39 |
| 40 def create_node(self, node_id, owner, config = None, type='leaf'): | |
| 111 | 41 """ Create new node. |
| 42 | |
| 43 The implementation should make sure, the passed owner JID is stripped | |
| 44 of the resource (e.g. using C{owner.userhostJID()}). | |
| 45 | |
| 46 @param node_id: NodeID of the new node. | |
| 47 @type node_id: L{str} | |
| 48 @param owner: JID of the new nodes's owner. | |
| 49 @type owner: L{jid.JID} | |
| 50 @param config: Configuration | |
| 51 @param type: Node type. Can be either C{'leaf'} or C{'collection'}. | |
| 52 @return: deferred that fires on creation. | |
| 53 """ | |
| 107 | 54 |
| 55 def delete_node(self, node_id): | |
| 111 | 56 """ Delete a node. |
| 57 | |
| 58 @param node_id: NodeID of the new node. | |
| 59 @type node_id: L{str} | |
| 60 @return: deferred that fires on deletion. | |
| 61 """ | |
| 107 | 62 |
| 63 def get_affiliations(self, entity): | |
| 111 | 64 """ Get all affiliations for entity. |
| 65 | |
| 66 The implementation should make sure, the passed owner JID is stripped | |
| 67 of the resource (e.g. using C{owner.userhostJID()}). | |
| 68 | |
| 69 @param entity: JID of the entity. | |
| 70 @type entity: L{jid.JID} | |
| 71 @return: deferred that returns a L{list} of tuples of the form | |
| 72 C{(node_id, affiliation)}, where C{node_id} is of the type | |
| 73 L{str} and C{affiliation} is one of C{'owner'}, C{'publisher'} | |
| 74 and C{'outcast'}. | |
| 75 """ | |
| 107 | 76 |
| 77 def get_subscriptions(self, entity): | |
| 111 | 78 """ Get all subscriptions for an entity. |
| 79 | |
| 80 The implementation should make sure, the passed owner JID is stripped | |
| 81 of the resource (e.g. using C{owner.userhostJID()}). | |
| 82 | |
| 83 @param entity: JID of the entity. | |
| 84 @type entity: L{jid.JID} | |
| 85 @return: deferred that returns a L{list} of tuples of the form | |
| 86 C{(node_id, subscriber, state)}, where C{node_id} is of the | |
| 87 type L{str}, C{subscriber} of the type {jid.JID}, and | |
| 88 C{state} is C{'subscribed'} or C{'pending'}. | |
| 89 """ | |
| 107 | 90 |
| 91 | |
| 92 class INode(Interface): | |
| 128 | 93 """ Interface to the class of objects that represent nodes. """ |
| 94 | |
| 107 | 95 def get_type(self): |
| 116 | 96 """ Get node's type. |
| 97 | |
| 98 @return: C{'leaf'} or C{'collection'}. | |
| 99 """ | |
| 107 | 100 |
| 101 def get_configuration(self): | |
| 116 | 102 """ Get node's configuration. |
| 103 | |
| 104 The configuration must at least have two options: | |
| 105 C{pubsub#persist_items}, and C{pubsub#deliver_payloads}. | |
| 106 | |
| 107 @return: L{dict} of configuration options. | |
| 108 """ | |
| 107 | 109 |
| 110 def get_meta_data(self): | |
| 116 | 111 """ Get node's meta data. |
| 112 | |
| 113 The meta data must be a superset of the configuration options, and | |
| 114 also at least should have a C{pubsub#node_type} entry. | |
| 115 | |
| 116 @return: L{dict} of meta data. | |
| 117 """ | |
| 107 | 118 |
| 119 def set_configuration(self, options): | |
|
125
0d7b95fb2549
Add documentation to set_configuration().
Ralph Meijer <ralphm@ik.nu>
parents:
119
diff
changeset
|
120 """ Set node's configuration. |
|
0d7b95fb2549
Add documentation to set_configuration().
Ralph Meijer <ralphm@ik.nu>
parents:
119
diff
changeset
|
121 |
|
0d7b95fb2549
Add documentation to set_configuration().
Ralph Meijer <ralphm@ik.nu>
parents:
119
diff
changeset
|
122 The elements of {options} will set the new values for those |
|
0d7b95fb2549
Add documentation to set_configuration().
Ralph Meijer <ralphm@ik.nu>
parents:
119
diff
changeset
|
123 configuration items. This means that only changing items have to |
|
0d7b95fb2549
Add documentation to set_configuration().
Ralph Meijer <ralphm@ik.nu>
parents:
119
diff
changeset
|
124 be given. |
|
0d7b95fb2549
Add documentation to set_configuration().
Ralph Meijer <ralphm@ik.nu>
parents:
119
diff
changeset
|
125 |
|
0d7b95fb2549
Add documentation to set_configuration().
Ralph Meijer <ralphm@ik.nu>
parents:
119
diff
changeset
|
126 @param options: a dictionary of configuration options. |
|
0d7b95fb2549
Add documentation to set_configuration().
Ralph Meijer <ralphm@ik.nu>
parents:
119
diff
changeset
|
127 @returns: a deferred that fires upon success. |
|
0d7b95fb2549
Add documentation to set_configuration().
Ralph Meijer <ralphm@ik.nu>
parents:
119
diff
changeset
|
128 """ |
| 107 | 129 |
| 130 def get_affiliation(self, entity): | |
|
119
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
131 """ Get affiliation of entity with this node. |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
132 |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
133 @param entity: JID of entity. |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
134 @type entity: L{jid.JID} |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
135 @return: deferred that returns C{'owner'}, C{'publisher'}, C{'outcast'} |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
136 or C{None}. |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
137 """ |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
138 |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
139 def get_subscription(self, subscriber): |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
140 """ Get subscription to this node of subscriber. |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
141 |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
142 @param subscriber: JID of the new subscriptions' entity. |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
143 @type subscriber: L{jid.JID} |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
144 @return: deferred that returns the subscription state (C{'subscribed'}, |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
145 C{'pending'} or C{None}). |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
146 """ |
| 107 | 147 |
| 148 def add_subscription(self, subscriber, state): | |
|
119
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
149 """ Add new subscription to this node with given state. |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
150 |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
151 @param subscriber: JID of the new subscriptions' entity. |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
152 @type subscriber: L{jid.JID} |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
153 @param state: C{'subscribed'} or C{'pending'} |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
154 @type state: L{str} |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
155 @return: deferred that fires on subscription. |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
156 """ |
| 107 | 157 |
| 158 def remove_subscription(self, subscriber): | |
|
119
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
159 """ Remove subscription to this node. |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
160 |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
161 @param subscriber: JID of the subscriptions' entity. |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
162 @type subscriber: L{jid.JID} |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
163 @return: deferred that fires on removal. |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
164 """ |
| 107 | 165 |
| 166 def get_subscribers(self): | |
|
119
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
167 """ Get list of subscribers to this node. |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
168 |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
169 Retrieves the list of entities that have a subscription to this |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
170 node. That is, having the state C{'subscribed'}. |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
171 |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
172 @return: a deferred that returns a L{list} of L{jid.JID}s. |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
173 """ |
| 107 | 174 |
|
146
b4490bdc77e5
Change semantics of Node.is_subscribed() to match all subscriptions for an
Ralph Meijer <ralphm@ik.nu>
parents:
145
diff
changeset
|
175 def is_subscribed(self, entity): |
|
b4490bdc77e5
Change semantics of Node.is_subscribed() to match all subscriptions for an
Ralph Meijer <ralphm@ik.nu>
parents:
145
diff
changeset
|
176 """ Returns whether entity has any subscription to this node. |
|
119
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
177 |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
178 Only returns C{True} when the subscription state (if present) is |
|
146
b4490bdc77e5
Change semantics of Node.is_subscribed() to match all subscriptions for an
Ralph Meijer <ralphm@ik.nu>
parents:
145
diff
changeset
|
179 C{'subscribed'} for any subscription that matches the bare JID. |
| 107 | 180 |
|
146
b4490bdc77e5
Change semantics of Node.is_subscribed() to match all subscriptions for an
Ralph Meijer <ralphm@ik.nu>
parents:
145
diff
changeset
|
181 @param subscriber: bare JID of the subscriptions' entity. |
|
119
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
182 @type subscriber: L{jid.JID} |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
183 @return: deferred that returns a L{bool}. |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
184 """ |
| 107 | 185 |
|
145
f393bccec4bc
Add get_affiliations to Node class in storage facilities in preparation of
Ralph Meijer <ralphm@ik.nu>
parents:
142
diff
changeset
|
186 def get_affiliations(self): |
|
f393bccec4bc
Add get_affiliations to Node class in storage facilities in preparation of
Ralph Meijer <ralphm@ik.nu>
parents:
142
diff
changeset
|
187 """ Get affiliations of entities with this node. |
|
f393bccec4bc
Add get_affiliations to Node class in storage facilities in preparation of
Ralph Meijer <ralphm@ik.nu>
parents:
142
diff
changeset
|
188 |
|
f393bccec4bc
Add get_affiliations to Node class in storage facilities in preparation of
Ralph Meijer <ralphm@ik.nu>
parents:
142
diff
changeset
|
189 @return: deferred that returns a L{list} of tuples (jid, affiliation), |
|
f393bccec4bc
Add get_affiliations to Node class in storage facilities in preparation of
Ralph Meijer <ralphm@ik.nu>
parents:
142
diff
changeset
|
190 where jid is a L(jid.JID) and affiliation is one of C{'owner'}, |
|
f393bccec4bc
Add get_affiliations to Node class in storage facilities in preparation of
Ralph Meijer <ralphm@ik.nu>
parents:
142
diff
changeset
|
191 C{'publisher'}, C{'outcast'}. |
|
f393bccec4bc
Add get_affiliations to Node class in storage facilities in preparation of
Ralph Meijer <ralphm@ik.nu>
parents:
142
diff
changeset
|
192 """ |
|
f393bccec4bc
Add get_affiliations to Node class in storage facilities in preparation of
Ralph Meijer <ralphm@ik.nu>
parents:
142
diff
changeset
|
193 |
| 107 | 194 class ILeafNode(Interface): |
| 128 | 195 """ Interface to the class of objects that represent leaf nodes. """ |
| 196 | |
| 107 | 197 def store_items(self, items, publisher): |
| 128 | 198 """ Store items in persistent storage for later retrieval. |
| 199 | |
| 200 @param items: The list of items to be stored. Each item is the | |
| 201 L{domish} representation of the XML fragment as defined | |
| 202 for C{<item/>} in the | |
| 203 C{http://jabber.org/protocol/pubsub} namespace. | |
| 204 @type items: L{list} of {domish.Element} | |
| 205 @param publisher: JID of the publishing entity. | |
| 206 @type publisher: L{jid.JID} | |
| 207 @return: deferred that fires upon success. | |
| 208 """ | |
| 107 | 209 |
| 210 def remove_items(self, item_ids): | |
| 128 | 211 """ Remove items by id |
| 212 | |
| 213 @param item_ids: L{list} of item ids. | |
|
142
812300cdbc22
Changed behaviour of retraction of items so that only the actually deleted
Ralph Meijer <ralphm@ik.nu>
parents:
128
diff
changeset
|
214 @return: deferred that fires with a L{list} of ids of the items that |
|
812300cdbc22
Changed behaviour of retraction of items so that only the actually deleted
Ralph Meijer <ralphm@ik.nu>
parents:
128
diff
changeset
|
215 were deleted |
| 128 | 216 """ |
| 107 | 217 |
| 218 def get_items(self, max_items=None): | |
| 128 | 219 """ Get items. |
| 220 | |
| 221 If C{max_items} is not given, all items in the node are returned, | |
| 222 just like C{get_items_by_id}. Otherwise, C{max_items} limits | |
| 223 the returned items to a maximum of that number of most recently | |
| 224 published items. | |
| 225 | |
| 226 @param max_items: if given, a natural number (>0) that limits the | |
| 227 returned number of items. | |
|
142
812300cdbc22
Changed behaviour of retraction of items so that only the actually deleted
Ralph Meijer <ralphm@ik.nu>
parents:
128
diff
changeset
|
228 @return: deferred that fires with a L{list} of found items. |
| 128 | 229 """ |
| 107 | 230 |
| 231 def get_items_by_id(self, item_ids): | |
| 128 | 232 """ Get items by item id. |
| 233 | |
| 234 Each item in the returned list is a unicode string that | |
| 235 represent the XML of the item as it was published, including the | |
| 236 item wrapper with item id. | |
| 237 | |
| 238 @param item_ids: L{list} of item ids. | |
|
142
812300cdbc22
Changed behaviour of retraction of items so that only the actually deleted
Ralph Meijer <ralphm@ik.nu>
parents:
128
diff
changeset
|
239 @return: deferred that fires with a L{list} of found items. |
| 128 | 240 """ |
| 107 | 241 |
| 242 def purge(self): | |
| 128 | 243 """ Purge node of all items in persistent storage. |
| 244 | |
| 245 @return: deferred that fires when the node has been purged. | |
| 246 """ | |
| 107 | 247 |
| 248 | |
| 249 class ISubscription(Interface): | |
| 250 """ """ |