O2 ODMG Database System Tutorial

O2 ODMG Database System Tutorial Release 5.0 - April 1998

In for m at ion in t h is docu m en t is su bject t o ch an ge wit h ou t n ot ice an d sh ou ld n ot be con st r u ed as a com m it m en t by O2 Tech n ology. Th e soft war e descr ibed in t h is docu m en t is deliver ed u n der a licen se or n on disclosu r e agr eem en t . Th e soft war e can on ly be u sed or copied in accor dan ce wit h t h e t er m s of t h e agr eem en t . It is again st th e law t o copy t h is softwar e t o m agn et ic t ape, disk , or an y oth er m ediu m for an y pu r pose ot h er t h an t h e pu r ch aser ’s own u se. Copyr igh t 1992-1998 O 2 Tech n ology. All r igh ts r eser ved. No par t of t h is pu blicat ion can be r epr odu ced, st or ed in a r et r ieval syst em or t r an sm it ted in an y for m or by an y m ean s, elect r on ic, m ech an ical, ph ot ocopy wit h ou t pr ior wr it t en per m ission of O2 Tech n ology. O 2 , O2 En gin e API, O2 C, O 2 DBAccess, O 2 En gin e, O2 Gr aph , O 2 Kit , O2 Look , O2 St or e, O 2 Tools, an d O 2 Web ar e r egist er ed t r adem ar k s of O2 Tech n ology. SQL an d AIX ar e r egist er ed tr adem ar k s of In t er n at ion al Bu sin ess Mach in es Cor por at ion . Su n , Su n OS, an d SOLARIS ar e r egist er ed t r adem ar k s of Su n M icr osyst em s, In c. X Win dow Syst em is a r egister ed t r adem ar k of t h e Massach u set ts In stit u t e of Tech n ology. Un ix is a r egist er ed tr adem ar k of Un ix Syst em Labor at or ies, In c. H PUX is a r egist er ed t r adem ar k of Hewlet t -Pack ar d Com pan y. BOSX is a r egist er ed t r adem ar k of Bu ll S.A. IRIX is a r egist er ed t r adem ar k of Siem en s Nixdor f, A.G. NeXTSt ep is a r egist er ed t r adem ar k of t h e NeXT Com pu ter , In c. Pu r ify, Qu an t ify ar e r egist er ed t r adem ar k s of Pu r e Soft war e In c. Win dows is a r egist er ed t r adem ar k of M icr osoft Cor por at ion . All ot h er com pan y or pr odu ct n am es qu ot ed ar e t r adem ar k s or r egister ed t r adem ar k s of t h eir r espect ive t r adem ar k h older s. In for m at ion in t h is docu m en t is su bject t o ch an ge wit h ou t n ot ice an d sh ou ld n ot be con st r u ed as a com m it m en t by O2 Tech n ology. Th e soft war e descr ibed in t h is docu m en t is deliver ed u n der a licen se or n on disclosu r e agr eem en t.

Who should use this tutorial Th is t u t or ial is for pr ogr am m er s wh o wish t o wr ite or adapt C++ applicat ion s t o r u n wit h O2 . It pr esen t s an exam ple applicat ion an d descr ibes t h e st eps r equ ir ed t o por t t h is applicat ion t o O2 . A pr ior k n owledge of C++ is assu m ed. It also pr esen t s t h e object qu er y lan gu age (OQL) wh ich can be u sed for st an d-alon e qu er ies or em bed qu er ies in a C++ pr ogr am . Th e followin g m an u als give fu r t h er det ails on t h e topics cover ed in t h is t u t or ial: ODMG C++ Binding Guide ODMG C++ Binding Reference Manual OQL User Manual O2 System Administration Guide O2 System Administration Reference Manual

Oth er docu m en t s available ar e ou t lin ed, click below.

See O2 Documentation set.

TABLE OF CON TENTS

Th is t u t or ial con t ain s t h e followin g sect ion s: 1 - In t r odu ction 2 - Por t in g a C++ applicat ion 3 - OQL

O2 ODMG Dat abase System Tu t or ial

5

TABLE OF CONTENTS

1

Introduction

9

1.1 Introduction to O2 ....................................................................10 Architecture..................................................................................10 1.2 Object Database Management Group (ODMG)...................... 11 The O2 ODMG C++ Binding ......................................................12 1.3 Benefits of porting to O2 .........................................................13 1.4 Example application.................................................................15 Relevant files................................................................................17 1.5 Setup .........................................................................................19 2

Porting a C++ Application

23

2.1 Store C++ objects in an O2 database .....................................26 2.2 Change C++ pointers to persistent pointers .........................28 2.3 Include files...............................................................................32 2.4 Connect to the database..........................................................33 2.5 Run a transaction .....................................................................34 2.6 Create names............................................................................35 2.7 Modify source code..................................................................36 2.8 Create persistent objects ........................................................38 2.9 Build and Run the Application ................................................41 2.10 Replace arrays by collection classes.....................................42 2.11 Build and Run the Application ................................................49 3

OQL

51

3.1 The O2 ODMG Object Query Language .................................52 Interactive ad hoc queries ............................................................52 Accessing data..............................................................................53

6

O2 ODM G D at abase Syst em Tu t or ial

TABLE OF CONTENTS

Selecting data............................................................................... 53 Manipulating complex values...................................................... 54 Manipulating polymorphic collections........................................ 54 Composing operators................................................................... 55 3.2 Embedding OQL in C++ .......................................................... 56 3.3 Build and Run the Application ............................................... 58

O2 ODMG Database Syst em Tu t or ial

7

TABLE OF CONTENTS

8

O2 ODM G D at abase Syst em Tu t or ial

11

I ntr oduction

In t r odu ct ion t o t h e ben efit s of O2 .

Th is ch apt er br iefly in tr odu ces t h e O2 system an d t h e ben efit s of por t in g a C++ applicat ion to O2. It con t ain s t h e followin g section s: • Introduction to O2 • Object D at abase M an agem en t Gr ou p (OD MG) • Benefits of porting to O2 • Exam ple applicat ion • Set u p

O2 OD MG Dat abase Syst em Tu tor ial

9

1

Introduction

1.1 Introduction to O2 Th e O 2 ODM G dat abase syst em is a fu lly OD MG com plian t syst em , offer in g a power fu l dat abase en gin e, a C++ pr ogr am m in g in t er face an d an OQL qu er y in t er face. Th e O2 ODMG dat abase syst em offer s a dat a m odel fu lly com patible wit h t h e C++ t ype syst em . It pr ovides t r an spar en t m u lt i-u ser access t o a dat abase an d in clu des a com plet e em bedded qu er y lan gu age for associat ive access t o dat a. Th e O 2 system h as been design ed to su ppor t lar ge dat abases wit h a lar ge n u m ber of u ser s. O 2 is a t otally open syst em t h at in t egr at es easily wit h ot h er soft war e. Th e open ar ch it ect u r e of O2 pr ovides con n ect ion s t o r elat ion al dat abase en gin es, GUI t ools, t h e Wor ld Wide Web, pr ogr am m in g lan gu ages an d CASE an d m et h odology tools. O 2 is lan gu age an d com piler in depen den t . To pr ovide m axim u m flexibilit y you can access t h e sam e dat abase wit h an y of t h e su ppor ted pr ogr am m in g lan gu ages su ch as C, C++, J ava, Eiffel, Lisp, Objective C an d O2 C wh ich is a fou r t h gen er at ion object lan gu age. O 2 applicat ion s can be developed u sin g th e stan dar d pr ogr am m in g en vir on m en t s available or u sin g O2 Tools. With O 2 , you can u se st an dar d object -or ien t ed m et h odologies an d associat ed tools (Tr am is, LOV, Object eer in g, ROSE, et c.).

Architecture Th e O 2 Syst em su ppor ts a clien t ser ver ar ch itect u r e. Th e clien t an d ser ver ar e separ at e pr ocesses wh ich com m u n icat e over a n et wor k . Th er e is u su ally a sin gle ser ver pr ocess wh ich com m u n icat es wit h m u lt iple clien t s. Th e ser ver (o2server) is r espon sible for r eadin g an d wr it in g dat a t o per m an en t st or age, m an agin g con cu r r en t access to t h e dat a fr om m u lt iple clien ts, back in g u p t h e database an d r ecover in g t h e dat abase aft er a cr ash . Th e clien t pr ocess is a u ser application pr ogr am . For t h e pu r poses of t h is tu t or ial t h e clien t is an exam ple C++ applicat ion . In t h e C++ sam ple applicat ion t h e com m u n ication wit h t h e ser ver is t r an spar en t t o t h e C++ developer . Th e C++ applicat ion au t om atically com m u n icat es wit h t h e o2server t h r ou gh t h e O2 C++ r u n tim e libr ar y.

10

O 2 ODM G D at abase Syst em Tu t or ial

Object Database Management Group (ODMG)

