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 #------------------------------------------------------------
180 from Gnumed.pycommon import gmBusinessDBObject
181 from Gnumed.pycommon import gmPG2
182
183 #============================================================
184 # description
185 #------------------------------------------------------------
186 _SQL_get_XXX = u\"""
187 SELECT *, (xmin AS xmin_XXX)
188 FROM XXX.v_XXX
189 WHERE %s
190 \"""
191
192 class cXxxXxx(gmBusinessDBObject.cBusinessDBObject):
193
194 _cmd_fetch_payload = _SQL_get_XXX % u"pk_XXX = %s"
195 _cmds_store_payload = [
196 u\"""
197 UPDATE xxx.xxx SET -- typically the underlying table name
198 xxx = %(xxx)s, -- typically "table_col = %(view_col)s"
199 xxx = gm.nullify_empty_string(%(xxx)s)
200 WHERE
201 pk = %(xxx)s
202 AND
203 xmin = %(xmin_XXX)s
204 RETURNING
205 pk as pk_XXX,
206 xmin as xmin_XXX
207 \"""
208 ]
209 # view columns:
210 _updatable_fields = [
211 u'xxx',
212 u'xxx'
213 ]
214 #------------------------------------------------------------
215 def get_XXX(order_by=None):
216 if order_by is None:
217 order_by = u'true'
218 else:
219 order_by = u'true ORDER BY %s' % order_by
220
221 cmd = _SQL_get_XXX % order_by
222 rows, idx = gmPG2.run_ro_queries(queries = [{'cmd': cmd}], get_col_idx = True)
223 return [ cXxxXxx(row = {'data': r, 'idx': idx, 'pk_field': 'xxx'}) for r in rows ]
224 #------------------------------------------------------------
225 def create_xxx(xxx=None, xxx=None):
226
227 args = {
228 u'xxx': xxx,
229 u'xxx': xxx
230 }
231 cmd = u\"""
232 INSERT INTO xxx.xxx (
233 xxx,
234 xxx,
235 xxx
236 ) VALUES (
237 %(xxx)s,
238 %(xxx)s,
239 gm.nullify_empty_string(%(xxx)s)
240 )
241 RETURNING pk
242 \"""
243 rows, idx = gmPG2.run_rw_queries(queries = [{'cmd': cmd, 'args': args}], return_data = True, get_col_idx = False)
244
245 return cXxxXxx(aPK_obj = rows[0]['pk'])
246 #------------------------------------------------------------
247 def delete_xxx(xxx=None):
248 args = {'pk': xxx}
249 cmd = u"DELETE FROM xxx.xxx WHERE pk = %(pk)s"
250 gmPG2.run_rw_queries(queries = [{'cmd': cmd, 'args': args}])
251 return True
252 #------------------------------------------------------------
253
254
255 """
256
257 - def __init__(self, aPK_obj=None, row=None):
258 """Init business object.
259
260 Call from child classes:
261
262 super(cChildClass, self).__init__(aPK_obj = aPK_obj, row = row)
263 """
264
265
266
267 self.pk_obj = '<uninitialized>'
268 self._idx = {}
269 self._payload = []
270 self._ext_cache = {}
271 self._is_modified = False
272
273
274 self.__class__._cmd_fetch_payload
275 self.__class__._cmds_store_payload
276 self.__class__._updatable_fields
277
278 if aPK_obj is not None:
279 self.__init_from_pk(aPK_obj=aPK_obj)
280 else:
281 self._init_from_row_data(row=row)
282
283 self._is_modified = False
284
286 """Creates a new clinical item instance by its PK.
287
288 aPK_obj can be:
289 - a simple value
290 * the primary key WHERE condition must be
291 a simple column
292 - a dictionary of values
293 * the primary key where condition must be a
294 subselect consuming the dict and producing
295 the single-value primary key
296 """
297 self.pk_obj = aPK_obj
298 result = self.refetch_payload()
299 if result is True:
300 self.original_payload = {}
301 for field in self._idx.keys():
302 self.original_payload[field] = self._payload[self._idx[field]]
303 return True
304
305 if result is False:
306 raise gmExceptions.ConstructorError, "[%s:%s]: error loading instance" % (self.__class__.__name__, self.pk_obj)
307
309 """Creates a new clinical item instance given its fields.
310
311 row must be a dict with the fields:
312 - pk_field: the name of the primary key field
313 - idx: a dict mapping field names to position
314 - data: the field values in a list (as returned by
315 cursor.fetchone() in the DB-API)
316
317 row = {'data': row, 'idx': idx, 'pk_field': 'the PK column name'}
318
319 rows, idx = gmPG2.run_ro_queries(queries = [{'cmd': cmd, 'args': args}], get_col_idx = True)
320 objects = [ cChildClass(row = {'data': r, 'idx': idx, 'pk_field': 'the PK column name'}) for r in rows ]
321 """
322 try:
323 self._idx = row['idx']
324 self._payload = row['data']
325 self.pk_obj = self._payload[self._idx[row['pk_field']]]
326 except:
327 _log.exception('faulty <row> argument structure: %s' % row)
328 raise gmExceptions.ConstructorError, "[%s:??]: error loading instance from row data" % self.__class__.__name__
329
330 if len(self._idx.keys()) != len(self._payload):
331 _log.critical('field index vs. payload length mismatch: %s field names vs. %s fields' % (len(self._idx.keys()), len(self._payload)))
332 _log.critical('faulty <row> argument structure: %s' % row)
333 raise gmExceptions.ConstructorError, "[%s:??]: error loading instance from row data" % self.__class__.__name__
334
335 self.original_payload = {}
336 for field in self._idx.keys():
337 self.original_payload[field] = self._payload[self._idx[field]]
338
340 if self.__dict__.has_key('_is_modified'):
341 if self._is_modified:
342 _log.critical('[%s:%s]: loosing payload changes' % (self.__class__.__name__, self.pk_obj))
343 _log.debug('original: %s' % self.original_payload)
344 _log.debug('modified: %s' % self._payload)
345
347 tmp = []
348 try:
349 for attr in self._idx.keys():
350 if self._payload[self._idx[attr]] is None:
351 tmp.append(u'%s: NULL' % attr)
352 else:
353 tmp.append('%s: >>%s<<' % (attr, self._payload[self._idx[attr]]))
354 return '[%s:%s]: %s' % (self.__class__.__name__, self.pk_obj, str(tmp))
355 except:
356 return 'nascent [%s @ %s], cannot show payload and primary key' %(self.__class__.__name__, id(self))
357
359
360
361
362 try:
363 return self._payload[self._idx[attribute]]
364 except KeyError:
365 pass
366
367
368 getter = getattr(self, 'get_%s' % attribute, None)
369 if not callable(getter):
370 _log.warning('[%s]: no attribute [%s]' % (self.__class__.__name__, attribute))
371 _log.warning('[%s]: valid attributes: %s' % (self.__class__.__name__, str(self._idx.keys())))
372 _log.warning('[%s]: no getter method [get_%s]' % (self.__class__.__name__, attribute))
373 methods = filter(lambda x: x[0].startswith('get_'), inspect.getmembers(self, inspect.ismethod))
374 _log.warning('[%s]: valid getter methods: %s' % (self.__class__.__name__, str(methods)))
375 raise gmExceptions.NoSuchBusinessObjectAttributeError, '[%s]: cannot access [%s]' % (self.__class__.__name__, attribute)
376
377 self._ext_cache[attribute] = getter()
378 return self._ext_cache[attribute]
379
381
382
383 if attribute in self.__class__._updatable_fields:
384 try:
385 if self._payload[self._idx[attribute]] != value:
386 self._payload[self._idx[attribute]] = value
387 self._is_modified = True
388 return
389 except KeyError:
390 _log.warning('[%s]: cannot set attribute <%s> despite marked settable' % (self.__class__.__name__, attribute))
391 _log.warning('[%s]: supposedly settable attributes: %s' % (self.__class__.__name__, str(self.__class__._updatable_fields)))
392 raise gmExceptions.NoSuchBusinessObjectAttributeError, '[%s]: cannot access [%s]' % (self.__class__.__name__, attribute)
393
394
395 if hasattr(self, 'set_%s' % attribute):
396 setter = getattr(self, "set_%s" % attribute)
397 if not callable(setter):
398 raise gmExceptions.NoSuchBusinessObjectAttributeError, '[%s] setter [set_%s] not callable' % (self.__class__.__name__, attribute)
399 try:
400 del self._ext_cache[attribute]
401 except KeyError:
402 pass
403 if type(value) is types.TupleType:
404 if setter(*value):
405 self._is_modified = True
406 return
407 raise gmExceptions.BusinessObjectAttributeNotSettableError, '[%s]: setter [%s] failed for [%s]' % (self.__class__.__name__, setter, value)
408 if setter(value):
409 self._is_modified = True
410 return
411
412
413 _log.error('[%s]: cannot find attribute <%s> or setter method [set_%s]' % (self.__class__.__name__, attribute, attribute))
414 _log.warning('[%s]: settable attributes: %s' % (self.__class__.__name__, str(self.__class__._updatable_fields)))
415 methods = filter(lambda x: x[0].startswith('set_'), inspect.getmembers(self, inspect.ismethod))
416 _log.warning('[%s]: valid setter methods: %s' % (self.__class__.__name__, str(methods)))
417 raise gmExceptions.BusinessObjectAttributeNotSettableError, '[%s]: cannot set [%s]' % (self.__class__.__name__, attribute)
418
419
420
422 raise NotImplementedError('comparison between [%s] and [%s] not implemented' % (self, another_object))
423
425 return self._is_modified
426
428 try:
429 return self._idx.keys()
430 except AttributeError:
431 return 'nascent [%s @ %s], cannot return keys' %(self.__class__.__name__, id(self))
432
435
437 _log.error('[%s:%s]: forgot to override get_patient()' % (self.__class__.__name__, self.pk_obj))
438 return None
439
441 """Fetch field values from backend.
442 """
443 if self._is_modified:
444 if ignore_changes:
445 _log.critical('[%s:%s]: loosing payload changes' % (self.__class__.__name__, self.pk_obj))
446 _log.debug('original: %s' % self.original_payload)
447 _log.debug('modified: %s' % self._payload)
448 else:
449 _log.critical('[%s:%s]: cannot reload, payload changed' % (self.__class__.__name__, self.pk_obj))
450 return False
451
452 if type(self.pk_obj) == types.DictType:
453 arg = self.pk_obj
454 else:
455 arg = [self.pk_obj]
456 rows, self._idx = gmPG2.run_ro_queries (
457 queries = [{'cmd': self.__class__._cmd_fetch_payload, 'args': arg}],
458 get_col_idx = True
459 )
460 if len(rows) == 0:
461 _log.error('[%s:%s]: no such instance' % (self.__class__.__name__, self.pk_obj))
462 return False
463 self._payload = rows[0]
464 return True
465
468
469 - def save(self, conn=None):
471
473 """Store updated values (if any) in database.
474
475 Optionally accepts a pre-existing connection
476 - returns a tuple (<True|False>, <data>)
477 - True: success
478 - False: an error occurred
479 * data is (error, message)
480 * for error meanings see gmPG2.run_rw_queries()
481 """
482 if not self._is_modified:
483 return (True, None)
484
485 args = {}
486 for field in self._idx.keys():
487 args[field] = self._payload[self._idx[field]]
488 self.modified_payload = args
489
490 close_conn = self.__noop
491 if conn is None:
492 conn = gmPG2.get_connection(readonly=False)
493 close_conn = conn.close
494
495
496
497
498
499
500 queries = []
501 for query in self.__class__._cmds_store_payload:
502 queries.append({'cmd': query, 'args': args})
503 rows, idx = gmPG2.run_rw_queries (
504 link_obj = conn,
505 queries = queries,
506 return_data = True,
507 get_col_idx = True
508 )
509
510
511
512
513
514 if len(rows) == 0:
515 return (False, (u'cannot update row', _('[%s:%s]: row not updated (nothing returned), row in use ?') % (self.__class__.__name__, self.pk_obj)))
516
517
518 row = rows[0]
519 for key in idx:
520 try:
521 self._payload[self._idx[key]] = row[idx[key]]
522 except KeyError:
523 conn.rollback()
524 close_conn()
525 _log.error('[%s:%s]: cannot update instance, XMIN refetch key mismatch on [%s]' % (self.__class__.__name__, self.pk_obj, key))
526 _log.error('payload keys: %s' % str(self._idx))
527 _log.error('XMIN refetch keys: %s' % str(idx))
528 _log.error(args)
529 raise
530
531 conn.commit()
532 close_conn()
533
534 self._is_modified = False
535
536 self.original_payload = {}
537 for field in self._idx.keys():
538 self.original_payload[field] = self._payload[self._idx[field]]
539
540 return (True, None)
541
542
544
545 """ turn the data into a list of dicts, adding "class hints".
546 all objects get turned into dictionaries which the other end
547 will interpret as "object", via the __jsonclass__ hint,
548 as specified by the JSONRPC protocol standard.
549 """
550 if isinstance(obj, list):
551 return map(jsonclasshintify, obj)
552 elif isinstance(obj, gmPG2.dbapi.tz.FixedOffsetTimezone):
553
554
555 res = {'__jsonclass__': ["jsonobjproxy.FixedOffsetTimezone"]}
556 res['name'] = obj._name
557 res['offset'] = jsonclasshintify(obj._offset)
558 return res
559 elif isinstance(obj, datetime.timedelta):
560
561
562 res = {'__jsonclass__': ["jsonobjproxy.TimeDelta"]}
563 res['days'] = obj.days
564 res['seconds'] = obj.seconds
565 res['microseconds'] = obj.microseconds
566 return res
567 elif isinstance(obj, datetime.time):
568
569
570 res = {'__jsonclass__': ["jsonobjproxy.Time"]}
571 res['hour'] = obj.hour
572 res['minute'] = obj.minute
573 res['second'] = obj.second
574 res['microsecond'] = obj.microsecond
575 res['tzinfo'] = jsonclasshintify(obj.tzinfo)
576 return res
577 elif isinstance(obj, datetime.datetime):
578
579
580 res = {'__jsonclass__': ["jsonobjproxy.DateTime"]}
581 res['year'] = obj.year
582 res['month'] = obj.month
583 res['day'] = obj.day
584 res['hour'] = obj.hour
585 res['minute'] = obj.minute
586 res['second'] = obj.second
587 res['microsecond'] = obj.microsecond
588 res['tzinfo'] = jsonclasshintify(obj.tzinfo)
589 return res
590 elif isinstance(obj, cBusinessDBObject):
591
592
593 res = {'__jsonclass__': ["jsonobjproxy.%s" % obj.__class__.__name__]}
594 for k in obj.get_fields():
595 t = jsonclasshintify(obj[k])
596 res[k] = t
597 print "props", res, dir(obj)
598 for attribute in dir(obj):
599 if not attribute.startswith("get_"):
600 continue
601 k = attribute[4:]
602 if res.has_key(k):
603 continue
604 getter = getattr(obj, attribute, None)
605 if callable(getter):
606 res[k] = jsonclasshintify(getter())
607 return res
608 return obj
609
610
611 if __name__ == '__main__':
612
613 if len(sys.argv) < 2:
614 sys.exit()
615
616 if sys.argv[1] != u'test':
617 sys.exit()
618
619
630
631 from Gnumed.pycommon import gmI18N
632 gmI18N.activate_locale()
633 gmI18N.install_domain()
634
635 data = {
636 'pk_field': 'bogus_pk',
637 'idx': {'bogus_pk': 0, 'bogus_field': 1},
638 'data': [-1, 'bogus_data']
639 }
640 obj = cTestObj(row=data)
641
642
643 obj['wrong_field'] = 1
644
645
646