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