1.2 Object Database Management Group (ODMG) Th e Object Dat abase Man agem en t Gr ou p (ODMG) is m ade u p of th e leadin g Object D at abase ven dor s plu s a lar ge n u m ber of com pan ies t h at ar e in t er est ed in an ODBM S st an dar d. Th e ODM G h as pr odu ced a st an dar d for object dat abases. Th e OD MG St an dar d is an in t er oper abilit y st an dar d wh ich allows applicat ion s wr it ten t o t h e st an dar d t o r u n on an y com plian t syst em . Th is st an dar d con t ain s five cat egor ies: - Object M odel - Object D efin it ion Lan gu age (ODL) - Object Qu er y Lan gu age (OQL) - C++ Lan gu age Bin din g - J ava Lan gu age Bin din g Th e ODM G Object m odel is an ext en sion of t h e OM G object m odel. Th e object m odel su ppor t s t h e n ot ion s of class, objects wit h at t r ibu t es an d m et h ods, in h er it an ce, an d specialization . Th e exten sion s to t h e OMG object m odel in clu de su ppor t for r elat ion sh ips between object s, su ppor t for collect ion classes an d a set of base classes for dat e, tim e an d ch ar act er str in gs. Th e ODM G-93 st an dar d also allows for explicit n am es for an object or collection . Fr om a n am e, an applicat ion can dir ect ly r et r ieve th e n am ed object an d oper ate on it or n avigat e t o ot h er objects followin g r elat ion sh ip lin k s. A n am e in t h e sch em a plays t h e r ole of a var iable in a pr ogr am . Nam es ar e en tr y poin t s to th e dat abase. Fr om t h ese en tr y poin t s, ot h er object s can be r each ed t h r ou gh associative qu er ies or n avigat ion . Th e O2 OD MG Dat abase is fu lly com patible wit h t h e OD MG object m odel, object qu er y lan gu age (OQL) an d C++ bin din g.

O2 ODMG Dat abase System Tu tor ial

11

1

Introduction

The O2 ODMG C++ Binding Th e ODMG C++ lan gu age bin din g is design ed t o br in g t r an spar en t per sist en ce t o C++ applicat ion s. Per sist en ce is t h e abilit y for an object t o ou t live t h e pr ocess wh ich cr eat ed it . Tr an spar en cy applies t o bot h t h e t ype syst em an d t h e pr ogr am m in g lan gu age. Fr om t h e C++ developer ’s per spect ive t h er e is a sin gle u n ified t ype syst em acr oss t h e pr ogr am m in g lan gu age an d t h e dat abase. Th er efor e an y C++ class can be stor ed in t h e database. Th e dat abase m an ipu lat ion lan gu age is C++ so th er e is n o n eed for a separ at e database pr ogr am m in g lan gu age t o access an d m an ipu lat e data. Th e ODMG C++ bin din g con sist s of st an dar d C++ code. Th er e ar e n o n ew lan gu age con st r u ct s u sed for t h e bin din g. Th e bin din g m ak es u se of C++ t em plat es t o pr ovide per sisten ce. Sin ce t h e code is st an dar d C++ code t h er e is n ot a special pr e-com piler for t h e sou r ce code, so you can con tin u e t o u se an y of you r exist in g C++ t ools as well as adopt n ew tools in th e fu t u r e.

12


Benefits of porting to O2

1.3 Benefits of porting to O2 A sh or t ban k in g applicat ion is pr ovided for t h e pu r poses of th is t u t or ial. It is an au tom at ed teller m ach in e (ATM ) applicat ion . Th e applicat ion allows u ser s t o login t o t h eir accou n t s t o m ak e deposits or wit h dr awals an d t o ch eck t h e balan ce of an accou n t or r eview r ecen t t r an sact ion s. Th e ch an ges r equ ir ed to por t t h e application t o O2 in volve less t h an 10% of t h e code an d t h ou gh on ly a sm all por t ion of code is m odified t h e applicat ion gain s su bst an t ially in t er m s of fu n ct ion alit y. It gain s in t er m s of du r abilit y, con cu r r en cy, scalability an d accessibilit y t h r ou gh OQL. Th e or igin al ver sion of t h e sou r ce code r eads cu st om er data at st ar t u p an d wr it es in for m at ion back wh en t h e pr ogr am en ds. If t h e pr ogr am fails all m odification s m ade will be lost . Th e possibilit y of losin g dat a is u n accept able. Th e O2 System pr otect s dat a by en su r in g t h at all ch an ges com m it t ed to t h e dat abase ar e in deed wr it t en t o th e dat abase an d t h at if a cr ash occu r s t h e dat a is safe fr om cor r u pt ion . Th e O2 System allows for con cu r r en t access t o dat a. Wit h con cu r r en t access it is possible t o h ave m u lt iple pr ocesses accessin g t h e dat abase at th e sam e t im e. For exam ple you cou ld h ave sever al ATM m ach in es accessin g th e sam e dat abase. Th e dat abase con t r ols t h e access t o t h e dat a en su r in g t h at ever y clien t h as a con sist en t view of th e dat a. On e of t h e m ost im por tan t im pr ovem en ts t o t h e sam ple applicat ion will be t o m ak e t h e application m or e scalable. Th e or igin al applicat ion is lim it ed in t h e am ou n t of dat a it can st or e t o m ach in e m em or y. By u sin g t h e O2 dat abase t h e applicat ion is n o lon ger lim it ed in t h is way. Th er e is n o pr act ical lim it t o th e size of an O2 dat abase. Th e addit ion of ODMG collect ion classes an d OQL qu er ies r edu ces th e ph ysical lim itation s of t h e applicat ion . ODM G collection classes pr ovide flexible collect ion s wh ich can gr ow as dat a expan ds an d t h ey ar e t igh tly lin k ed t o t h e dat abase en gin e t o pr ovide efficien t cach in g of lar ge collection s. By r eu sin g t h e OD MG collect ion classes you will also r edu ce t h e am ou n t of code t h at you n eed t o develop an d m ain t ain . Th e OQL qu er y lan gu age is an opt im ized qu er y lan gu age. All qu er ies will be au tom at ically opt im ized t o im pr ove t h e per for m an ce of you r applicat ion . Th e OQL qu er y lan gu age is a declar at ive qu er y lan gu age so t h e ph ysical st r u ct u r e of t h e dat a can be ch an ged wit h ou t h avin g to ch an ge th e qu er y. Th is allows an adm in ist r at or to add in dexes to lar ge collection s wit h ou t h avin g t o m odify or r ecom pile t h e applicat ion .


13

1

Introduction

Th e O2 System can r eplace exist in g code th at im plem en ts dat abase t ype feat u r es t h u s r edu cin g th e am ou n t of code t o be m ain t ain ed. For n ew developm en t s t h e O2 Syst em r edu ces t h e am ou n t of code r equ ir ed. For t h e sam ple applicat ion we can r em ove t h e code for t h e initializeAccounts an d updateAccounts m eth ods. By r em ovin g th e code wh ich becom es u seless th r ou gh por tin g we r edu ce t h e size of t h e applicat ion by 200 lin es or 25%. On e of t h e k ey featu r es of t h e O 2 ODMG C++ Bin din g is t h at it does n ot ext en d t h e C++ lan gu age t o add special dat abase k eywor ds. Th e bin din g u ses st an dar d C++ con cept s su ch as t em plates an d in h er it an ce t o pr ovide con n ect ion t o t h e dat abase. Th e u se of st an dar d C++ does n ot for ce developer s t o ch an ge t h e m et h ods or t ools t h ey u se t o develop code. An y t ool t h at can wor k wit h stan dar d C++ can be u sed wit h t h e O 2 ODMG C++ Bin din g. Th ese in clu de fr on t en d case t ools wh ich gen er at e C++ code, edit or s, debu gger s, m em or y m an agem en t t ools an d t h ir d par t y class libr ar ies. Th is t u t or ial is in ten ded t o pr ovide a qu ick in t r odu ct ion t o t h e O2 ODMG C++ In ter face an d t h e OQL qu er y lan gu age. Th er e ar e m an y im por t an t feat u r es of t h e O 2 Syst em t h at wer e n ot cover ed in t h is t u t or ial. Th ese in clu de dat abase feat u r es su ch as t r an sact ion types. sch em a u pdat es, war m an d cold r ecover y, an d su ppor t for con t in u ou s oper at ion . An ot h er obviou s advan t age is O2 Tech n ology’s com m it m en t t o in du st r y st an dar ds. Usin g a syst em t h at com plies wit h in du st r y st an dar ds en su r es t h e in ter oper abilit y bet ween you r applicat ion an d ot h er t ools an d does n ot lock you r sou r ce code t o a specific ven dor .

14


Example application

1.4 Example application In t h is t u t or ial we ar e goin g t o be wor k in g wit h a C++ ban k in g applicat ion wh er e cu st om er s u se au tom at ic t eller m ach in es (ATM) t o ch eck t h eir accou n ts or car r y ou t sim ple ban k in g t r an sact ion s. Th is is n ot a pr odu ct ion applicat ion , bu t a sim ple pr ogr am u sed for exam ple pu r poses on ly. Th e application u ses a sim ple t er m in al in ter face to com m u n icat e with cu st om er s. Befor e bein g por ted t o O2 , t h e applicat ion u ses st an dar d oper at in g syst em files t o st or e in for m at ion abou t cu st om er s an d accou n t s. Wh en t h e ATM applicat ion is star t ed in for m at ion abou t exist in g accou n t s is r ead fr om a file an d wh en t h e applicat ion st ops in for m at ion is wr it t en back t o th e file. Th e class com posit ion is sh own in figu r e 1.


15

1

Introduction

ATM

Terminal displayLogin displaySelectEvent displayBalance displaySelectAccount displayMessage displayPerson displayEvent getString getNumber getAmount

