Innhold
1 API
ChangeLog er et abstrakt API for å registrere hendelser og endringer i Cerebrum. API-et har følgende funksjonalitet:
1.1 cl_init
Oppsett av ChangeLog-implementasjonen.
1.2 log_change
Legg endring i kø.
Implemetasjoner bør benytte denne API-funksjonen til å ta i mot en endring, og legge denne i kø for lagring eller levering.
1.3 write_log
Skriv endringer.
Implementasjoner bør benytte denne API-funksjonen til å lagre eller levere endringen til sine målsystem. write_log bør kalles før endringer leveres til databasen.
- Implementasjoner som benytter samme database som Cerebrum bør benytte funksjonen til å skrive endringene til databasen (se modules.ChangeLog).
- Implementasjoner som benytter transaksjoner for å levere endringer, bør benytte funksjonen til å skrive endringer til transaksjon.
- Implementasjoner som ikke benytter transaksjoner, eller ikke har mulighet til å avbryte levering/lagring av endring, bør ikke benytte funskjonen.
1.4 clear_log
Tøm kø for endringer.
Implementasjoner bør benytte denne funksjonen til å tømme køen av endringer som har blitt lagt til med log_change.
1.5 publish_log
Utfør endringer – endringer leveres eller lagres.
Implementasjoner bør benytte funksjonen for å forsikre seg om at meldinger blir levert.
- Implementasjoner som benytter samme database som Cerebrum bør ikke benytte seg av funksjonen, men heller benytte seg av CLDatabase for å sykronisere lagring av endringer.
- Implementasjoner som benytter transaksjoner for å levere endringer, bør benytte funksjonen til å avslutte transaksjon og skrive/levere endringer.
- Implementasjoner som ikke benytter transaksjoner, eller ikke har mulighet til å avbryte levering/lagring av endring, bør benytte funksjonen til å skrive/levere endringer.
1.6 unpublish_log
Avbryt levering av endringer.
Implementasjoner bør benytte funksjonen til å avbryte levering/lagring av endringer.
- Implementasjoner som benytter samme database som Cerebrum bør ikke benytte seg av funksjonen, men heller benytte seg av CLDatabase for å sykronisere lagring av endringer.
- Implementasjoner som benytter transaksjoner for å levere endringer, bør benytte funksjonen til å avbryte transaksjon.
- Implementasjoner som ikke benytter transaksjoner, eller ikke har mulighet til å avbryte levering/lagring av endring, bør benytte funksjonen til å tømme kø av endringer (f.eks. ved å kalle på clear_log).
2 Database
ChangeLog kan synkroniseres med database-commits ved å benytte CLDatabase som database-implementasjon.
Når dette gjøres, vil man ved commit til database automatisk gjøre, write_log, clear_log, publish_log og unpublish_log på riktige tidspunkt.
For å ta i bruk CLDatabase, må man sette opp:
cereconf.CLASS_DATABASE = ('Cerebrum.CLDatabase/CLDatabase', )
Oppførsel:
Ved rollback:
- ChangeLog.clear_log()
- Database.rollback()
Ved commit:
ChangeLog.write_log()
Database.commit()
- Hvis suksess: ChangeLog.publish_log()
- Hvis feil: ChangeLog.unpublish_log()
3 Implementasjon
3.1 modules.ChangeLog
ChangeLog-modulen i Cerebrum lagrer endringer i en egen database-tabell.
Hensikten med modulen er å:
- Lagre hvem som gjorde hvilke endringer.
- Oppdage/lytte etter endringer for å reagere raskt i andre systemer.
3.2 modules.EventLog
EventLog-modulen i Cerebrum lagrer endringer i en egen tabell for hendelser. Database-tabellen fungerer da som en enkel meldingskø, hvor PostgreSQL fungerer som Publish/Subscribe-system for videresending av meldinger.
Modulen er kun tilpasset installasjoner som benytter PostgreSQL som database-backend, fordi den benytter seg av database-spesifik funksjonalitet for å sende meldinger videre til system som abbonerer på disse.
EventLog ble skrevet for integrasjon mot Exchange. Mer informasjon om dette finnes i dokumentasjonen til Exchange-integrasjonen:
4 Kodestandard
- __init__
ChangeLog-implementasjoner bør ikke implementere __init__, da dette fort kan skape konflikt med database-implementasjonen sin __init__ (når CLDatabase benyttes).
Oppsett av objekt bør gjøres i cl_init.
- log_change
Log change har fire faste argumenter:
- subject_entity
- change_type
- destination_entity
- change_params
Alle tilleggs-argument må kommer etter disse, og kun bestå av key=value argumenter. I tillegg må log_change ta i mot et ubestemt antall key=value argumenter som sendes videre til andre implementasjoner:
def log_change(self, subject, change, dest, change_params=None, my_special_arg='my_default_value', **other_kw_args): super(MySpecialImplementation, self).log_change(subject, change, dest, change_params=change_params, **other_kw_args) # Do stuff- API-funksjoner
- Alle API-funksjoner bør ta key-value argument
- Unngå logging av endringer i en implementasjon
- Dersom du vil ha behov for å gjøre log_change uten at implementasjonen din benyttes, kan du legge til en skip_*-opsjon (standardverdi False) i implementasjonen av log_change. Når opsjonen er True, skal implementasjonen ikke gjøre noe annet med endringen enn å sende den videre til andre implementasjoner (super().log_change()).
- KUN logge endringer i en gitt implementasjon
Dersom man har behov for å kun sende en endring til en gitt implementasjon, bør man benytte seg av klassen direkte, eller lage en egen (ad-hoc) klasse for synkronisering med databasen:
db_cls = Factory.get('DBDriver') class MySpecialEventLog(EventLog, db_cls): def commit(self): self.write_log() super(MySpecialLogger, self).commit() event_log = MySpecialEventLog() event_log.log_change(*args) event_log.commit()