Mercurial > libervia-pubsub
annotate idavoll/storage.py @ 140:d79f0816f6c3
Revert changes to error handling into disco calls.
Bump version.
| author | Ralph Meijer <ralphm@ik.nu> |
|---|---|
| date | Wed, 27 Apr 2005 20:22:51 +0000 |
| parents | b27a66637a10 |
| children | 812300cdbc22 |
| 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 |
| 128 | 20 class ItemNotFound(Error): |
| 21 pass | |
| 22 | |
| 107 | 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 |
| 175 def is_subscribed(self, subscriber): | |
|
119
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
176 """ Returns whether subscriber has a subscription to this node. |
|
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 |
|
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
179 C{'subscribed'}. |
| 107 | 180 |
|
119
3e7a7426f518
Added SubscriptionNotFound and SubscriptionExists errors.
Ralph Meijer <ralphm@ik.nu>
parents:
116
diff
changeset
|
181 @param subscriber: JID of the subscriptions' entity. |
|
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 |
| 186 class ILeafNode(Interface): | |
| 128 | 187 """ Interface to the class of objects that represent leaf nodes. """ |
| 188 | |
| 107 | 189 def store_items(self, items, publisher): |
| 128 | 190 """ Store items in persistent storage for later retrieval. |
| 191 | |
| 192 @param items: The list of items to be stored. Each item is the | |
| 193 L{domish} representation of the XML fragment as defined | |
| 194 for C{<item/>} in the | |
| 195 C{http://jabber.org/protocol/pubsub} namespace. | |
| 196 @type items: L{list} of {domish.Element} | |
| 197 @param publisher: JID of the publishing entity. | |
| 198 @type publisher: L{jid.JID} | |
| 199 @return: deferred that fires upon success. | |
| 200 """ | |
| 107 | 201 |
| 202 def remove_items(self, item_ids): | |
| 128 | 203 """ Remove items by id |
| 204 | |
| 205 @param item_ids: L{list} of item ids. | |
| 206 @return: deferred that fires when all given items were deleted, or | |
| 207 a failure if one of them was not found. | |
| 208 """ | |
| 107 | 209 |
| 210 def get_items(self, max_items=None): | |
| 128 | 211 """ Get items. |
| 212 | |
| 213 If C{max_items} is not given, all items in the node are returned, | |
| 214 just like C{get_items_by_id}. Otherwise, C{max_items} limits | |
| 215 the returned items to a maximum of that number of most recently | |
| 216 published items. | |
| 217 | |
| 218 @param max_items: if given, a natural number (>0) that limits the | |
| 219 returned number of items. | |
| 220 @return: deferred that fires with a C{list} of found items. | |
| 221 """ | |
| 107 | 222 |
| 223 def get_items_by_id(self, item_ids): | |
| 128 | 224 """ Get items by item id. |
| 225 | |
| 226 Each item in the returned list is a unicode string that | |
| 227 represent the XML of the item as it was published, including the | |
| 228 item wrapper with item id. | |
| 229 | |
| 230 @param item_ids: L{list} of item ids. | |
| 231 @return: deferred that fires with a C{list} of found items. | |
| 232 """ | |
| 107 | 233 |
| 234 def purge(self): | |
| 128 | 235 """ Purge node of all items in persistent storage. |
| 236 | |
| 237 @return: deferred that fires when the node has been purged. | |
| 238 """ | |
| 107 | 239 |
| 240 | |
| 241 class ISubscription(Interface): | |
| 242 """ """ |