1 """GNUmed database object business class.
2
3 Overview
4 --------
5 This class wraps a source relation (table, view) which
6 represents an entity that makes immediate business sense
7 such as a vaccination or a medical document. In many if
8 not most cases this source relation is a denormalizing
9 view. The data in that view will in most cases, however,
10 originate from several normalized tables. One instance
11 of this class represents one row of said source relation.
12
13 Note, however, that this class does not *always* simply
14 wrap a single table or view. It can also encompass several
15 relations (views, tables, sequences etc) that taken together
16 form an object meaningful to *business* logic.
17
18 Initialization
19 --------------
20 There are two ways to initialize an instance with values.
21 One way is to pass a "primary key equivalent" object into
22 __init__(). Refetch_payload() will then pull the data from
23 the backend. Another way would be to fetch the data outside
24 the instance and pass it in via the <row> argument. In that
25 case the instance will not initially connect to the databse
26 which may offer a great boost to performance.
27
28 Values API
29 ----------
30 Field values are cached for later access. They can be accessed
31 by a dictionary API, eg:
32
33 old_value = object['field']
34 object['field'] = new_value
35
36 The field names correspond to the respective column names
37 in the "main" source relation. Accessing non-existant field
38 names will raise an error, so does trying to set fields not
39 listed in self.__class__._updatable_fields. To actually
40 store updated values in the database one must explicitly
41 call save_payload().
42
43 The class will in many cases be enhanced by accessors to
44 related data that is not directly part of the business
45 object itself but are closely related, such as codes
46 linked to a clinical narrative entry (eg a diagnosis). Such
47 accessors in most cases start with get_*. Related setters
48 start with set_*. The values can be accessed via the
49 object['field'] syntax, too, but they will be cached
50 independantly.
51
52 Concurrency handling
53 --------------------
54 GNUmed connections always run transactions in isolation level
55 "serializable". This prevents transactions happening at the
56 *very same time* to overwrite each other's data. All but one
57 of them will abort with a concurrency error (eg if a
58 transaction runs a select-for-update later than another one
59 it will hang until the first transaction ends. Then it will
60 succeed or fail depending on what the first transaction
61 did). This is standard transactional behaviour.
62
63 However, another transaction may have updated our row
64 between the time we first fetched the data and the time we
65 start the update transaction. This is noticed by getting the
66 XMIN system column for the row when initially fetching the
67 data and using that value as a where condition value when
68 updating the row later. If the row had been updated (xmin
69 changed) or deleted (primary key disappeared) in the
70 meantime the update will touch zero rows (as no row with
71 both PK and XMIN matching is found) even if the query itself
72 syntactically succeeds.
73
74 When detecting a change in a row due to XMIN being different
75 one needs to be careful how to represent that to the user.
76 The row may simply have changed but it also might have been
77 deleted and a completely new and unrelated row which happens
78 to have the same primary key might have been created ! This
79 row might relate to a totally different context (eg. patient,
80 episode, encounter).
81
82 One can offer all the data to the user:
83
84 self.original_payload
85 - contains the data at the last successful refetch
86
87 self.modified_payload
88 - contains the modified payload just before the last
89 failure of save_payload() - IOW what is currently
90 in the database
91
92 self._payload
93 - contains the currently active payload which may or
94 may not contain changes
95
96 For discussion on this see the thread starting at:
97
98 http://archives.postgresql.org/pgsql-general/2004-10/msg01352.php
99
100 and here
101
102 http://groups.google.com/group/pgsql.general/browse_thread/thread/e3566ba76173d0bf/6cf3c243a86d9233
103 (google for "XMIN semantic at peril")
104
105 Problem cases with XMIN:
106
107 1) not unlikely
108 - a very old row is read with XMIN
109 - vacuum comes along and sets XMIN to FrozenTransactionId
110 - now XMIN changed but the row actually didn't !
111 - an update with "... where xmin = old_xmin ..." fails
112 although there is no need to fail
113
114 2) quite unlikely
115 - a row is read with XMIN
116 - a long time passes
117 - the original XMIN gets frozen to FrozenTransactionId
118 - another writer comes along and changes the row
119 - incidentally the exact same old row gets the old XMIN *again*
120 - now XMIN is (again) the same but the data changed !
121 - a later update fails to detect the concurrent change !!
122
123 TODO:
124 The solution is to use our own column for optimistic locking
125 which gets updated by an AFTER UPDATE trigger.
126 """
127
128 __version__ = "$Revision: 1.60 $"
129 __author__ = "K.Hilbert <Karsten.Hilbert@gmx.net>"
130 __license__ = "GPL"
131
132 import sys, copy, types, inspect, logging, datetime
133
134
135 if __name__ == '__main__':
136 sys.path.insert(0, '../../')
137 from Gnumed.pycommon import gmExceptions, gmPG2
138
139
140 _log = logging.getLogger('gm.db')
141 _log.info(__version__)
142
144 """Represents business objects in the database.
145
146 Rules:
147 - instances ARE ASSUMED TO EXIST in the database
148 - PK construction (aPK_obj): DOES verify its existence on instantiation
149 (fetching data fails)
150 - Row construction (row): allowed by using a dict of pairs
151 field name: field value (PERFORMANCE improvement)
152 - does NOT verify FK target existence
153 - does NOT create new entries in the database
154 - does NOT lazy-fetch fields on access
155
156 Class scope SQL commands and variables:
157
158 <_cmd_fetch_payload>
159 - must return exactly one row
160 - where clause argument values are expected
161 in self.pk_obj (taken from __init__(aPK_obj))
162 - must return xmin of all rows that _cmds_store_payload
163 will be updating, so views must support the xmin columns
164 of their underlying tables
165
166 <_cmds_store_payload>
167 - one or multiple "update ... set ... where xmin_* = ..." statements
168 which actually update the database from the data in self._payload,
169 - the last query must refetch the XMIN values needed to detect
170 concurrent updates, their field names had better be the same as
171 in _cmd_fetch_payload
172
173 <_updatable_fields>
174 - a list of fields available for update via object['field']
175
176
177 A template for new child classes:
178
179 *********** start of template ***********
180
181 #------------------------------------------------------------
182 from Gnumed.pycommon import gmBusinessDBObject
183 from Gnumed.pycommon import gmPG2
184
185 #============================================================
186 # short description
187 #------------------------------------------------------------
188 # use plural form, search-replace get_XXX
189 _SQL_get_XXX = u\"""
190 SELECT *, (xmin AS xmin_XXX)
191 FROM XXX.v_XXX
192 WHERE %s
193 \"""
194
195 class cXxxXxx(gmBusinessDBObject.cBusinessDBObject):
196 \"""Represents ...\"""
197
198 _cmd_fetch_payload = _SQL_get_XXX % u"pk_XXX = %s"
199 _cmds_store_payload = [
200 u\"""
201 UPDATE xxx.xxx SET -- typically the underlying table name
202 xxx = %(xxx)s, -- typically "table_col = %(view_col)s"
203 xxx = gm.nullify_empty_string(%(xxx)s)
204 WHERE
205 pk = %(pk_XXX)s
206 AND
207 xmin = %(xmin_XXX)s
208 RETURNING
209 pk as pk_XXX,
210 xmin as xmin_XXX
211 \"""
212 ]
213 # view columns that can be updated:
214 _updatable_fields = [
215 u'xxx',
216 u'xxx'
217 ]
218 #------------------------------------------------------------
219 def get_XXX(order_by=None):
220 if order_by is None:
221 order_by = u'true'
222 else:
223 order_by = u'true ORDER BY %s' % order_by
224
225 cmd = _SQL_get_XXX % order_by
226 rows, idx = gmPG2.run_ro_queries(queries = [{'cmd': cmd}], get_col_idx = True)
227 return [ cXxxXxx(row = {'data': r, 'idx': idx, 'pk_field': 'xxx'}) for r in rows ]
228 #------------------------------------------------------------
229 def create_xxx(xxx=None, xxx=None):
230
231 args = {
232 u'xxx': xxx,
233 u'xxx': xxx
234 }
235 cmd = u\"""
236 INSERT INTO xxx.xxx (
237 xxx,
238 xxx,
239 xxx
240 ) VALUES (
241 %(xxx)s,
242 %(xxx)s,
243 gm.nullify_empty_string(%(xxx)s)
244 )
245 RETURNING pk
246 \"""
247 rows, idx = gmPG2.run_rw_queries(queries = [{'cmd': cmd, 'args': args}], return_data = True, get_col_idx = False)
248
249 return cXxxXxx(aPK_obj = rows[0]['pk'])
250 #------------------------------------------------------------
251 def delete_xxx(xxx=None):
252 args = {'pk': xxx}
253 cmd = u"DELETE FROM xxx.xxx WHERE pk = %(pk)s"
254 gmPG2.run_rw_queries(queries = [{'cmd': cmd, 'args': args}])
255 return True
256 #------------------------------------------------------------
257
258 *********** end of template ***********
259
260 """
261
262 - def __init__(self, aPK_obj=None, row=None):
263 """Init business object.
264
265 Call from child classes:
266
267 super(cChildClass, self).__init__(aPK_obj = aPK_obj, row = row)
268 """
269
270
271
272 self.pk_obj = '<uninitialized>'
273 self._idx = {}
274 self._payload = []
275 self._ext_cache = {}
276 self._is_modified = False
277
278
279 self.__class__._cmd_fetch_payload
280 self.__class__._cmds_store_payload
281 self.__class__._updatable_fields
282
283 if aPK_obj is not None:
284 self.__init_from_pk(aPK_obj=aPK_obj)
285 else:
286 self._init_from_row_data(row=row)
287
288 self._is_modified = False
289
291 """Creates a new clinical item instance by its PK.
292
293 aPK_obj can be:
294 - a simple value
295 * the primary key WHERE condition must be
296 a simple column
297 - a dictionary of values
298 * the primary key where condition must be a
299 subselect consuming the dict and producing
300 the single-value primary key
301 """
302 self.pk_obj = aPK_obj
303 result = self.refetch_payload()
304 if result is True:
305 self.original_payload = {}
306 for field in self._idx.keys():
307 self.original_payload[field] = self._payload[self._idx[field]]
308 return True
309
310 if result is False:
311 raise gmExceptions.ConstructorError, "[%s:%s]: error loading instance" % (self.__class__.__name__, self.pk_obj)
312
314 """Creates a new clinical item instance given its fields.
315
316 row must be a dict with the fields:
317 - pk_field: the name of the primary key field
318 - idx: a dict mapping field names to position
319 - data: the field values in a list (as returned by
320 cursor.fetchone() in the DB-API)
321
322 row = {'data': row, 'idx': idx, 'pk_field': 'the PK column name'}
323
324 rows, idx = gmPG2.run_ro_queries(queries = [{'cmd': cmd, 'args': args}], get_col_idx = True)
325 objects = [ cChildClass(row = {'data': r, 'idx': idx, 'pk_field': 'the PK column name'}) for r in rows ]
326 """
327 try:
328 self._idx = row['idx']
329 self._payload = row['data']
330 self.pk_obj = self._payload[self._idx[row['pk_field']]]
331 except:
332 _log.exception('faulty <row> argument structure: %s' % row)
333 raise gmExceptions.ConstructorError, "[%s:??]: error loading instance from row data" % self.__class__.__name__
334
335 if len(self._idx.keys()) != len(self._payload):
336 _log.critical('field index vs. payload length mismatch: %s field names vs. %s fields' % (len(self._idx.keys()), len(self._payload)))
337 _log.critical('faulty <row> argument structure: %s' % row)
338 raise gmExceptions.ConstructorError, "[%s:??]: error loading instance from row data" % self.__class__.__name__
339
340 self.original_payload = {}
341 for field in self._idx.keys():
342 self.original_payload[field] = self._payload[self._idx[field]]
343
345 if self.__dict__.has_key('_is_modified'):
346 if self._is_modified:
347 _log.critical('[%s:%s]: loosing payload changes' % (self.__class__.__name__, self.pk_obj))
348 _log.debug('original: %s' % self.original_payload)
349 _log.debug('modified: %s' % self._payload)
350
352 tmp = []
353 try:
354 for attr in self._idx.keys():
355 if self._payload[self._idx[attr]] is None:
356 tmp.append(u'%s: NULL' % attr)
357 else:
358 tmp.append('%s: >>%s<<' % (attr, self._payload[self._idx[attr]]))
359 return '[%s:%s]: %s' % (self.__class__.__name__, self.pk_obj, str(tmp))
360 except:
361 return 'nascent [%s @ %s], cannot show payload and primary key' %(self.__class__.__name__, id(self))
362
364
365
366
367 try:
368 return self._payload[self._idx[attribute]]
369 except KeyError:
370 pass
371
372
373 getter = getattr(self, 'get_%s' % attribute, None)
374 if not callable(getter):
375 _log.warning('[%s]: no attribute [%s]' % (self.__class__.__name__, attribute))
376 _log.warning('[%s]: valid attributes: %s' % (self.__class__.__name__, str(self._idx.keys())))
377 _log.warning('[%s]: no getter method [get_%s]' % (self.__class__.__name__, attribute))
378 methods = filter(lambda x: x[0].startswith('get_'), inspect.getmembers(self, inspect.ismethod))
379 _log.warning('[%s]: valid getter methods: %s' % (self.__class__.__name__, str(methods)))
380 raise gmExceptions.NoSuchBusinessObjectAttributeError, '[%s]: cannot access [%s]' % (self.__class__.__name__, attribute)
381
382 self._ext_cache[attribute] = getter()
383 return self._ext_cache[attribute]
384
386
387
388 if attribute in self.__class__._updatable_fields:
389 try:
390 if self._payload[self._idx[attribute]] != value:
391 self._payload[self._idx[attribute]] = value
392 self._is_modified = True
393 return
394 except KeyError:
395 _log.warning('[%s]: cannot set attribute <%s> despite marked settable' % (self.__class__.__name__, attribute))
396 _log.warning('[%s]: supposedly settable attributes: %s' % (self.__class__.__name__, str(self.__class__._updatable_fields)))
397 raise gmExceptions.NoSuchBusinessObjectAttributeError, '[%s]: cannot access [%s]' % (self.__class__.__name__, attribute)
398
399
400 if hasattr(self, 'set_%s' % attribute):
401 setter = getattr(self, "set_%s" % attribute)
402 if not callable(setter):
403 raise gmExceptions.NoSuchBusinessObjectAttributeError, '[%s] setter [set_%s] not callable' % (self.__class__.__name__, attribute)
404 try:
405 del self._ext_cache[attribute]
406 except KeyError:
407 pass
408 if type(value) is types.TupleType:
409 if setter(*value):
410 self._is_modified = True
411 return
412 raise gmExceptions.BusinessObjectAttributeNotSettableError, '[%s]: setter [%s] failed for [%s]' % (self.__class__.__name__, setter, value)
413 if setter(value):
414 self._is_modified = True
415 return
416
417
418 _log.error('[%s]: cannot find attribute <%s> or setter method [set_%s]' % (self.__class__.__name__, attribute, attribute))
419 _log.warning('[%s]: settable attributes: %s' % (self.__class__.__name__, str(self.__class__._updatable_fields)))
420 methods = filter(lambda x: x[0].startswith('set_'), inspect.getmembers(self, inspect.ismethod))
421 _log.warning('[%s]: valid setter methods: %s' % (self.__class__.__name__, str(methods)))
422 raise gmExceptions.BusinessObjectAttributeNotSettableError, '[%s]: cannot set [%s]' % (self.__class__.__name__, attribute)
423
424
425
427 raise NotImplementedError('comparison between [%s] and [%s] not implemented' % (self, another_object))
428
430 return self._is_modified
431
433 try:
434 return self._idx.keys()
435 except AttributeError:
436 return 'nascent [%s @ %s], cannot return keys' %(self.__class__.__name__, id(self))
437
440
442 _log.error('[%s:%s]: forgot to override get_patient()' % (self.__class__.__name__, self.pk_obj))
443 return None
444
446 """Fetch field values from backend.
447 """
448 if self._is_modified:
449 if ignore_changes:
450 _log.critical('[%s:%s]: loosing payload changes' % (self.__class__.__name__, self.pk_obj))
451 _log.debug('original: %s' % self.original_payload)
452 _log.debug('modified: %s' % self._payload)
453 else:
454 _log.critical('[%s:%s]: cannot reload, payload changed' % (self.__class__.__name__, self.pk_obj))
455 return False
456
457 if type(self.pk_obj) == types.DictType:
458 arg = self.pk_obj
459 else:
460 arg = [self.pk_obj]
461 rows, self._idx = gmPG2.run_ro_queries (
462 queries = [{'cmd': self.__class__._cmd_fetch_payload, 'args': arg}],
463 get_col_idx = True
464 )
465 if len(rows) == 0:
466 _log.error('[%s:%s]: no such instance' % (self.__class__.__name__, self.pk_obj))
467 return False
468 self._payload = rows[0]
469 return True
470
473
474 - def save(self, conn=None):
476
478 """Store updated values (if any) in database.
479
480 Optionally accepts a pre-existing connection
481 - returns a tuple (<True|False>, <data>)
482 - True: success
483 - False: an error occurred
484 * data is (error, message)
485 * for error meanings see gmPG2.run_rw_queries()
486 """
487 if not self._is_modified:
488 return (True, None)
489
490 args = {}
491 for field in self._idx.keys():
492 args[field] = self._payload[self._idx[field]]
493 self.modified_payload = args
494
495 close_conn = self.__noop
496 if conn is None:
497 conn = gmPG2.get_connection(readonly=False)
498 close_conn = conn.close
499
500
501
502
503
504
505 queries = []
506 for query in self.__class__._cmds_store_payload:
507 queries.append({'cmd': query, 'args': args})
508 rows, idx = gmPG2.run_rw_queries (
509 link_obj = conn,
510 queries = queries,
511 return_data = True,
512 get_col_idx = True
513 )
514
515
516
517
518
519 if len(rows) == 0:
520 return (False, (u'cannot update row', _('[%s:%s]: row not updated (nothing returned), row in use ?') % (self.__class__.__name__, self.pk_obj)))
521
522
523 row = rows[0]
524 for key in idx:
525 try:
526 self._payload[self._idx[key]] = row[idx[key]]
527 except KeyError:
528 conn.rollback()
529 close_conn()
530 _log.error('[%s:%s]: cannot update instance, XMIN refetch key mismatch on [%s]' % (self.__class__.__name__, self.pk_obj, key))
531 _log.error('payload keys: %s' % str(self._idx))
532 _log.error('XMIN refetch keys: %s' % str(idx))
533 _log.error(args)
534 raise
535
536 conn.commit()
537 close_conn()
538
539 self._is_modified = False
540
541 self.original_payload = {}
542 for field in self._idx.keys():
543 self.original_payload[field] = self._payload[self._idx[field]]
544
545 return (True, None)
546
547
549
550 """ turn the data into a list of dicts, adding "class hints".
551 all objects get turned into dictionaries which the other end
552 will interpret as "object", via the __jsonclass__ hint,
553 as specified by the JSONRPC protocol standard.
554 """
555 if isinstance(obj, list):
556 return map(jsonclasshintify, obj)
557 elif isinstance(obj, gmPG2.dbapi.tz.FixedOffsetTimezone):
558
559
560 res = {'__jsonclass__': ["jsonobjproxy.FixedOffsetTimezone"]}
561 res['name'] = obj._name
562 res['offset'] = jsonclasshintify(obj._offset)
563 return res
564 elif isinstance(obj, datetime.timedelta):
565
566
567 res = {'__jsonclass__': ["jsonobjproxy.TimeDelta"]}
568 res['days'] = obj.days
569 res['seconds'] = obj.seconds
570 res['microseconds'] = obj.microseconds
571 return res
572 elif isinstance(obj, datetime.time):
573
574
575 res = {'__jsonclass__': ["jsonobjproxy.Time"]}
576 res['hour'] = obj.hour
577 res['minute'] = obj.minute
578 res['second'] = obj.second
579 res['microsecond'] = obj.microsecond
580 res['tzinfo'] = jsonclasshintify(obj.tzinfo)
581 return res
582 elif isinstance(obj, datetime.datetime):
583
584
585 res = {'__jsonclass__': ["jsonobjproxy.DateTime"]}
586 res['year'] = obj.year
587 res['month'] = obj.month
588 res['day'] = obj.day
589 res['hour'] = obj.hour
590 res['minute'] = obj.minute
591 res['second'] = obj.second
592 res['microsecond'] = obj.microsecond
593 res['tzinfo'] = jsonclasshintify(obj.tzinfo)
594 return res
595 elif isinstance(obj, cBusinessDBObject):
596
597
598 res = {'__jsonclass__': ["jsonobjproxy.%s" % obj.__class__.__name__]}
599 for k in obj.get_fields():
600 t = jsonclasshintify(obj[k])
601 res[k] = t
602 print "props", res, dir(obj)
603 for attribute in dir(obj):
604 if not attribute.startswith("get_"):
605 continue
606 k = attribute[4:]
607 if res.has_key(k):
608 continue
609 getter = getattr(obj, attribute, None)
610 if callable(getter):
611 res[k] = jsonclasshintify(getter())
612 return res
613 return obj
614
615
616 if __name__ == '__main__':
617
618 if len(sys.argv) < 2:
619 sys.exit()
620
621 if sys.argv[1] != u'test':
622 sys.exit()
623
624
635
636 from Gnumed.pycommon import gmI18N
637 gmI18N.activate_locale()
638 gmI18N.install_domain()
639
640 data = {
641 'pk_field': 'bogus_pk',
642 'idx': {'bogus_pk': 0, 'bogus_field': 1},
643 'data': [-1, 'bogus_data']
644 }
645 obj = cTestObj(row=data)
646
647
648 obj['wrong_field'] = 1
649
650
651