Source Code for Module elisa.core.components.resource_provider

  1  # -*- coding: utf-8 -*- 
  2  # Moovida - Home multimedia server 
  3  # Copyright (C) 2006-2009 Fluendo Embedded S.L. (www.fluendo.com). 
  4  # All rights reserved. 
  5  # 
  6  # This file is available under one of two license agreements. 
  7  # 
  8  # This file is licensed under the GPL version 3. 
  9  # See "LICENSE.GPL" in the root of this distribution including a special 
 10  # exception to use Moovida with Fluendo's plugins. 
 11  # 
 12  # The GPL part of Moovida is also available under a commercial licensing 
 13  # agreement from Fluendo. 
 14  # See "LICENSE.Moovida" in the root directory of this distribution package 
 15  # for details on that license. 
 16   
 17  """ 
 18  Provides access to resources 
 19  """ 
 20   
 21  __maintainer__ = 'Florian Boucault <florian@fluendo.com>' 
 22  __maintainer2__ = 'Benjamin Kampmann <benjamin@fluendo.com>' 
 23   
 24   
 25  from elisa.core.component import Component 
 26   
 27  from elisa.core.utils import defer 
 28   
 29 -class ResourceNotFound(Exception): 
 30      """ 
 31      Exception raised by a resource provider if a requested resource cannot 
 32      be found.  
 33   
 34      For instance, that is what should be raised when an HTTP 404 response code 
 35      is obtained while trying to get the resource. 
 36      """ 
 37   
 38   
 39 -class ResourceProvider(Component): 
 40      """ 
 41      Responsible for accessing resources following REST architecture 
 42      principles. 
 43   
 44      Accessing a resource is done through a URI that points to it. Possible 
 45      operations on resources are defined by the REST principles and allow 
 46      retrieval, creation, update and removal of resources. 
 47   
 48      For more information about REST, Roy Fielding's thesis is helpful: 
 49      http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm 
 50   
 51      A resource can be identified with a URI. This is also called a pointer 
 52      or a link. 
 53   
 54   
 55      Example: 
 56   
 57      You could have a list of music albums stored at some place designated by 
 58      the following URI:: 
 59   
 60          elisa://localhost/albums 
 61   
 62      When the user decides to access the resource behind this URI, a retrieval 
 63      request is sent to the L{elisa.resource_manager.ResourceManager}. 
 64      It holds all the ResourceProviders and forwards the request to one that 
 65      can handle it. This is made possible by trying to match the URI to their 
 66      regular expressions. 
 67   
 68      A resource in Elisa is stored as a L{elisa.core.components.model.Model}. 
 69      The chosen ResourceProvider returns the Model (in this example, it would 
 70      be something like an AlbumsListModel) and starts to fill it asynchronously. 
 71      When it is complete, the L{elisa.core.utils.defer.Deferred} is fired. 
 72   
 73      @cvar supported_uri: regular expression defining what URIs a 
 74                           ResourceProvider can handle 
 75      @type supported_uri: str 
 76      """ 
 77   
 78 -    def get(self, uri, context_model=None): 
 79          """ 
 80          Return a resource that L{uri} is pointing to. A URI can point to 
 81          any kind of resource. Resources are returned as models. 
 82   
 83          The model that is returned does not always already contain all the 
 84          resource. The deferred is fired when the resource loading is complete. 
 85   
 86          @param uri:           URI pointing to the resource 
 87          @type uri:            L{elisa.core.media_uri.MediaUri} 
 88          @param context_model: the URI often comes from a certain context. 
 89                                For example a URI pointing to a MusicAlbum can 
 90                                come from a Model that could contain the album 
 91                                cover or the album name. If the context_model is 
 92                                provided the resource_provider should try to 
 93                                reuse its data if possible. 
 94          @type context_model:  L{elisa.core.components.model.Model} 
 95   
 96          @return:              a new model and a deferred fired when the 
 97                                model is fully loaded 
 98          @rtype:               tuple of L{elisa.core.components.model.Model} 
 99                                L{elisa.core.utils.defer.Deferred} 
100          """ 
101          return (None, defer.fail(NotImplementedError())) 
102   
103 -    def post(self, uri, **parameters): 
104          """ 
105          Update the resource pointed by L{uri} with L{parameters}. 
106   
107          @param uri:        URI pointing to the resource to update 
108          @type uri:         L{elisa.core.media_uri.MediaUri} 
109          @param parameters: parameters of the resource that should be updated 
110   
111          @return:           a deferred fired when the parameters got posted 
112          @rtype:            L{elisa.core.utils.defer.Deferred} 
113          """ 
114          return defer.fail(NotImplementedError()) 
115   
116 -    def put(self, source_uri, container_uri, source_model=None): 
117          """ 
118          Put one resource into another. Both resources are identified with URIs. 
119   
120          @param source_uri:    URI pointing to the resource that should be put 
121                                into the other one 
122          @type source_uri:     L{elisa.core.media_uri.MediaUri} 
123          @param container_uri: URI pointing to the resource that should receive 
124                                the resource 
125          @type container_uri:  L{elisa.core.media_uri.MediaUri} 
126          @param source_model:  Often the resource behind the source_uri is 
127                                already existing as a model-representation. To 
128                                prevent from doing a 'get' for the given 
129                                source_uri this model can also be given to the  
130                                put request. 
131          @type source_model:   L{elisa.core.components.model.Model} 
132   
133          @return:              a deferred fired when the resource got put 
134          @rtype:               L{elisa.core.utils.defer.Deferred} 
135          """ 
136          return defer.fail(NotImplementedError()) 
137   
138 -    def delete(self, uri): 
139          """ 
140          Delete a Resource represented by a URI. 
141   
142          @param uri: URI pointing to the resource that should be deleted 
143          @type uri:  L{elisa.media_uri.MediaUri} 
144   
145          @return:    a deferred fired when the resource got deleted 
146          @rtype:     L{elisa.core.utils.defer.Deferred} 
147          """ 
148          return defer.fail(NotImplementedError()) 
149