Package muntjac :: Package data :: Module buffered
[hide private]
[frames] | no frames]

Source Code for Module muntjac.data.buffered

  1  # Copyright (C) 2012 Vaadin Ltd.  
  2  # Copyright (C) 2012 Richard Lincoln 
  3  #  
  4  # Licensed under the Apache License, Version 2.0 (the "License");  
  5  # you may not use this file except in compliance with the License.  
  6  # You may obtain a copy of the License at  
  7  #  
  8  #     http://www.apache.org/licenses/LICENSE-2.0  
  9  #  
 10  # Unless required by applicable law or agreed to in writing, software  
 11  # distributed under the License is distributed on an "AS IS" BASIS,  
 12  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
 13  # See the License for the specific language governing permissions and  
 14  # limitations under the License. 
 15   
 16  """Defines the interface to commit and discard changes to an object.""" 
 17   
 18  import sys 
 19   
 20  from muntjac.terminal.sys_error import SysError 
 21  from muntjac.terminal.error_message import IErrorMessage 
 22  from muntjac.data.validatable import IValidatable 
 23   
 24   
25 -class IBuffered(object):
26 """Defines the interface to commit and discard changes to an object, 27 supporting read-through and write-through modes. 28 29 I{Read-through mode} means that the value read from the buffered object 30 is constantly up to date with the data source. I{Write-through} mode 31 means that all changes to the object are immediately updated to the data 32 source. 33 34 Since these modes are independent, their combinations may result in some 35 behaviour that may sound surprising. 36 37 For example, if a C{IBuffered} object is in read-through mode but 38 not in write-through mode, the result is an object whose value is updated 39 directly from the data source only if it's not locally modified. If the 40 value is locally modified, retrieving the value from the object would 41 result in a value that is different than the one stored in the data source, 42 even though the object is in read-through mode. 43 44 @author: Vaadin Ltd. 45 @author: Richard Lincoln 46 @version: 1.1.2 47 """ 48
49 - def commit(self):
50 """Updates all changes since the previous commit to the data source. 51 The value stored in the object will always be updated into the data 52 source when C{commit} is called. 53 54 @raise SourceException: 55 if the operation fails because of an exception is thrown by 56 the data source. The cause is included in the exception. 57 @raise InvalidValueException: 58 if the operation fails because validation is enabled and 59 the values do not validate 60 """ 61 raise NotImplementedError
62 63
64 - def discard(self):
65 """Discards all changes since last commit. The object updates its value 66 from the data source. 67 68 @raise SourceException: 69 if the operation fails because of an exception is thrown by 70 the data source. The cause is included in the exception. 71 """ 72 raise NotImplementedError
73 74
75 - def isWriteThrough(self):
76 """Tests if the object is in write-through mode. If the object is in 77 write-through mode, all modifications to it will result in C{commit} 78 being called after the modification. 79 80 @return: C{True} if the object is in write-through mode, C{False} if 81 it's not. 82 """ 83 raise NotImplementedError
84 85
86 - def setWriteThrough(self, writeThrough):
87 """Sets the object's write-through mode to the specified status. When 88 switching the write-through mode on, the C{commit} operation 89 will be performed. 90 91 @param writeThrough: 92 Boolean value to indicate if the object should be in 93 write-through mode after the call. 94 @raise SourceException: 95 If the operation fails because of an exception is thrown by 96 the data source. 97 @raise InvalidValueException: 98 If the implicit commit operation fails because of a 99 validation error. 100 """ 101 raise NotImplementedError
102 103
104 - def isReadThrough(self):
105 """Tests if the object is in read-through mode. If the object is in 106 read-through mode, retrieving its value will result in the value being 107 first updated from the data source to the object. 108 109 The only exception to this rule is that when the object is not in 110 write-through mode and it's buffer contains a modified value, the value 111 retrieved from the object will be the locally modified value in the 112 buffer which may differ from the value in the data source. 113 114 @return: C{True} if the object is in read-through mode, 115 C{False} if it's not. 116 """ 117 raise NotImplementedError
118 119
120 - def setReadThrough(self, readThrough):
121 """Sets the object's read-through mode to the specified status. When 122 switching read-through mode on, the object's value is updated from the 123 data source. 124 125 @param readThrough: 126 Boolean value to indicate if the object should be in 127 read-through mode after the call. 128 129 @raise SourceException: 130 If the operation fails because of an exception is thrown by 131 the data source. The cause is included in the exception. 132 """ 133 raise NotImplementedError
134 135
136 - def isModified(self):
137 """Tests if the value stored in the object has been modified since it 138 was last updated from the data source. 139 140 @return: C{True} if the value in the object has been modified 141 since the last data source update, C{False} if not. 142 """ 143 raise NotImplementedError
144 145
146 -class SourceException(RuntimeError, IErrorMessage):
147 """An exception that signals that one or more exceptions occurred while a 148 buffered object tried to access its data source or if there is a problem 149 in processing a data source. 150 151 @author: Vaadin Ltd. 152 @author: Richard Lincoln 153 @version: 1.1.2 154 """ 155
156 - def __init__(self, source, cause=None):
157 """Creates a source exception from one or multiple causes. 158 159 @param source: 160 the source object implementing the IBuffered interface. 161 @param cause: 162 the original causes for this exception. 163 """ 164 # Source class implementing the buffered interface 165 self._source = source 166 167 # Original cause of the source exception 168 self._causes = list() 169 170 if isinstance(cause, list): 171 self._causes = cause 172 elif cause is not None: 173 self._causes = [cause]
174 175
176 - def getCause(self):
177 """Gets the cause of the exception. 178 179 @return: The cause for the exception. 180 @raise MoreThanOneCauseException: 181 if there is more than one cause for the exception. This 182 is possible if the commit operation triggers more than 183 one error at the same time. 184 """ 185 if len(self._causes) == 0: 186 return None 187 return self._causes[0]
188 189
190 - def getCauses(self):
191 """Gets all the causes for this exception. 192 193 @return: throwables that caused this exception 194 """ 195 return self._causes
196 197
198 - def getSource(self):
199 """Gets a source of the exception. 200 201 @return: the IBuffered object which generated this exception. 202 """ 203 return self._source
204 205
206 - def getErrorLevel(self):
207 """Gets the error level of this buffered source exception. The level of 208 the exception is maximum error level of all the contained causes. 209 210 The causes that do not specify error level default to C{ERROR} level. 211 Also source exception without any causes are of level C{ERROR}. 212 213 @see: com.vaadin.terminal.IErrorMessage#getErrorLevel() 214 """ 215 level = -sys.maxint - 1 216 217 for i in range(len(self._causes)): 218 if isinstance(self._causes[i], IErrorMessage): 219 causeLevel = self._causes[i].getErrorLevel() 220 else: 221 causeLevel = IErrorMessage.ERROR 222 223 if causeLevel > level: 224 level = causeLevel 225 226 return IErrorMessage.ERROR if level == -sys.maxint - 1 else level
227 228
229 - def paint(self, target):
230 target.startTag('error') 231 level = self.getErrorLevel() 232 233 if level > 0 and level <= IErrorMessage.INFORMATION: 234 target.addAttribute('level', 'info') 235 236 elif level <= IErrorMessage.WARNING: 237 target.addAttribute('level', 'warning') 238 239 elif level <= IErrorMessage.ERROR: 240 target.addAttribute('level', 'error') 241 242 elif level <= IErrorMessage.CRITICAL: 243 target.addAttribute('level', 'critical') 244 245 else: 246 target.addAttribute('level', 'system') 247 248 # Paint all the exceptions 249 for i in range(len(self._causes)): 250 if isinstance(self._causes[i], IErrorMessage): 251 self._causes[i].paint(target) 252 else: 253 SysError(self._causes[i]).paint(target) 254 255 target.endTag('error')
256 257
258 - def addListener(self, listener, iface=None):
259 raise NotImplementedError
260 261
262 - def addCallback(self, callback, eventType=None, *args):
263 raise NotImplementedError
264 265
266 - def removeListener(self, listener, iface=None):
267 raise NotImplementedError
268 269
270 - def removeCallback(self, callback, eventType=None):
271 raise NotImplementedError
272 273
274 - def requestRepaint(self):
275 raise NotImplementedError
276 277
278 - def requestRepaintRequests(self):
279 raise NotImplementedError
280 281
282 - def getDebugId(self):
283 return None
284 285
286 - def setDebugId(self, idd):
287 raise NotImplementedError, \ 288 'Setting testing id for this Paintable is not implemented'
289 290
291 -class IBufferedValidatable(IBuffered, IValidatable):
292 """This interface defines the combination of C{IValidatable} and 293 C{IBuffered} interfaces. The combination of the interfaces defines 294 if the invalid data is committed to datasource. 295 296 @author: Vaadin Ltd. 297 @author: Richard Lincoln 298 @version: 1.1.2 299 """ 300
301 - def isInvalidCommitted(self):
302 """Tests if the invalid data is committed to datasource. The default is 303 C{False}. 304 """ 305 raise NotImplementedError
306 307
308 - def setInvalidCommitted(self, isCommitted):
309 """Sets if the invalid data should be committed to datasource. The 310 default is C{False}. 311 """ 312 raise NotImplementedError
313