code.grnet.gr Git - pithos/blob - pithos/backends/base.py

   1 # Copyright 2011 GRNET S.A. All rights reserved.
   2 #
   3 # Redistribution and use in source and binary forms, with or
   4 # without modification, are permitted provided that the following
   5 # conditions are met:
   6 #
   7 #   1. Redistributions of source code must retain the above
   8 #      copyright notice, this list of conditions and the following
   9 #      disclaimer.
  10 #
  11 #   2. Redistributions in binary form must reproduce the above
  12 #      copyright notice, this list of conditions and the following
  13 #      disclaimer in the documentation and/or other materials
  14 #      provided with the distribution.
  15 #
  16 # THIS SOFTWARE IS PROVIDED BY GRNET S.A. ``AS IS'' AND ANY EXPRESS
  17 # OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18 # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19 # PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL GRNET S.A OR
  20 # CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  21 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  22 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  23 # USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  24 # AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  26 # ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27 # POSSIBILITY OF SUCH DAMAGE.
  28 #
  29 # The views and conclusions contained in the software and
  30 # documentation are those of the authors and should not be
  31 # interpreted as representing official policies, either expressed
  32 # or implied, of GRNET S.A.
  33
  34 class BaseBackend(object):
  35     """Abstract backend class that serves as a reference for actual implementations.
  36
  37     The purpose of the backend is to provide the necessary functions for handling data
  38     and metadata. It is responsible for the actual storage and retrieval of information.
  39
  40     Note that the account level is always valid as it is checked from another subsystem.
  41
  42     The following variables should be available:
  43         'hash_algorithm': Suggested is 'sha256'
  44         'block_size': Suggested is 4MB
  45     """
  46
  47     def delete_account(self, user, account):
  48         """Delete the account with the given name.
  49
  50         Raises:
  51             IndexError: Account is not empty
  52         """
  53         return
  54
  55     def get_account_meta(self, user, account, until=None):
  56         """Return a dictionary with the account metadata.
  57
  58         The keys returned are all user-defined, except:
  59             'name': The account name
  60             'count': The number of containers (or 0)
  61             'bytes': The total data size (or 0)
  62             'modified': Last modification timestamp (overall)
  63             'until_timestamp': Last modification until the timestamp provided
  64         """
  65         return {}
  66
  67     def update_account_meta(self, user, account, meta, replace=False):
  68         """Update the metadata associated with the account.
  69
  70         Parameters:
  71             'meta': Dictionary with metadata to update
  72             'replace': Replace instead of update
  73         """
  74         return
  75
  76     def list_containers(self, user, account, marker=None, limit=10000, until=None):
  77         """Return a list of container (name, version_id) tuples existing under an account.
  78
  79         Parameters:
  80             'marker': Start list from the next item after 'marker'
  81             'limit': Number of containers to return
  82         """
  83         return []
  84
  85     def put_container(self, user, account, container):
  86         """Create a new container with the given name.
  87
  88         Raises:
  89             NameError: Container already exists
  90         """
  91         return
  92
  93     def delete_container(self, user, account, container):
  94         """Delete the container with the given name.
  95
  96         Raises:
  97             NameError: Container does not exist
  98             IndexError: Container is not empty
  99         """
 100         return
 101
 102     def get_container_meta(self, user, account, container, until=None):
 103         """Return a dictionary with the container metadata.
 104
 105         The keys returned are all user-defined, except:
 106             'name': The container name
 107             'count': The number of objects
 108             'bytes': The total data size
 109             'modified': Last modification timestamp (overall)
 110             'until_timestamp': Last modification until the timestamp provided
 111
 112         Raises:
 113             NameError: Container does not exist
 114         """
 115         return {}
 116
 117     def update_container_meta(self, user, account, container, meta, replace=False):
 118         """Update the metadata associated with the container.
 119
 120         Parameters:
 121             'meta': Dictionary with metadata to update
 122             'replace': Replace instead of update
 123
 124         Raises:
 125             NameError: Container does not exist
 126         """
 127         return
 128
 129     def list_objects(self, user, account, container, prefix='', delimiter=None, marker=None, limit=10000, virtual=True, keys=[], until=None):
 130         """Return a list of object (name, version_id) tuples existing under a container.
 131
 132         Parameters:
 133             'prefix': List objects starting with 'prefix'
 134             'delimiter': Return unique names before 'delimiter' and after 'prefix'
 135             'marker': Start list from the next item after 'marker'
 136             'limit': Number of objects to return
 137             'virtual': If not set, the result will only include names starting\
 138                        with 'prefix' and ending without a 'delimiter' or with\
 139                        the first occurance of the 'delimiter' after 'prefix'.\
 140                        If set, the result will include all names after 'prefix',\
 141                        up to and including the 'delimiter' if it is found
 142             'keys': Include objects that have meta with the keys in the list
 143
 144         Raises:
 145             NameError: Container does not exist
 146         """
 147         return []
 148
 149     def list_object_meta(self, user, account, container, until=None):
 150         """Return a list with all the container's object meta keys.
 151
 152         Raises:
 153             NameError: Container does not exist
 154         """
 155         return []
 156
 157     def get_object_meta(self, user, account, container, name, version=None):
 158         """Return a dictionary with the object metadata.
 159
 160         The keys returned are all user-defined, except:
 161             'name': The object name
 162             'bytes': The total data size
 163             'modified': Last modification timestamp (overall)
 164             'version': The version identifier
 165             'version_timestamp': The version's modification timestamp
 166
 167         Raises:
 168             NameError: Container/object does not exist
 169             IndexError: Version does not exist
 170         """
 171         return {}
 172
 173     def update_object_meta(self, user, account, container, name, meta, replace=False):
 174         """Update the metadata associated with the object.
 175
 176         Parameters:
 177             'meta': Dictionary with metadata to update.
 178             'replace': Replace instead of update
 179
 180         Raises:
 181             NameError: Container/object does not exist
 182         """
 183         return
 184
 185     def get_object_permissions(self, user, account, container, name):
 186         """Return a dictionary with the object permissions.
 187
 188         The keys are:
 189             'public': The object is readable by all and available at a public URL
 190             'private': No permissions set
 191             'read': The object is readable by the users/groups in the list
 192             'write': The object is writable by the users/groups in the list
 193
 194         Raises:
 195             NameError: Container/object does not exist
 196         """
 197         return {}
 198
 199     def update_object_permissions(self, user, account, container, name, permissions):
 200         """Update the permissions associated with the object.
 201
 202         Parameters:
 203             'permissions': Dictionary with permissions to update
 204
 205         Raises:
 206             NameError: Container/object does not exist
 207             ValueError: Invalid users/groups in permissions
 208             AttributeError: Can not set permissions, as this object\
 209                 is already shared/private by another object higher\
 210                 in the hierarchy, or setting permissions here will\
 211                 invalidate other permissions deeper in the hierarchy
 212         """
 213         return
 214
 215     def get_object_hashmap(self, user, account, container, name, version=None):
 216         """Return the object's size and a list with partial hashes.
 217
 218         Raises:
 219             NameError: Container/object does not exist
 220             IndexError: Version does not exist
 221         """
 222         return 0, []
 223
 224     def update_object_hashmap(self, user, account, container, name, size, hashmap, meta={}, replace_meta=False, permissions={}):
 225         """Create/update an object with the specified size and partial hashes.
 226
 227         Parameters:
 228             'dest_meta': Dictionary with metadata to change
 229             'replace_meta': Replace metadata instead of update
 230             'permissions': Updated object permissions
 231
 232         Raises:
 233             NameError: Container does not exist
 234             ValueError: Invalid users/groups in permissions
 235             AttributeError: Can not set permissions
 236         """
 237         return
 238
 239     def copy_object(self, user, account, src_container, src_name, dest_container, dest_name, dest_meta={}, replace_meta=False, permissions={}, src_version=None):
 240         """Copy an object's data and metadata.
 241
 242         Parameters:
 243             'dest_meta': Dictionary with metadata to change from source to destination
 244             'replace_meta': Replace metadata instead of update
 245             'permissions': New object permissions
 246             'src_version': Copy from the version provided
 247
 248         Raises:
 249             NameError: Container/object does not exist
 250             IndexError: Version does not exist
 251             ValueError: Invalid users/groups in permissions
 252             AttributeError: Can not set permissions
 253         """
 254         return
 255
 256     def move_object(self, user, account, src_container, src_name, dest_container, dest_name, dest_meta={}, replace_meta=False, permissions={}):
 257         """Move an object's data and metadata.
 258
 259         Parameters:
 260             'dest_meta': Dictionary with metadata to change from source to destination
 261             'replace_meta': Replace metadata instead of update
 262             'permissions': New object permissions
 263
 264         Raises:
 265             NameError: Container/object does not exist
 266             ValueError: Invalid users/groups in permissions
 267             AttributeError: Can not set permissions
 268         """
 269         return
 270
 271     def delete_object(self, user, account, container, name):
 272         """Delete an object.
 273
 274         Raises:
 275             NameError: Container/object does not exist
 276         """
 277         return
 278
 279     def list_versions(self, user, account, container, name):
 280         """Return a list of all (version, version_timestamp) tuples for an object."""
 281         return []
 282
 283     def get_block(self, hash):
 284         """Return a block's data.
 285
 286         Raises:
 287             NameError: Block does not exist
 288         """
 289         return ''
 290
 291     def put_block(self, data):
 292         """Store a block and return the hash."""
 293         return 0
 294
 295     def update_block(self, hash, data, offset=0):
 296         """Update a known block and return the hash.
 297
 298         Raises:
 299             IndexError: Offset or data outside block limits
 300         """
 301         return 0