cash_balance total_deposits term account_list location lookupAccount dispenseCash printReceipt initializeAccounts run

Account number balance description owners events_completed lookupOwner newOwner insertEvent getNumber getBalance title deposit withdraw

Address Person firstName middleName lastName personal_id accounts address showDeposits showWithdraws showEvents

Attributes Methods

16

Street city state zip_code

Event machine message amount execute show

one to one

Figure 1.


one to many

Example application

Th e in h er itan ce h ier ar ch y of t h e even t classes is sh own in figu r e 2.

Event

depositEvent

withdrawEvent

balanceEvent

Figure 2.

Relevant files Th e applicat ion sou r ce code is st or ed in var iou s files: main.cxx - con t ain s t h e m ain pr ogr am . atm.hxx an d atm.cxx - con t ain t h e defin it ion of t h e ATM class an d m et h od defin it ion s. account.hxx an d account.cxx - con t ain t h e defin it ion s of t h e Addr ess, Per son an d Accou n t classes an d m et h od defin ition s. event.hxx an d event.cxx - con t ain t h e defin it ion s of t h e Even t , deposit Even t , wit h dr awEven t an d balan ceEven t classes an d t h eir m et h od defin it ion s. terminal.hxx an d terminal.cxx - con t ain t h e Ter m in al class defin ition an d m eth od defin it ion s. MakefileUnix.original or MakefileNt.original -con t ain th e m ak efile for com pilin g t h e or igin al ver sion of t h e applicat ion . Th e m ain r ou t in e of t h e pr ogr am cr eat es t h e ATM, Per son an d Accou n t object s, fr om dat a in a file an d t h en passes con t r ol t o t h e ATM ::r u n m et h od. Th e data file is locat ed in dat a/ accou n t s. Fin ally, README files descr ibe t h e st ep by st ep pr ocess t o r u n t h e t u t or ial. Please h ave a look at t h em .


17

1

Introduction

Th e ATM::r u n m et h od con t r ols t h e in t er act ion bet ween cu st om er s an d accou n t s. Th e m et h od fir st displays a login pr om pt t o t h e u ser . Th e login pr ocess pr odu ces an accou n t n u m ber an d a per son al iden t ificat ion n u m ber (PIN). Th e ATM:look u pAccou n t m eth od is t h en u sed t o fin d an accou n t cor r espon din g t o th e accou n t n u m ber . Th en t h e Accou n t ::look u pOwn er m et h od is u sed t o look u p a Per son based on t h e PIN. Th e t er m in al t h en displays a list of action s t h at t h e cu st om er can t ak e. Th e act ion s ar e r epr esen t ed as even t object s wh ich r epr esen t t h e in t er face between cu stom er s an d t h eir accou n t s. Even t object s ar e saved in t h e dat abase t o m ain t ain an accou n t h ist or y. Even t object s ar e t h e on ly n ew object s cr eat ed in t h e database wh ile th e ATM:Ru n m et h od is r u n n in g. Th e ot h er object s in th e database ar e on ly m odified wh en t h e ATM is r u n n in g, for in st an ce t h e Accou n t object is u pdat ed t o r eflect an y ch an ge in t h e balan ce of t h e accou n t an d also t o add even t s t o t h e even t h ist or y.

18


Setup

1.5 Setup It is assu m ed t h at t h e O2 soft war e is in st alled. If t h is is n ot t h e case, r efer t o t h e O2 In st allat ion sh eet for fu r t h er det ails. Th e O2 system m u st be set u p befor e you can begin por t in g t h e exam ple applicat ion . Set an en vir on m en t var iable called O2HOME specifyin g t h e dir ector y path wh er e t h e O2 soft war e is in st alled. Position you r self at O2HOME: > cd $O2HOME Add th e O2HOME/bin dir ect or y t o th e path in each wor k in g win dow: > set path = ($O2HOME/bin $path) In or der t o r u n t h e O 2 Syst em you n eed to h ave a .O2KEYS licen se file for th e m ach in e you ar e r u n n in g on . Th e .O2KEYS file sh ou ld be st or ed in th e O2 in st allat ion dir ect or y. Th e o2server pr ogr am calls t h e O2 dat abase ser ver . Each o2server r u n s a sin gle n am ed syst em . Th e logical defin it ion for each syst em is given in t h e .o2serverrc file locat ed in t h e O2HOME dir ect or y. Th e .o2serverrc file con t ain s t h e syst em n am e, n am e of t h e ser ver m ach in e, t h e locat ion of t h e catalog, log an d sh adow dir ect or y. For m or e in for m at ion abou t th e .o2serverrc file r efer t o t h e O2 System Adm in ist r at ion Gu ide. Fr om th e O2HOME dir ect or y u se t h e followin g com m an ds t o cr eat e a .o2serverrc file for t h e tu tor ial. > mkdir o2vol Edit t h e .o2ser ver r c file an d add th e followin g lin es: demo.server = demo.cataldir = $O2HOME/o2vol demo.logdir = $O2HOME/o2vol demo.shadowdir = $O2HOME/o2vol wh er e is h e n am e of t h e m ach in e wh er e th e O2 ser ver will run. Th e defau lt syst em n am e an d ser ver n am e can be specified by th e en vir on m en t var aible O2OPTIONS. Use th e followin g com m an ds t o set O2OPTIONS:


19

1

Introduction

On Un ix, (in sh) set O2OPTIONS "-system demo -server ; export O2SYSTEM (in csh) setenv O2OPTIONS "-system demo -server " On Win dows NT, u se th e Environment tab of t h e syst em pr oper t ies pan el to set t h e O2OPTIONS var iable. Th e O2OPTIONS en vir on m en t var iable is u sed by all O 2 u t ilit ies pr ogr am s. You m u st in it ialize a syst em befor e you can r u n a dat abase ser ver . Th e in it ializat ion pr ocess cr eat es t h e files u sed by th e dat abase ser ver . To in it ialize th e system u se th e followin g com m an d. > o2dba_init -system demo -server Now st ar t t h e dat abase ser ver for t h e system with t h e followin g com m an d: > o2server -system demo Each syst em can con t ain m u lt iple sch em as an d bases. A schema is a collect ion of class defin ition s. A base is a collect ion of in st an ces of classes. Sch em as allow for t h e r eu se of code by let t in g you or gan ize a gr ou p of classes t h at wor k t oget h er in t o a sin gle sch em a. For in st an ce, you cou ld cr eat e a cu st om er sch em a t h at cou ld con t ain sever al classes to deal with cu st om er s. Th en an y ot h er applicat ion th at n eeded to deal with cu st om er s h as on ly t o im por t th e r elevan t classes fr om t h e cu st om er sch em a. You m u st cr eat e t h e schema an d base for t h e t u t or ial. Th is can be don e fr om a C++ pr ogr am or in t er act ively u sin g t h e O2 adm in ist r at ion tools. We will cr eat e th e schema an d base in t er actively. Fir st st ar t t h e O2 adm in ist r at ion t ool. > o2dsa_shell Now cr eat e t h e sch em a an d base. Com m an ds ar e con fir m ed by t ypin g a n ew lin e followed by ctr l D. schema bankSchema; base bankBase; quit; ^D

20


Setup

Now copy t h e t u t or ial sou r ce code t o a wor k in g dir ect or y. To com plet e t h e tu t or ial you will n eed appr oxim at ely t en m egabyt es of disk space in t h e wor k in g dir ect or y. To copy t h e sou r ce code t o a dir ect or y called working_directory execu t e t h e followin g: On Un ix, > cd $O2HOME/samples/o2cplusplus/odmg_tutorial/ > cp -r * working_directory On Win dows NT, sim ply m ak e a copy/paste oper at ion t o t h e folder u sin g t h e NT Explor er . Th e dir ect or y called wor k in g_dir ect or y m u st alr eady exist . Now m ove t o t h e wor k in g dir ect or y On Un ix, > cd working_directory/original On Win dows NT, > cd working_directory\original You ar e n ow r eady t o por t t h e exam ple applicat ion t o O 2 .


21

1

22

Introduction


22

P orting a C++ A p p l i ca ti o n

Th is ch apt er descr ibes h ow to por t an exam ple C++ applicat ion t o O2 . It con tain s th e followin g sect ion s: • St or e C++ object s in an O2 dat abase: im por t in g class defin it ion s t o O 2 • Ch an ge C++ poin t er s t o per sist en t poin t er s • In clu de files • Con n ect t o t h e database • Ru n a t r an sact ion • Cr eat e n am es • M odify sou r ce code • Cr eat e per sisten t object s • Replace ar r ays by collect ion classes


23

2


