| 1 |
# Copyright (c) 2013 Red Hat, Inc. |
| 2 |
# |
| 3 |
# Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 |
# you may not use this file except in compliance with the License. |
| 5 |
# You may obtain a copy of the License at |
| 6 |
# |
| 7 |
# http://www.apache.org/licenses/LICENSE-2.0 |
| 8 |
# |
| 9 |
# Unless required by applicable law or agreed to in writing, software |
| 10 |
# distributed under the License is distributed on an "AS IS" BASIS, |
| 11 |
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or |
| 12 |
# implied. |
| 13 |
# See the License for the specific language governing permissions and |
| 14 |
# limitations under the License. |
| 15 |
|
| 16 |
import re |
| 17 |
|
| 18 |
from zaqarclient._i18n import _ # noqa |
| 19 |
from zaqarclient.queues.v2 import claim as claim_api |
| 20 |
from zaqarclient.queues.v2 import core |
| 21 |
from zaqarclient.queues.v2 import iterator |
| 22 |
from zaqarclient.queues.v2 import message |
| 23 |
|
| 24 |
# NOTE(wanghao): This is copied from Zaqar server side, so if server have |
| 25 |
# updated it someday, we should update it here to keep consistent. |
| 26 |
QUEUE_NAME_REGEX = re.compile(r'^[a-zA-Z0-9_\-]+$') |
| 27 |
|
| 28 |
|
| 29 |
class Queue: |
| 30 |
|
| 31 |
message_module = message |
| 32 |
|
| 33 |
def __init__(self, client, name, href=None, metadata=None, |
| 34 |
auto_create=True, force_create=False): |
| 35 |
"""Initialize queue object |
| 36 |
|
| 37 |
:param client: The client object of Zaqar. |
| 38 |
:type client: `object` |
| 39 |
:param name: Name of the queue. |
| 40 |
:type name: str |
| 41 |
:param href : Hypertext Reference. |
| 42 |
:type href: str |
| 43 |
:param metadata : A metadata object of the queue. |
| 44 |
:type metadata: `dict` |
| 45 |
:param auto_create: If create the queue automatically in database. |
| 46 |
:type auto_create: `boolean` |
| 47 |
:param force_create: If create the queue and skip the API version |
| 48 |
check, which is useful for command line interface. |
| 49 |
:type force_create: `boolean` |
| 50 |
:returns: The queue object. |
| 51 |
""" |
| 52 |
self.client = client |
| 53 |
|
| 54 |
if name == "": |
| 55 |
raise ValueError(_('Queue name does not have a value')) |
| 56 |
|
| 57 |
if not QUEUE_NAME_REGEX.match(str(name)): |
| 58 |
raise ValueError(_('The queue name may only contain ASCII ' |
| 59 |
'letters, digits, underscores and dashes.')) |
| 60 |
|
| 61 |
# NOTE(flaper87) Queue Info |
| 62 |
self._name = name |
| 63 |
self._metadata = metadata |
| 64 |
self._href = href |
| 65 |
|
| 66 |
# NOTE(flwang): If force_create is True, then even though auto_create |
| 67 |
# is not True, the queue should be created anyway. |
| 68 |
if auto_create or force_create: |
| 69 |
self.ensure_exists(force_create=force_create) |
| 70 |
|
| 71 |
@property |
| 72 |
def name(self): |
| 73 |
return self._name |
| 74 |
|
| 75 |
@property |
| 76 |
def href(self): |
| 77 |
return self._href |
| 78 |
|
| 79 |
@property |
| 80 |
def metadata_dict(self): |
| 81 |
return dict(self.metadata()) |
| 82 |
|
| 83 |
def exists(self): |
| 84 |
"""Checks if the queue exists.""" |
| 85 |
req, trans = self.client._request_and_transport() |
| 86 |
return core.queue_exists(trans, req, self._name) |
| 87 |
|
| 88 |
def ensure_exists(self, force_create=False): |
| 89 |
"""Ensures a queue exists |
| 90 |
|
| 91 |
This method is not race safe, |
| 92 |
the queue could've been deleted |
| 93 |
right after it was called. |
| 94 |
""" |
| 95 |
req, trans = self.client._request_and_transport() |
| 96 |
if force_create: |
| 97 |
core.queue_create(trans, req, self._name) |
| 98 |
|
| 99 |
def metadata(self, new_meta=None, force_reload=False): |
| 100 |
"""Get metadata and return it |
| 101 |
|
| 102 |
:param new_meta: A dictionary containing |
| 103 |
an updated metadata object. If present |
| 104 |
the queue metadata will be updated in |
| 105 |
remote server. If the new_meta is empty, |
| 106 |
the metadata object will be cleared. |
| 107 |
:type new_meta: `dict` |
| 108 |
:param force_reload: Whether to ignored the |
| 109 |
cached metadata and reload it from the |
| 110 |
server. |
| 111 |
:type force_reload: `bool` |
| 112 |
|
| 113 |
:returns: The queue metadata. |
| 114 |
""" |
| 115 |
req, trans = self.client._request_and_transport() |
| 116 |
|
| 117 |
# TODO(flaper87): Cache with timeout |
| 118 |
if new_meta is None and self._metadata and not force_reload: |
| 119 |
return self._metadata |
| 120 |
else: |
| 121 |
self._metadata = core.queue_get(trans, req, self._name) |
| 122 |
|
| 123 |
if new_meta is not None: |
| 124 |
temp_metadata = self._metadata.copy() |
| 125 |
changes = [] |
| 126 |
for key, value in new_meta.items(): |
| 127 |
# If key exists, replace it's value. |
| 128 |
if self._metadata.get(key, None) is not None: |
| 129 |
changes.append({'op': 'replace', |
| 130 |
'path': '/metadata/%s' % key, |
| 131 |
'value': value}) |
| 132 |
temp_metadata.pop(key) |
| 133 |
# If not, add the new key. |
| 134 |
else: |
| 135 |
changes.append({'op': 'add', |
| 136 |
'path': '/metadata/%s' % key, |
| 137 |
'value': value}) |
| 138 |
# For the keys which are not included in the new metadata, remove |
| 139 |
# them. |
| 140 |
for key, value in temp_metadata.items(): |
| 141 |
changes.append({'op': 'remove', |
| 142 |
'path': '/metadata/%s' % key}) |
| 143 |
|
| 144 |
self._metadata = core.queue_update(trans, req, self._name, |
| 145 |
metadata=changes) |
| 146 |
|
| 147 |
return self._metadata |
| 148 |
|
| 149 |
@property |
| 150 |
def stats(self): |
| 151 |
req, trans = self.client._request_and_transport() |
| 152 |
return core.queue_get_stats(trans, req, self._name) |
| 153 |
|
| 154 |
def delete(self): |
| 155 |
req, trans = self.client._request_and_transport() |
| 156 |
core.queue_delete(trans, req, self._name) |
| 157 |
|
| 158 |
# Messages API |
| 159 |
|
| 160 |
def post(self, messages): |
| 161 |
"""Posts one or more messages to this queue |
| 162 |
|
| 163 |
:param messages: One or more messages to post |
| 164 |
:type messages: `list` or `dict` |
| 165 |
|
| 166 |
:returns: A dict with the result of this operation. |
| 167 |
:rtype: `dict` |
| 168 |
""" |
| 169 |
if not isinstance(messages, list): |
| 170 |
messages = [messages] |
| 171 |
|
| 172 |
messages = {'messages': messages} |
| 173 |
|
| 174 |
req, trans = self.client._request_and_transport() |
| 175 |
|
| 176 |
# TODO(flaper87): Return a list of messages |
| 177 |
return core.message_post(trans, req, |
| 178 |
self._name, messages) |
| 179 |
|
| 180 |
def message(self, message_id): |
| 181 |
"""Gets a message by id |
| 182 |
|
| 183 |
:param message_id: Message's reference |
| 184 |
:type message_id: str |
| 185 |
|
| 186 |
:returns: A message |
| 187 |
:rtype: `dict` |
| 188 |
""" |
| 189 |
req, trans = self.client._request_and_transport() |
| 190 |
msg = core.message_get(trans, req, self._name, |
| 191 |
message_id) |
| 192 |
return self.message_module.Message(self, **msg) |
| 193 |
|
| 194 |
def messages(self, *messages, **params): |
| 195 |
"""Gets a list of messages from the server |
| 196 |
|
| 197 |
This method returns a list of messages, it can be |
| 198 |
used to retrieve a set of messages by id or to |
| 199 |
walk through the active messages by using the |
| 200 |
collection endpoint. |
| 201 |
|
| 202 |
The `messages` and `params` params are mutually exclusive |
| 203 |
and the former has the priority. |
| 204 |
|
| 205 |
:param messages: List of messages' ids to retrieve. |
| 206 |
:type messages: *args of str |
| 207 |
|
| 208 |
:param params: Filters to use for getting messages |
| 209 |
:type params: **kwargs dict. |
| 210 |
|
| 211 |
:returns: List of messages |
| 212 |
:rtype: `list` |
| 213 |
""" |
| 214 |
req, trans = self.client._request_and_transport() |
| 215 |
|
| 216 |
# TODO(flaper87): Return a MessageIterator. |
| 217 |
# This iterator should handle limits, pagination |
| 218 |
# and messages deserialization. |
| 219 |
|
| 220 |
if messages: |
| 221 |
msgs = core.message_get_many(trans, req, |
| 222 |
self._name, messages) |
| 223 |
else: |
| 224 |
# NOTE(flaper87): It's safe to access messages |
| 225 |
# directly. If something wrong happens, the core |
| 226 |
# API will raise the right exceptions. |
| 227 |
msgs = core.message_list(trans, req, |
| 228 |
self._name, |
| 229 |
**params) |
| 230 |
|
| 231 |
return iterator._Iterator(self.client, |
| 232 |
msgs, |
| 233 |
'messages', |
| 234 |
self.message_module.create_object(self)) |
| 235 |
|
| 236 |
def delete_messages(self, *messages): |
| 237 |
"""Deletes a set of messages from the server |
| 238 |
|
| 239 |
:param messages: List of messages' ids to delete. |
| 240 |
:type messages: *args of str |
| 241 |
""" |
| 242 |
|
| 243 |
req, trans = self.client._request_and_transport() |
| 244 |
return core.message_delete_many(trans, req, self._name, |
| 245 |
set(messages)) |
| 246 |
|
| 247 |
def pop(self, count=1): |
| 248 |
"""Pop `count` messages from the server |
| 249 |
|
| 250 |
:param count: Number of messages to pop. |
| 251 |
:type count: int |
| 252 |
|
| 253 |
:returns: List of messages |
| 254 |
:rtype: `list` |
| 255 |
""" |
| 256 |
|
| 257 |
req, trans = self.client._request_and_transport() |
| 258 |
msgs = core.message_pop(trans, req, self._name, count=count) |
| 259 |
return iterator._Iterator(self.client, |
| 260 |
msgs, |
| 261 |
'messages', |
| 262 |
self.message_module.create_object(self)) |
| 263 |
|
| 264 |
def signed_url(self, paths=None, ttl_seconds=None, methods=None): |
| 265 |
req, trans = self.client._request_and_transport() |
| 266 |
return core.signed_url_create(trans, req, self._name, paths=paths, |
| 267 |
ttl_seconds=ttl_seconds, methods=methods) |
| 268 |
|
| 269 |
def subscriptions(self, detailed=False, marker=None, limit=20): |
| 270 |
return self.client.subscriptions(queue_name=self._name, |
| 271 |
detailed=detailed, |
| 272 |
marker=marker, |
| 273 |
limit=limit) |
| 274 |
|
| 275 |
def purge(self, resource_types=None): |
| 276 |
req, trans = self.client._request_and_transport() |
| 277 |
core.queue_purge(trans, req, self._name, |
| 278 |
resource_types=resource_types) |
| 279 |
|
| 280 |
def claim(self, id=None, ttl=None, grace=None, |
| 281 |
limit=None): |
| 282 |
return claim_api.Claim(self, id=id, ttl=ttl, grace=grace, limit=limit) |
| 283 |
|
| 284 |
|
| 285 |
def create_object(parent): |
| 286 |
return lambda args: Queue(parent, args["name"], href=args.get("href"), |
| 287 |
metadata=args.get("metadata"), auto_create=False) |