Statistics
| Branch: | Tag: | Revision:

root / pithos / backends / base.py @ 3436eeb0

History | View | Annotate | Download (11.4 kB)

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