Th e exam ple application wor k s in it s cu r r en t st at e. Befor e pr oceedin g we su ggest you br owse t h r ou gh t h e files t o fam iliar ize you r self wit h t h e applicat ion , th en com pile, lin k an d execu te it . To com pile an d lin k t h e applicat ion en t er th e followin g com m an d: On Un ix > make -f MakefileUnix.original On Win dows NT > nmake -F MakefileNt.original On ce it h as been com piled r u n t h e pr ogr am t h r ou gh t h e followin g com m an ds: Star t t h e applicat ion > bank En ter t h e Accou n t n u m ber 11111 at t h e pr om pt an d pr ess en t er . Th e followin g will be displayed. Welcome to the Bank of O2 Enter Account Number, 0 to exit > 11111 At th e per son al ID pr om pt en ter t h e n u m ber 9999 an d pr ess en t er . Enter Personal ID Number, 0 to exit > 9999 You ar e n ow logged in t o t h e syst em so you can car r y ou t t r an sact ion s wit h t h e accou n t s available. Now exit t h e pr ogr am . We will n ow go t h r ou gh t h e st eps n ecessar y t o por t t h e existin g applicat ion t o th e O2 Syst em . Figu r e 3 sh ows th e im por t , com pile an d lin k st eps t h at ar e n ecessar y t o gen er at e an O2 C++ dat abase applicat ion .

24


C++ Class Definitions

o2import

Generated C++ Code

Application C++ Code

C++ Compiler

Database

Object Code

O2 Runtime Library

Linker

Executable Application O2 Runtime Library Figure 3.


25

2


2.1 Store C++ objects in an O2 database To st or e a C++ object in an O2 database, t h e dat abase n eeds in for m ation on t h e st r u ct u r e of t h e object . You can su pply th is in for m at ion by im por t in g C++ class defin it ion s. Th e im por t pr ocess par ses class defin it ion s to gen er at e m et a in for m at ion for t h e dat abase an d it en h an ces t h e exist in g class defin it ion s t o add per sist en ce. An en h an ced class defin it ion is a su bclass of a r oot per sist en t class (o2 _r oot ) an d sever al m et h ods ar e gen er ated for t h e class wh ich m an age in t er action wit h t h e dat abase. On ce t h e class h as been im por t ed in t o O2 , in stan ces of t h e class can be st or ed in t h e database or can con t in u e t o be u sed as n or m al t r an sien t C++ object s. Su ch classes ar e k n own as per sist en t capable classes. Th e o2cpp_import tool im por t s class defin it ion s in t o O 2 . To sim plify th e pr ocess of im por t in g m u ltiple classes in t o O2 a u t ilit y is pr ovided. Th is is o2makegen an d it gen er ates a M ak efile t o im por t all you r classes. Th e gen er at ed Mak efile can be u sed dir ect ly or can be in t egr at ed in t o you r exist in g m ak e pr ocess. Th e o2makegen pr ogr am t ak es a con figu r at ion file as in pu t . Th e con figu r at ion file for t h is tu t or ial is alr eady wr it ten . Th e file is bank.config. Th is con figu r at ion file in clu des com m en ts wh ich descr ibe t h e syn t ax. You sh ou ld r eview th is file t o bet ter u n der st an d th e in for m at ion n eeded t o im por t classes in t o O2 . Th e files im por ted m u st be com pilable in C++ or self-con t ain ed. H eader files ar e u su ally par sed du r in g t h e com pilat ion of a sou r ce file. Th e sou r ce file m ay pr ovide con t ext in for m at ion t h at is n eeded t o par se t h e h eader file. Com m an d lin e opt ion s m ay also pr ovide vit al in for m at ion . Most h eader files ar e self con t ain ed, h owever . Som e h eader files do r equ ir e addition al con t ext in for m at ion t o be im por t ed in t o O 2 . Th e m ost com m on addit ion al in for m ation n eeded is ot h er class defin it ion s. Th e best way t o solve t h is is to or der t h e im por t pr ocess so t h at an y class defin it ion n eeded by a class h as alr eady been im por t ed. Som et im es a closed cir cle of poin t er s can exist in class defin it ion s, for exam ple: class A { B *pointer }; class B { A *pointer }; To br eak t h is cycle you can u se t h e ImpForwardClasses opt ion with o2makegen t o declar e classes wh ich ar e n eeded t o par se a file, bu t wh ich h ave n ot yet been defin ed.

26


Store C++ objects in an O2 database

On ce im por t ed, t h e en h an ced per sist en t capable class defin it ion s m u st be u sed in st ead of t h e or igin al t r an sien t class defin ition s. You can eit h er h ave t h e o2cpp_import over wr it e t h e or igin al ver sion of th e h eader file or wr it e it t o an ot h er file. In t h is exam ple we do n ot over wr it e t h e h eader files. Th e lin e "[FILENAM E]Im pOu t pu t Dir : ou t pu t " in bank.config specifies t h at th e gen er at ed files sh ou ld be st or ed in t h e output dir ect or y. To gen er ate t h e Mak efile for t h e applicat ion execu t e t h e followin g com m an d: > o2makegen bank.config


27

2


2.2 Change C++ pointers to persistent pointers For each class T im por t ed in t o O 2 an an cillar y class d_Ref is available. An in stan ce of t h e d_Ref class is called a per sist en t poin t er . Th e per sist en t poin t er is t h en u sed t o r efer en ce an in stan ce of a per sist en t capable class. Per sist en t poin t er s ar e m an ipu lat ed in t h e sam e way as st an dar d C++ poin t er s. Per sist en t poin t er s m ain tain a r elat ion sh ip bet ween two object s per m an en t ly in t h e dat abase. Stan dar d C++ poin t er s r efer t o an addr ess wh ich is valid on ly wh ile a pr ogr am is execu t in g. Befor e im por t in g class defin ition s in to O2 you m u st ch an ge st an dar d C++ poin t er s in per sist en t capable classes to per sisten t poin t er s. For in st an ce in t h e exam ple applicat ion t h e Per son class h as a poin t er t o an addr ess object . class Person { ... Address *address; ... }; So t h at t h e dat abase can m ain t ain t h e r elat ion sh ip bet ween t h e Per son an d t h e Addr ess you n eed t o ch an ge t h e poin t er t o a per sist en t poin t er . class Person { ... d_Ref address; ... }; Th e per sist en t poin t er m ech an ism offer s a n u m ber of advan t ages t o t h e C++ pr ogr am m er . Per sist en t poin t er s ch eck r efer en t ial in tegr it y so you r dat a is safe fr om cor r u pt ion by dan glin g poin ter s. A per sist en t poin t er can addr ess m or e dat a t h an th e st an dar d 32 bit C++ poin t er so you r dat abase can be scaled t o a lar ger size. o2cpp_import h elps you by au t om at ically m odifyin g t h e class defin ition t o u se per sist en t poin t er s in st ead of st an dar d C++ poin t er s. If an at t r ibu t e is a poin t er t o an ot h er k n own per sist en t class th e poin t er will au tom at ically be ch an ged t o a per sist en t poin ter . Th e m et h od sign at u r es m ay also con t ain r efer en ces t o per sist en t capable classes. However , m et h od sign at u r es m ay or m ay n ot n eed t o be ch an ged depen din g on wh et h er or n ot t h e dat a r efer en ced is per sist en t . For t h is r eason m et h od sign at u r es ar e n ot m odified by o2cpp_import an d it is left t o you t o decide if m eth od sign atu r es sh ou ld be ch an ged. In t h e accou n t .h xx file you on ly n eed t o ch an ge t wo m et h od sign at u r es of t h e Accou n t class. Th e Per son an d Addr ess class can be im por t ed wit h ou t ch an ge. You m u st m ak e t h e ch an ges ou tlin ed below t o t h e Accou n t class.

28


Change C++ pointers to persistent pointers

Wh en m ak in g ch an ges you can delet e lin es or con ver t t h em t o com m en t s. Bot h t h e or igin al ver sion an d th e m odified ver sion ar e in t h e file. Th e m odified ver sion is in com m en t s. You n eed on ly r em ove th e com m en t s an d delete t h e or igin al ver sion or con ver t it t o com m en t s. Th e best way t o fin d t h e lin es t h at n eed t o be ch an ged is t o sear ch for t h e class n am e or m et h od n am e wh er e t h e ch an ge tak es place. Th e lin e "/ / ODMG Per sist en t Ver sion " sh ou ld r em ain in com m en ts.

• account.hxx file In t h e Accou n t class defin it ion in t h e accou n t .h xx file delet e or com m en t ou t th e followin g lin es: // Original Version Person *lookupOwner(int pin_number) const; void newOwner(Person *NewOwner); void insertEvent(Event* event); an d add or u n -com m en t th e followin g lin es in t h eir place: // ODMG Persistent Version d_Ref lookupOwner(int pin_number) const; void newOwner(d_Ref &NewOwner); void insertEvent(const d_Ref &event); You m u st also ch an ge t h e cor r espon din g sign at u r e of th e m et h od defin ition .

• account.cxx file In t h e file accou n t .cxx delet e or com m en t ou t t h e followin g lin e: // Original Version Person * Account::lookupOwner(int pin_number) const { an d add or u n -com m en t t h e followin g lin e in it s place: // ODMG Persistent Version d_Ref Account::lookupOwner(int pin_number) const{ In t h e file accou n t .cxx delet e or com m en t ou t t h e followin g lin e: // Original Version void Account::newOwner(Person *NewOwner) { an d add or u n -com m en t t h e followin g lin e in it s place: // ODMG Persistent Version void Account::newOwner(d_Ref &NewOwner) {


29

2


In t h e file accou n t .cxx delet e or com m en t ou t t h e followin g lin e: // Original Version void Account::insertEvent(Event* event) { an d add or u n -com m en t t h e followin g lin e in it s place: // ODMG Persistent Version void Account::insertEvent(const d_Ref &event) {

