Mercurial > libervia-pubsub
annotate idavoll/storage.py @ 155:5191ba7c4df8
Work towards first release 0.5.0.
- Add licensing information (MIT)
- Improve installation instructions.
- Use new plugins framework in twisted.
| author | Ralph Meijer <ralphm@ik.nu> |
|---|---|
| date | Mon, 21 Aug 2006 16:05:35 +0000 |
| parents | ea8b4189ae3b |
| 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 """ """ |