• atm.hxx file In t h e file at m .h xx again you on ly n eed t o ch an ge t h e m et h od sign at u r es. Mak e t h e ch an ges ou t lin ed below t o at m .h xx. In t h e ATM class defin it ion in t h e file at m .h xx delet e or com m en t ou t t h e followin g lin es: // Original Version Account *newAccount(int account_number, ...); Account *lookupAccount(int account_number) const; an d add or u n -com m en t t h e followin g lin es in t h eir place: // ODMG Persistent Version d_Ref newAccount(int account_number, ...); d_Ref lookupAccount(int account_number) const; Again ch an ge t h e cor r espon din g sign at u r es in t h e m et h od defin it ion s.

• atm.cxx file In t h e file at m .cxx delet e or com m en t ou t th e followin g lin e: // Original Version Account * ATM::lookupAccount(int account_number) const an d add or u n -com m en t t h e followin g lin e in it s place // ODMG Persistent Version d_RefATM::lookupAccount(int account_number)const In file atm .cxx delet e or com m en t ou t t h e followin g lin e: // Original Version Account * ATM::newAccount(int account_number, ...) { an d add or u n -com m en t t h e followin g lin e in it s place // ODMG Persistent Version d_Ref ATM::newAccount(int account_number, ...);

30


Change C++ pointers to persistent pointers

• terminal.hxx file In file ter m in al.h xx in t h e class Ter m in al delet e or com m en t ou t t h e followin g lin es: // Original Version Account *displaySelectAccount(const Person* customer) const; void displayPerson(const Person *customer) const; an d add or u n -com m en t t h e followin g lin e in th eir place // ODMG Persistent Version d_Ref displaySelectAccount(const d_Ref &customer) const; void displayPerson(const d_Ref &customer) const; On ce again ch an ge t h e cor r espon din g m et h od defin it ion s.

• terminal.cxx file In file ter m in al.cxx delet e or com m en t ou t t h e followin g lin e: // Orignal Version Account* Terminal::displaySelectAccount(const Person* customer) const{ an d add or u n -com m en t t h e followin g lin e in it s place // ODMG Persistent Version d_Ref Terminal::displaySelectAccount(const d_Ref& customer) const { In file ter m in al.cxx delet e or com m en t ou t t h e followin g lin e: // Original Version void Terminal::displayPerson(const Person *customer) const { an d add or u n -com m en t t h e followin g lin e in it s place // ODMG Persistent Version void Terminal::displayPerson(const d_Ref& customer) const{


31

2


2.3 Include files You m u st add t h e followin g in clu de files t o t h e applicat ion . Th ese in clu de files con t ain t h e object s, classes an d fu n ct ion s wh ich pr ovide t h e in t er face bet ween t h e applicat ion an d t h e database. Th e atm .h xx file is in clu ded by ever y sou r ce file so we will add t h e in clu de lin es t o t h at file.

• atm.hxx file In t h e file at m .h xx add or u n -com m en t t h e followin g lin es // ODMG Persistent Version // Contains d_Session, d_Database and d_Transaction classes #include “o2lib_CC.hxx // Contains templates for d_Ref, d_Set, d_List, ... #include “o2template_CC.hxx” // Contains OQL interface #include “OQL_CC.hxx”

32


Connect to the database

2.4 Connect to the database Th e ODM G C++ bin din g con t ain s a set of classes for database m an agem en t. Th e d_Session class set s u p com m u n icat ion s between a C++ applicat ion an d a dat abase ser ver . Th e d_D at abase class is u sed t o cr eat e, dest r oy, open an d close a dat abase. Th e d_Dat abase class can also be u sed t o cr eat e an d dest r oy n am es in t h e dat abase as well as associat in g C++ var iables t o n am es. Th e d_Tr an sact ion class star t s an d en ds t r an sact ion s wit h t h e dat abase. You n eed to add in st an ces of all of t h ese classes t o th e exam ple applicat ion . Th e d_Session class h as a begin m et h od t o est ablish com m u n ication wit h t h e dat abase ser ver . Th e followin g lin e in t h e sou r ce code sh ows t h e call t o begin : session.set_default_env(); if (session.begin(argc,argv)) { Th e par am et er s passed t o begin ar e t h e ar gc an d ar gv par am et er s passed t o t h e m ain r ou t in e. Th e set _defau lt _en v m et h od sets t h e O2 Syst em n am e, t h e n am e of t h e m ach in e t h at t h e O2 Ser ver is r u n n in g on an d t h e locat ion of th e O2 soft war e. Th e d_Session class also h as an en d m et h od. Th is m eth od closes t h e con n ection wit h th e dat abase. Th e followin g lin e fr om t h e sou r ce code sh ows t h e call to en d: session.end(); Aft er con n ect in g t o t h e dat abase ser ver t h e applicat ion m u st specify wh ich dat abase t o open . Th e followin g lin e sh ows t h e call n eed t o open t h e ban k Base dat abase. database_g->open("bankBase"); It is possible t o open an d close m u lt iple dat abases in a sin gle session . Th e followin g lin e sh ow th e call n eeded t o close t h e dat abase database_g->close();


33

2


2.5 Run a transaction In or der t o m odify dat a in t h e database you n eed to be in a t r an sact ion . Th e t r an sact ion m ech an ism pr ot ect s an applicat ion again st failu r e an d en su r es t h at dat a is con sist en t in a m u lt i-u ser en vir on m en t . In side a t r an sact ion , O2 pr ovides an isolat ion pr oper t y by lock in g t h e objects. Con sequ en t ly, in cer tain cir cu m st an ces a t r an sact ion wait s u n t il an oth er t r an sact ion com m its. To m in im ize t h e wait t im e, we declar e a t r an sact ion on ly in t h e m et h ods th at m odify t h e dat a.

• account.cxx file In th e m et h od Accou n t ::deposit add or u n -com m en t t h e followin g lin es: d_Transaction transaction; transaction.begin(); ... transaction.validate(); In th e m et h od Accou n t ::wit h dr aw add or u n -com m en t t h e followin g lin es: d_Transaction transaction; transaction.begin(); ... transaction.validate();

• atm.cxx file In th e m et h od ATM::in it ializeAccou n t s() add or u n -com m en t t h e followin g lin es: d_Transaction transaction; transaction.begin(); ... transaction.validate();

34


Create names

2.6 Create names You will n eed t o cr eat e n am es in th e dat abase. A n am e is t h e en t r y poin t for t h e application to th e database. You can cr eat e a sin gle n am e for t h e ATM object , ATM_MACH INE an d th en access all per sist en t dat a by t r aver sin g fr om t h e n am ed ATM object . Sin ce t h e n am e n eeds t o be cr eat ed on ly on ce you can cr eat e it du r in g in it ializat ion . Th e set_object _n am e m et h od of t h e d_Database class is u sed t o cr eate t h e n am e. Th e followin g lin e sh ows t h e call n eeded t o cr eat e t h e ATM _MACHINE n am e database_g-> set_object_name(atm_machine, "ATM_MACHINE"); On ce t h e n am e is cr eat ed you access t h e n am e t h r ou gh a per sist en t poin t er . You can associat e a per sist en t poin t er wit h a n am ed object by t r an sm it t in g t h e n am e as an ar gu m en t t o t h e con str u ct or . For exam ple: d_Ref machine("ATM_MACHINE"); Th e r elat ion sh ip can also be est ablish ed by u sin g t h e d_Dat base::look u p_object m et h od. We will u se t h e look u p_object m et h od for t h e ATM applicat ion sin ce th e per sist en t poin t er is declar ed befor e t h e n am e h as been cr eat ed. Th e followin g lin e sh ows t h e call n eeded t o look u p th e n am e ATM_MACH INE atm_machine->lookup_object("ATM_MACHINE");


35

2

Porting a C++ Application 2.7 Modify source code We n eed t o cr eat e an in st an ce of d_D at abase in global scope so t h at we can cr eate n ew object s in t h e database in an y fu n ct ion or m et h od. Near lin e 80 in m ain .cxx add or u n -com m en t th e followin g global declar at ion .

• main.cxx file In t h e file m ain .cxx n ear lin e 80 add or u n -com m en t t h e followin g global declar at ion . d_Database* database_g = new d_Database; We also n eed t o add a declar at ion so t h at ot h er files can access t h e global var iable. We will add th e declar at ion t o t h e file at m .h xx sin ce it is in clu ded by ever y sou r ce file.

• atm.hxx file In file atm .h xx add or u n -com m en t t h e followin g lin es: // ODMG Persistent Version // Global database pointer for creating objects in the database extern d_Database* database_g; You can t h en add th e code t o est ablish a con n ect ion with t h e dat abase, open t h e ban k Base dat abase, st ar t t h e t r an sact ion , cr eat e th e n am es in t h e dat abase, en d th e t r an sact ion , close t h e ban k Base an d fin ally close t h e con n ect ion wit h t h e dat abase. In t h e class ATM add or u n -com m en t t h e followin g lin e: void d_activate {term = new Terminal;} You m u st in itialize t h e t em por ar y at tr ibu t e t er m wh en t h e per sist en t object of t h e class ATM is r ead fr om t h e dat abase for th e fir st t im e.

• main.cxx file In t h e file m ain .cxx delete or com m en t ou t t h e followin g lin es: // Original Version ATM* atm_machine; atm_machine->initializeAccounts(); atm_machine = new ATM; atm_machine->run(); an d add or u n -com m en t t h e followin g lin es in t h eir place, n ot e t h at t h e com m en ted ou t por t ion begin s wit h "/ * BEGIN PERSISENT VERSION"

36


Modify source code

an d en ds wit h "END PERSISTENT VERSION */ " in st ead of th e "/ / " com m en t s: // ODMG Persistent Version /* BEGIN PERSISTENT VERSION */ d_Session session; d_Transaction transaction; // ODMG Persistent Version d_Ref atm_machine; session.set_default_env(); if (session.begin(argc,argv)) { cerrinitializeAccounts(); } else { database_g->open("bankBase"); atm_machine = database_g->lookup_object("ATM_MACHINE"); } if (! atm_machine) { cerr close(); session.end(); /* END PERSISTENT VERSION */ Now you ar e r eady t o cr eat e object s in t h e dat abase.


37

2


2.8 Create persistent objects In t h e OD MG bin din g, per sist en ce is specified at object cr eat ion tim e. If you wan t t o cr eat e a per sist en t object you t r an sm it a d_Database poin t er t o t h e n ew oper at or of t h e object . Sin ce all per sist en t dat a is accessed fr om n am es, each n ewly cr eated per sist en t object sh ou ld be at t ain able fr om a n am e. An object can be associat ed dir ect ly wit h a n am e or an object can be in dir ect ly att ain able fr om a n am e th r ou gh per sist en t poin t er s. Th e allocat ion st at em en ts in t h e exam ple applicat ion m u st be m odified t o cr eat e per sist en t object s in st ead of t r an sien t on es. Som e local var iable declar ation s wh ich ar e poin t er s t o per sist en t object s n eed t o be ch an ged t o per sist en t poin ter s. Th is en su r es th at per sist en t object s ar e k ept in t h e C++ cach e. Th e dat abase will swap per sist en t object s ou t of t h e cach e t h at ar e n o lon ger poin t ed t o by a per sisten t poin t er .

• account.cxx file In file accou n t .cxx in t h e m et h od Accou n t ::deposit delet e or com m en t ou t t h e followin g lin es: // Original Version depositEvent* event = new depositEvent(machine_g); an d add or u n -com m en t t h e followin g lin es in t h eir place // ODMG Persistent Version d_Ref event = new(database_g) depositEvent(machine_g); In file accou n t .cxx in t h e m et h od Accou n t ::wit h dr aw delet e or com m en t ou t t h e followin g lin es: // Original Version withdrawEvent* event = new withdrawEvent(machine_g); an d add or u n -com m en t t h e followin g lin es in t h eir place

d_Ref event = new(database_g) withdrawEvent(machine_g);

38


Create persistent objects

• atm.cxx file In file at m .cxx in t h e m et h od ATM::r u n delet e or com m en t ou t t h e followin g lin es: // Original Version Account * current_account; Person * current_customer an d add or u n -com m en t t h e followin g lin es in t h eir place // ODMG Persistent Version d_Ref current_account; d_Ref current_customer; In file at m .cxx in t h e con st r u ct or ATM ::ATM () delet e or com m en t ou t t h e followin g lin es: // Original Version location = new Address("3600_BAYSHORE","PALO ALTO","CA","94043"); an d add or u n -com m en t t h e followin g lin es in t h eir place // ODMG Persistent Version location = new(database_g) Address("3600_BAYSHORE", "PALO_ALTO", "CA", "94303"); In file at m .cxx in t h e m et h od ATM ::look u pAccou n t (in t accou n t _n u m ber ) delet e or com m en t ou t t h e followin g lin es: // Original Version Account *target_account = (Account*) NULL; an d add or u n -com m en t t h e followin g lin es in t h eir place // ODMG Persistent Version d_Ref target_account = (Account*)NULL; In file at m .cxx in t h e m et h od ATM:in it ializeAccou n t s() delet e or com m en t ou t th e followin g lin es: // Original Version Person* current_person; ... Account* new_account = new Account; inFile >> * new_account; ... // Original Version current_person = new Person; inFile >> * current_person;


39

2


an d add or u n -com m en t t h e followin g lin es in t h eir place // ODMG Persistent Version d_Ref current_person; ... d_Ref new_account = new(database_g) Account; inFile >> * (new_account.ptr()); ... // ODMG Persistent Version current_person = new(database_g) Person; inFile >> * (current_person.ptr()); In file atm .cxx in t h e m et h od ATM:n ewAccou n t(in t accou n t_n u m ber , ...) delet e or com m en t ou t t h e followin g lin es: // Original Version Account* new_account = new Account(account_number, description, balance); an d add or u n -com m en t t h e followin g lin es in t h eir place // ODMG Persistent Version d_Ref new_account = new(database_g) Account (account_number, description, balance); Sin ce t h e ATM object is n am ed an d all per sist en t object s ar e associat ed wit h t h e ATM by per sist en t poin t er s n o addition al n am es n eed t o be cr eat ed. J u st as wit h a typical C++ pr ogr am you can explicit ly delete object s fr om th e dat abase wh en t h ey ar e n o lon ger n eeded. However , O2 pr ovides a gar bage fu n ct ion t o deal wit h dat a t h at is n ot delet ed by t h e applicat ion . In file accou n t .cxx in t h e oper at or >> (ifst r eam & , Per son & ) delet e or com m en t ou t t h e followin g lin es: p.address = new Address; ifs >> *p.address ... Account* current_account; an d add or u n -com m en t t h e followin g lin es in t h eir place p.address = new(database_g) Address; ifs >> *(p.address.ptr()); ... d_Ref current_account;

40


Build and Run the Application

2.9 Build and Run the Application Th e sam ple applicat ion is n ow por t ed t o th e O2 Syst em . To com pile, lin k an d r u n t h e applicat ion en t er th e followin g com m an d: On Un ix, > make clean > make On Win dows NT, > nmake clean > nmake If n ecessar y, cor r ect an y t ypin g er r or s you m igh t h ave m ade t h at cau se syn t ax er r or s an d r epeat t h e m ak e. On ce it h as been com piled an d lin k ed r u n t h e pr ogr am t h r ou gh t h e followin g com m an ds: St ar t t h e applicat ion > bank -initialize En t er t h e Accou n t n u m ber 11111 at t h e pr om pt an d pr ess en t er . Th e followin g will be displayed. Welcome to the Bank of O2 Enter Account Number, 0 to exit > 11111 At t h e per son al ID pr om pt en t er t h e n u m ber 9999 an d pr ess en t er . Enter PIN Number > 9999 You ar e n ow logged in to t h e syst em so you can car r y ou t tr an sact ion s wit h t h e accou n t s available. Now exit t h e pr ogr am


41

2


2.10 Replace arrays by collection classes ODMG-93 in t r odu ces pr edefin ed gen er ic collect ion classes. An O2 OD MG dat abase su ppor ts all ODM G collect ion classes. Th e collect ion s su ppor t ed ar e: d_Set - u n or der ed collect ion of elem en t s wit h n o du plicat es. d_Bag - u n or der ed collect ion of elem en t s t h at allows for du plicat es. d_List - an or der ed collection of elem en t s t h at allows for du plicates. d_Var r ay - a on e dim en sion al ar r ay of var yin g len gt h . Collection classes u se st an dar d C++ t em plat e classes t o pr ovide su ppor t for elem en ts of an ar bit r ar y type. Th ese classes h ave m et h ods for var iou s oper ation s, su ch as in ser t , delet e, appen d, u n ion , in t er sect ion , et c. Th er e is also an it er at or t em plat e class for defin in g iter ator s for an y t ype of collect ion . Th e it er at or s ar e u sed t o scan a collect ion sequ en tially r et u r n in g each m at ch in g elem en t fr om t h e collect ion . Th e u se of collect ion classes in C++ pr ogr am s m ak es t h e pr ogr am s m or e scalable. Ou r exam ple applicat ion u ses ar r ays t o st or e collect ion s. Th e size of t h e ar r ays is set at t h e t im e t h e applicat ion is com piled. Th e OD MG C++ collect ion classes ar e n ot of a fixed size an d can expan d as t h e applicat ion evolves. Collection classes ar e t igh t ly cou pled to t h e O 2 dat abase t o pr ovide t r an spar en t cach in g of lar ge collect ion s. Wh en an applicat ion accesses a lar ge ODM G collect ion on ly a por t ion of t h e collect ion is br ou gh t in t o applicat ion m em or y. As t h e applicat ion tr aver ses t h e collect ion t h e r est of t h e collect ion is br ou gh t in . Accessin g data in collect ion s can be speeded u p by cr eat in g in dexes on a collect ion . You can n ow r eplace t h e ar r ays in t h e exam ple application wit h collect ion classes. Th e ATM class con t ain s t h e list of accou n ts. Th is is k n own as t h e accou n t s_list . Th e list of accou n t s is im plem en t ed u sin g a st an dar d C++ ar r ay. Sin ce t h er e is n o r equ ir em en t t o m ain t ain an y or der in g on t h e list of accou n t s we will u se a d_Set t o r eplace t h e ar r ay. Fir st we n eed t o m odify t h e declar at ion of t h e accou n t list .

• atm.hxx file In t h e ATM class declar at ion in t h e file at m .h xx com m en t ou t or delete t h e followin g lin es: // Original Version Account *accounts_list[MAX_ACCOUNTS]; an d add or u n -com m en t t h e followin g lin es in t h eir place:

42


Replace arrays by collection classes

// ODMG Collection Class Replacement d_Set< d_Ref > accounts_list; Not e t h e u se of a space bet ween > > to differ en t iate bet ween a n ested t em plat e an d t h e sh ift oper ator . Now m odify t h e code wh er e t h e accou n t s_list is bein g u sed. On ly t h e look u pAccou n t m et h od accesses t h e accou n t s_list . Rem ove t h e in it ializat ion code th at is n o lon ger n eeded t h en r eplace t h e for loop u sed in t h e m et h od wit h t h e u se of an iter ator . Fir st cr eat e t h e it er at or fr om t h e accou n ts_list collect ion an d t h en t r aver se th e collect ion u sin g t h e it er at or .

• atm.cxx file In t h e con st r u ct or ATM::ATM in t h e file atm .cxx delet e or com m en t ou t t h e followin g lin es: // Original Version //for(int i=0;igetNumber() == account_number) { target_account = accounts_list[i]; } break; } an d add or u n -com m en t t h e followin g lin es in t h eir place: // ODMG Collection Class Replacement d_Ref search_account; d_Iterator< d_Ref > iterator = accounts_list.create_iterator(); while ( iterator.next(search_account) ) { if (search_account->getNumber() == account_number) target_account = search_account; } break;


43

2


M odify t h e accou n t cr eat ion r ou t in e t o appen d t h e n ew accou n t on t o t h e list by m ak in g t h e followin g m odificat ion . In t h e m et h od ATM::in itializeAccou n t s in th e file at m .cxx delet e or com m en t ou t t h e followin g lin es:

// Original Version int i = 0; while (accounts_list[i] != NULL) i++; accounts_list[i] = new_account; an d add or u n -com m en t t h e followin g lin es in t h eir place: // ODMG Collection Class Version accounts_list.insert_element( new_account ); In t h e m et h od ATM::n ewAccou n t in t h e file at m .cxx delet e or com m en t ou t t h e followin g lin es:

// Original Version int i = 0; while (accounts_list[i] != NULL) i++; accounts_list[i] = new_account; an d add or u n -com m en t t h e followin g lin es in t h eir place: // ODMG Collection Class Version accounts_list.insert_element( new_account ); Replace t h e ar r ay of poin t er s t o even t s in t h e Accou n t class t o u se an OD MG collect ion class. Th e or der of t h e even ts is sign ifican t so u se a d_List t o m ain t ain t h e or der . Collect ion classes su ppor t polym or ph ism t h r ou gh class h ier ar ch y t h er efor e t h e d_List m ay con tain elem en t s of t h e su bclasses of Even t , n am ely deposit Even t an d wit h dr awEven t . Replace t h e ar r ay of Per son by a r elation sh ip of t ype d_Set t o m ain t ain r efer en t ial in t egr it y wit h Per son an d ch an ge it s in ver se lin k , accou n t s in t h e Per son class, to a r elation sh ip of t h e t ype d_List . M ak e th e followin g ch an ges t o t h e declar at ion of t h e even ts_com plet ed, own er s in t h e Accou n t class an d accou n t s in t h e Per son class.

44


Replace arrays by collection classes

• account.hxx file In t h e accou n t class declar ation in t h e file accou n t .h xx delet e or com m en t ou t th e followin g lin es: // Original Version Person* owners[CUSTOMERS_PER_ACCOUNT]; ... Event *events_completed[MAX_EVENTS]; Add or u n -com m en t th e followin g lin es in th eir place: // ODMG Collection Class Replacement d_Set owners inverse accounts; ... d_List< d_Ref > events_completed; In t h e Per son class declar at ion delet e or com m en t ou t th e followin g lin es: // Original Version Account* accounts[ACCOUNTS_PER_CUST] Add or u n -com m en t t h e followin g lin es in t h eir place: // ODMG Collection Class Replacement d_List accounts inverse owners You also n eed t o ch an ge th e way t h e even t s_com plet ed an d t h e own er s ar e u sed. St op th e even t s_com plet ed an d own er s bein g in it ialized t o NULL in bot h t h e Accou n t con st r u ct or s an d add t h e in itializer for th e r elat ion sh ip.

• account.cxx file In t h e con st r u ct or Accou n t ::Accou n t in t h e file accou n t .cxx delet e or com m en t ou t th e followin g lin es // Original Version int i; for (i=0;iaccounts[i]) { an d u n -com m en t or add t h e followin g lin es: // ODMG Collection Class Version int nb = customer->accounts.cardinality(); while (i < nb && customer-accounts[i]) {

48


Build and Run the Application

2.11 Build and Run the Application Now you h ave por t ed t h e au t om at ed t eller m ach in e applicat ion t o u se ODMG collect ion classes. Th e n ext st ep is t o com pile an d lin k th e m odified applicat ion . Ru n t h e followin g com m an d t o com pile an d lin k t h e applicat ion : On Un ix, > make On Win dows NT, > nmake If n ecessar y, cor r ect an y t ypin g er r or s you m igh t h ave m ade t h at cau se syn t ax er r or s an d r epeat t h e m ak e. Now r u n t h e application , u sin g t h e in it ialize option t o r er ead t h e dat a fr om t h e files. You n eed t o r ein it ialize t h e dat abase becau se you m odified t h e sch em a wh en you added th e collect ion classes. > bank -initialize En t er t h e Accou n t n u m ber 11111 at t h e pr om pt an d pr ess en t er . Th e followin g will be displayed. Welcome to the Bank of O2 Enter Account Number, 0 to exit > 11111 At t h e per son al ID pr om pt en t er t h e n u m ber 9999 an d pr ess en t er . Enter PIN Number > 9999 You ar e n ow logged in to t h e syst em so you can car r y ou t tr an sact ion s wit h t h e accou n t s available. To exit t h e pr ogr am en t er 0 at t h e accou n t n u m ber pr om pt .


49

2

50



33

OQL

Th is ch apt er descr ibes OQL. It con tain s th e followin g sect ion s: • Th e O2 OD MG Object Qu er y Lan gu age • Em beddin g OQL in C++ • Bu ild an d Ru n t h e Applicat ion


51

3

OQL

3.1 The O2 ODMG Object Query Language OD MG-93 in t r odu ces an object qu er y lan gu age (OQL). OQL is an SQLst yle lan gu age t h at allows for easy access t o object s. Sim ilar in u se t o SQL, OQL is an essen t ial t ool for developin g dat abase applicat ion s.

• Query optimization Th e syst em opt im izes you r qu er ies. Tr ied an d t est ed opt im izat ion t ech n iqu es ar e u sed t o evalu at e an OQL qu er y. For exam ple, OQL u ses appr opr iat e in dexes to r edu ce t h e am ou n t of data t o be filter ed. It fact or izes com m on su b-expr ession s, discover s wh ich expr ession s can be com pu t ed on ce ou t side an it er at ion , an d m ak es select ion s befor e st ar t in g an in n er it er at ion .

• Logical and physical independence OQL differ s fr om st an dar d pr ogr am m in g lan gu ages in t h at t h e execu t ion of an OQL qu er y can be im pr oved dr am at ically wit h ou t m odifyin g t h e qu er y it self. Th is is don e by declar in g n ew ph ysical dat a st r u ct u r es or n ew in dexin g or clu st er in g st r at egies. Th is r edu ces r espon se t im e. Th is sor t of m odificat ion in a pu r ely im per at ive lan gu age lik e C++ r equ ir es t h at an algor it h m be com pletely r ewr itt en , as it m ak es u se of ph ysical st r u ct u r es.

Interactive ad hoc queries A dat abase u ser can n ot be ask ed t o wr it e, com pile, lin k , edit an d debu g a C++ pr ogr am to m ak e sim ple qu er ies. OQL can be u sed dir ect ly as a st an d-alon e qu er y in t er pr et er . Its syn t ax is sim ple an d flexible. For som eon e fam iliar with SQL, OQL can be lear n ed in a sh or t t im e. Som e exam ples ar e given t o dem on st r at e th e m ost u sefu l feat u r es of OQL. You can execu t e t h em as ad h oc qu er ies with o2dsa. Fir st st ar t th e o2dsa in t er pr et er : > o2dsa_shell Now set th e base an d pu t th e in t er pr et er in to qu er y m ode set base bankBase ^D query ^D 52


The O2 ODMG Object Query Language

You can type th e qu er ies in t o t h e In pu t win dow an d t h en execu t e th em by t ypin g a n ew lin e followed by ct r l D .

Accessing data D at a is accessed in t h e dat abase t h r ou gh a n am ed object. All qu er ies st ar t fr om a n am ed object an d n avigat e t h r ou gh poin t er s to r each r elevan t dat a. To do t h is in OQL u se “.” or “->”. Th ese allow you t o en ter com plex object s, as well as t o follow sim ple r elat ion sh ip pat h s. For in st an ce, if you n eed t o k n ow t h e n am e of t h e st r eet t h at an ATM m ach in e is on , th e qu er y is as follows: ATM_MACHINE.location.street ^D Th is qu er y st ar t s fr om an ATM object , t r aver ses an Addr ess object an d en t er s t h e addr ess object t o get t h e n am e of t h e st r eet . Th is exam ple tr eated a on e-t o-on e r elat ion sh ip. Let u s look at m u lt iple r elat ion sh ips. Assu m e we wan t to r et r ieve t h e accou n t n u m ber s. We can n ot wr it e ATM_MACH INE.accou n ts_list.n u m ber becau se accou n t s_list is a set of r efer en ces. Th e r esu lt sh ou ld be a collect ion of n u m ber s bu t we n eed an u n am bigu ou s for m of n ot at ion to t r aver se t h is m u lt iple r elat ion sh ip. We can u se t h e select-fr om -wh er e clau se t o h an dle collect ion s ju st as in SQL. select a.number from a in ATM_MACHINE.accounts_list ^D Now you can n avigat e fr om on e object t o an y ot h er object followin g an y r elat ion sh ip pat h an d en t er t h eir com plex su bvalu es.

Selecting data OQL su ppor t s a wh er e clau se t o select dat a wh ich m at ch es t h e pr edicat e of t h e clau se. For in st an ce, let u s su ppose t h at we wan t t o r est r ict t h e pr eviou s sear ch t o t h ose accou n t s with a balan ce gr eat er t h an zer o. select a.number from a in ATM_MACHINE.accounts_list where a.balance > 0 ^D

• Join


53

3

OQL

In t h e fr om clau se, collect ion s t h at ar e n ot dir ect ly r elated can also be declar ed. As in SQL, t h is allows you to com pu t e j oi n s bet ween t h ese collect ion s. For in st an ce, t o iden t ify cu st om er s wh ose PIN n u m ber is t h e sam e as t h eir accou n t n u m ber execu t e th e followin g qu er y. select a from a in ATM_MACHINE.accounts_list, p in (select distinct b from c in ATM_MACHINE.accounts_list, b in c->owners) where a.number = 10000 + p.personal_id / 9 ^D

Manipulating complex values A m ajor differ en ce bet ween OQL an d SQL is th at an object qu er y lan gu age m ay m an ipu lat e com plex valu es. OQL can cr eat e com plex valu es as a fin al r esu lt , or du r in g t h e qu er y as an in t er m ediat e r esu lt . To bu ild a com plex valu e, OQL u ses th e con st r u ct or s st r u ct , set , bag, list , an d ar r ay. For exam ple, t o obt ain t h e accou n t n u m ber an d balan ce for ever y accou n t , execu t e t h e followin g qu er y: select struct(num: a.number, bal: a.balance) from a in ATM_MACHINE.accounts_list ^D OQL can also cr eat e com plex object s. For th is pu r pose, it u ses t h e n am e of a class as a con st r u ct or . At tr ibu t es of t h e object of t h is class can be in itialized explicit ly by an y valid expr ession .

Manipulating polymorphic collections A m ajor con t r ibu t ion of object or ien tation is th at it allows you t o m an ipu lat e polym or ph ic collect ion s. An oth er is th e abilit y t o car r y ou t gen er ic act ion s on t h e elem en ts of t h ese collect ion s. Th is is m ade possible by a lat e bin din g m ech an ism , For in st an ce, t h e even ts_com plet ed list is a polym or ph ic list sin ce it con tain s object s of t h e deposit Even t an d wit h dr awEven t classes. Wh en a polym or ph ic collection is filt er ed it s elem en t s ar e k n own t o be of t h at class. Th is m ean s th at pr oper t ies of a su bclass (at t r ibu t e or m et h od) can n ot be applied t o su ch an elem en t , except in t wo im por t an t cases: lat e bin din g t o a m et h od, or explicit class in dicat ion (cast ). Th e OQL lan gu age su ppor t s bot h lat e bin din g of m et h ods an d explicit cast in g.

54


The O2 ODMG Object Query Language

• High level constructs OQL, lik e SQL, pr ovides h igh -level oper at or s t h at allow you t o sor t, gr ou p, or aggr egat e object s or t o gath er st at ist ics, all of wh ich wou ld r equ ir e con sider ably m or e pr ogr am m in g in C++.

Composing operators OQL is a pu r ely fu n ct ion al lan gu age: all oper at or s can be com posed fr eely as lon g as t h e t ype syst em is r espect ed. Th e oper at or s offer ed in OQL in clu de t h e set oper ator s (u n ion , in t er sect , except), th e u n iver sal oper ator (for all) an d t h e exist en t ial qu an t ifier s (exist s), t h e sor t an d gr ou p by oper at or s an d t h e aggr egat e oper at or s (cou n t , su m , m in , m ax an d aver age). Now exit t h e qu er y in t er pr et er by execu t in g t h e followin g com m an ds: quit ^D Now exit t h e o2dsa_sh ell pr ogr am by execu t in g th e followin g com m an ds: quit ^D


55

3

OQL

3.2 Embedding OQL in C++ Em bedded in a C++ pr ogr am , OQL r edu ces pr ogr am wr it in g. OQL is power fu l en ou gh t o con t ain a lon g C++ pr ogr am in on e st at em en t . It can also im pr ove t h e per for m an ce of an applicat ion becau se th e qu er y lan gu age is opt im ized. As OQL r espect s t h e ODMG m odel, it h as t h e sam e t ype syst em as C++ an d can qu er y object s an d collection s com pu t ed by C++ an d passed on t o OQL as par am et er s. OQL t h en deliver s a r esu lt , wh ich is pu t dir ect ly in t o C++ var iables wit h n o con ver sion . Th is solves im pedan ce m ism at ch pr oblem s t h at m ak e em bedded SQL m or e difficu lt t o u se. To in vok e a qu er y in C++ u se t h e followin g fu n ct ion : int d_oql_execute(d_OQL_Query &q, T &result) d_oql_execu t e t ak es a qu er y in t h e d_OQL_Qu er y par am et er , par ses an d evalu ates t h e qu er y at r u n t im e an d r et u r n s t h e r esu lt . To con st r u ct a qu er y you cr eat e an in st an ce of t h e d_OQL_Qu er y class an d in it ialize it wit h a ch ar act er st r in g con t ain in g t h e qu er y. In t h e qu er y con str u ction , you can give par am et er s in t h e for m of $1, $2, et c. Aft er cr eat in g t h e qu er y you associat e ar gu m en t s to t h ese par am et er s u sin g t h e getNumber = account_number

56


Embedding OQL in C++

To r eplace t h e exist in g C++ code wit h a qu er y m ak e t h e followin g ch an ges. In t h e m et h od ATM ::look u pAccou n t in th e file at m .cxx r em ove or com m en t ou t th e followin g lin es: // ODMG Collection Class Replacement d_Ref search_account; d_Iterator< d_Ref > iterator = accounts_list.create_iterator(); while ( iterator.next(search_account) ) { if (search_account->getNumber() == account_number) { target_account = search_account; break; } } Add or u n -com m en t th e followin g lin es in th eir place: // OQL Query Replacement d_OQL_Query query (“element(select x from x in $1 where x->getNumber = $2)”); query nmake If n ecessar y, cor r ect an y t ypin g er r or s you m igh t h ave m ade t h at cau se syn t ax er r or s an d r epeat t h e m ak e. Now r u n th e applicat ion . > odmg -tutorial En ter t h e Accou n t n u m ber 11111 at t h e pr om pt an d pr ess en t er . Th e followin g will be displayed. Welcome to the Bank of O2 Enter Account Number, 0 to exit > 11111 At th e per son al ID pr om pt en ter t h e n u m ber 9999 an d pr ess en t er . Enter PIN Number > 9999 You ar e n ow logged in t o t h e syst em so you can car r y ou t t r an sact ion s wit h t h e accou n t s available. To exit t h e pr ogr am en ter 0 at t h e accou n t n u m ber pr om pt . Th is is t h e en d of t h e O 2 ODMG C++ t u t or ial. You n ow k n ow h ow t o por t applicat ion s t o O2 an d can in t egr at e you r C++ pr ogr am in t h e O2 dat abase syst em , for bet ter an d m or e efficien t dat a m an agem en t .

58


O2 ODMG Database System Tutorial

O2 ODMG Database System Tutorial

Suggest Documents

Database Management System [DBMS] Tutorial

Schema and Database Evolution in the O2 Object Database System

Tutorial Spatial Database Systems

VBScript Database Tutorial Part 1

Microsoft Excel Database Functions Tutorial

Database Using Python: A Tutorial

Database Servers Tutorial - Communities - ArcGIS

Tutorial: Database Communication in LabVIEW

Towards a formal type system for ODMG OQL - CiteSeerX

Visual system tutorial

Electronic Keyboard Tutorial System

Tutorial Database Testing using SQL - Ning

Tutorial Aplikasi Database Matakuliah Berbasis Java Swing ...

Backtrack Oracle Tutorial - Backtrack & Oracle - Red-Database

Pemrograman Berorientasi Aspek Tutorial Koneksi Database ...

visual basic database tutorial pdf - Google Drive

oracle database tutorial pdf - Google Drive

Tutorial: Event Processing Using Database ... - Caltech Authors

Database tutorial in Access 2012 - Peter Aldhous

Tutorial Database Testing using SQL.pdf - Google Drive

tutorial database mysql pdf - Google Drive

Tutorial: Creating a Database Application using Delphi

Effect of O2 , H2 +O2 , and N2 +O2 ion-beam

Database System Development Lifecycle 4. Database design