ODMG C++ Binding Guide

Transcription

1 ODMG C++ Binding Guide Release August 1998

2 All rights to this publication are reserved. No part of this document may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language, in any form or by any means, without prior written permission from Ardent Software, Inc. If you are a licensed user of this product, Ardent Software, Inc. grants you a limited, nontransferable license to reproduce this particular document. This is limited to photocopy reproduction of a Ardent Software-supplied master copy. Copies must include all pages contained in the master copy (including this page) and m u st be int en ded str ict ly for int er n al dist r ibu t ion an d u se by t h e licen see, its employees, and assigns. Reprodu ced copies m ay not be tr ansfer red, in whole or in par t, to an y par t y ou tside t h e licen see s place(s) of business. Th e software described in this document is furnished under a license agreement. The software may be used or copied only in accordance with the terms of the agreement. It is against the law to copy this software on magnetic tape, disk, or an y ot h er m ediu m for an y pu rpose oth er th an t h e licen see's person al u se. Copyright Ardent Software, Inc. All Rights Reserved O 2 Release 5.0 Documentation Part # DO Ardent Software, Inc., reserves the right to make changes to this document and the software described herein at any time and without notice. Ardent Software, Inc. makes no warranty, express or implied, other than those contained in the terms and conditions of sale, and in no case is Ardent Software, Inc. liable for more than the license fee or purchase price of this product. Ardent Software, Inc. 50 Washington Street Westboro, Massachusetts USA Telephone: (508) Facsimile: (508) World Wide Web: O 2, O 2 Engine API, O 2 C, O 2 DBAccess, O 2 Engine, O 2 Graph, O 2 Kit, O 2 Look, O 2 Store, O 2 Tools, and O 2 Web are r egistered tradem ar k s of Ardent Softwar e, Inc. SQL and AIX are registered trademarks of International Business Machines Corporation. Sun, Su nos, and SOLARI S are registered trademarks of Sun Microsystems, Inc. X Window System is a registered trademark of Massachusetts Institute of Technology. Unix is a registered t r adem ark of Unix Syst em Laborator ies, Inc. HPUX i s a regist er ed t radem ar k of Hewlett -Pack ar d Com pany. BOSX is a registered trademar k of Bu ll S. A. IRIX is a registered trademark of Siemens Nixdorf, A. G. NeXTStep is a r egistered tr adem ar k of NeXT Com pu t er, In c. Pu r ify, Qu an t ify ar e r egist er ed t r adem ark s of Rat ion al Softwar e In c. Windows is a r egist er ed t r adem ark of Micr osoft Corporation. Ot h er t radem ar k s an d r egist er ed tr adem ark s ar e t h e property of the respective trademark holders.

3 Who should read this manual This manual is for programmers who wish to write or adapt C++ applications for the O 2 system. It presents the basic concepts of the O 2 ODMG C++ interface and describes how to import and export classes and how to program using the interface. It details the development environment including the Makefile generator. The manual also describes persistent pointers, generic collections, generic methods, and how to use OQL and O 2 Look with C++. A programming example is presented. This manual should be used in conjunction with the ODMG C++ Reference Manual which contains the complete list of O 2 C++ interface options. ODMG C++ Binding Reference Manual This manual contains a comprehensive list of all O 2 commands and C++ binding classes. The full syntax and all options are detailed for each method. This manual should be used in conjunction with the ODMG C++ Binding Guide. Other documents available are outlined, click below. See O2 Documentation set.

4

5 TABLE OF CONTENTS This manual is divided into the following chapters: 1 - Introduction 2 - Importing C++ Classes 3 - Exporting O 2 Classes 4 - Development Environment 5 - Programming Guidelines 6 - Persistent Object Hierarchy 7 - Collections 8 - Database Operations 9 - Utility Classes 10 - Example C++ Applications ODMG C++ Binding Guide 5

6 TABLE OF CONTENTS 1 Introduction System Overview Features and Advantages O2 and C Development...19 Programming Manual Overview Importing C++ Classes Getting started...28 Creating a schema for C++ objects...29 How to proceed? The O2 import tool...31 Example...32 Submitting files...34 Generated file...35 Using an external C++ library...36 o2cpp_import options...38 Translating C++ members...41 Importing member functions...42 Importing a class containing an object of another class...43 Importing a template class...44 Importing a template class as a member of an imported class...45 Importing a subclass of a template class...46 Relationship declarations...47 Relationship template class definitions Programmed mapping...56 Mapping a C++ class to a persistent structure...56 Copying attributes...58 Copying relationships...60 More elaborated conversions...62 How to invoke programmed mapping The O2 unimport tool ODMG C++ Binding Guide

7 TABLE OF CONTENTS 2.5 O2 named objects Confirming schema updates Exporting O2 Classes Exporting O2 classes Example o2cpp_export options Generated files Exporting O2C methods The O2 unexport tool Example Exporting with the O2 Command Development Environment Compiling and Linking C++ Sparc compiler Configuration File Syntax Contents Example Creating a Makefile Compilation Link edition Programming Guidelines Introduction Structure of an Application Creating Persistent Objects Persistence by attachment Direct persistence Direct persistence on a volume ODMG C++ Binding Guide 7

8 TABLE OF CONTENTS Direct persistence by proximity Transactions and persistent objects Persistent Pointers Persistent pointer definition Persistent pointer class Constructors and access mode Constructor and persistent root Pointer and persistent pointer New and destroy operators Casting Object locking Accessing Persistent Objects Memory Management Default memory manager Activate and deactivate Dynamically allocated data members Restriction about a destructor of a persistent capable class Customizing the memory manager Reference cycle Transaction Management Optimizing your transactions Nested Transactions Temporary Attributes in Persistent Objects Initializing temporary attributes Controlling the de-allocation of an object Multi-base Multi-base and Multi-schema A typical configuration Context switching Changing the context Restoring the context Organization of C++ modules Include Files you must use ODMG C++ Binding Guide

9 TABLE OF CONTENTS 5.12 Environment Variables o2ccnumber o2cccheck Adapting an Existing C++ Application C++ and the O 2 Engine API Troubleshooting ODMG C++ Applications O2 C++ runtime warnings O2 C++ runtime errors Other C++ runtime errors Persistent Object Hierarchy Introduction Inherited methods Collections Introduction Declaring collection variables Declaration failure Collection iterator Collection class Set Class Bag class List class Varray class Array class Database Operations Introduction Session class Beginning a session ODMG C++ Binding Guide 9

10 TABLE OF CONTENTS Using the O2 option mechanism Customizing the options Closing a session Ending a session Setting the session parameters Database class Creating a database Deleting a database Opening a database Closing a database Garbaging a database Setting an object name Getting an object name Renaming an object Accessing an object Creating a persistent root Deleting a persistent root Extending a database Getting the volume descriptor Setting the default volume Getting the default volume Transaction class Starting a transaction Read-only transactions Update transactions Committing a transaction Validating a transaction Aborting a transaction Checkpointing a transaction Promoting clusters in transaction O2 exceptions Wait and Deadlock Using OQL in C Query construction Query result Type checking Access mode ODMG C++ Binding Guide

11 TABLE OF CONTENTS d_oql_query class Using O2 Look in C O2 Look C++ functions Generic O2Look methods External Object Identifier Utility Classes d_string class d_bits class d_bytes class d_date class d_time class d_timestamp class d_interval class An Example C++ Application Introduction Define the class Person in file Person.hxx Class implementation in Person.cc The application in the file main.cc Main program Compiling your application Create a schema with an o2dsa_shell command Create a configuration file Generate a makefile Import the C++ classes Create persistent roots Create a database Create index if necessary with an o2dsa_shell command ODMG C++ Binding Guide 11

12 TABLE OF CONTENTS Compile Run the application INDEX ODMG C++ Binding Guide

13 1 Introduction 1 GENERAL OVERVIEW OF THE O 2 ODMG C++ INTERFACE Congr atu lations! You are now a u ser of the O 2 ODMG C++ interface! You will find that developing O 2 applications in C++ has several key advantages: transparent management of C++ objects, conformance to C++ standards, reuse your existing C++ applications, extended C++ libraries and access to all O 2 tools including the OQL query language, O 2 Look graphical interface generator and O 2 Tools. This chapter introduces the O 2 ODMG interface to C++ and is divided into the following sections: Syst em Over view Features and Advantages O2 and C++ Manual Overview Important The interface described in this manual totally conforms to the ODMG-93 standard 1. The main aim of the ODMG (Object Database Management Group) is to propose a set of standards enabling programmers to write portable applications that can be run on different ODBMS products. 1. The Object Database Standard: ODMG Atwood, Duhl, Ferran, Loomis and Wade. Edited by R.G.G. Cattell Morgan Kaufman Publishers. ODMG C++ Binding Guide 13

14 1 Introduction 1.1 System Overview The system architecture of O 2 is illustrated in Figure 1.1. Development Tools External Interfaces O 2 Dev. Tools Standard Dev. Tools OQL O 2 ODBC C C++ O 2 C Java O 2 CORBA Database Engine O 2 Engine O 2 DB Access O 2 Store O 2 Web Figure 1.1: O 2 System Archi tectur e The O 2 system can be viewed as consisting of three components. The Database Engine provides all the features of a Database system and an object-oriented system. This engine is accessed with Development Tools, such as various programming languages, O 2 development tools and any standard development tool. Numerous External Interfaces are provided. All encompassing, O 2 is a versatile, portable, distributed, highperformance dynamic object-oriented database system. Database Engine: O 2 Store The database management system provides low level facilities, through O 2 Store API, to access and manage a database: disk volumes, files, records, indices and transactions. O 2 En gine Th e object database en gine provides direct con t r ol of schemas, classes, objects and transactions, through O 2 Engine API. It provides full text indexing and search capabilities with O 2 Search and spatial indexing and retrieval capabilities with O 2 Spatial. It includes a Notification manager for informing other clients connected to the same O 2 server that an event has occurred, a Version manager for handling multiple object versions and a Replication API for synchronizing multiple copies of an O 2 system. 14 ODMG C++ Binding Guide

15 System Overview Programming Languages: O 2 objects may be created and managed using the following programming languages, utilizing all the features available with O 2 (persistence, collection management, transaction management, OQL qu er ies, et c.) C O 2 functions can be invoked by C programs. C++ ODMG compliant C++ binding. Java ODMG compliant Java binding. O 2 C A powerful and elegant object-oriented fourth generation language specialized for easy development of object database applications. OQL ODMG stan dard, easy-to-u se SQL-like object qu er y language with special features for dealing with complex O 2 objects and methods. O 2 Development Tools: O 2 Graph O 2 Look O 2 Kit O 2 Tools Create, modify and edit any type of object graph. Design and develop graphical user interfaces, provides interactive manipulation of complex and multimedia objects. Library of predefined classes and methods for faster development of user applications. Complete graphical programming environment to design and develop O 2 database applications. Standard Development Tools: All standard programming languages can be used with standard environments (e.g. Visual C++, Sun Sparcworks). External Interfaces: O 2 CORBA O 2 DBAccess Create an O 2 / Orbix server to access an O 2 database with CORBA. Connect O 2 applications to relational databases on remote hosts and invoke SQL statements. O 2 ODBC Connect remote ODBC client applications to O 2 databases. O 2 Web Create an O 2 World Wide Web server to access an O 2 database through the internet network. ODMG C++ Binding Guide 15

16 1 Introduction 1.2 Features and Advantages If you already have written applications in C++, you can integrate them into your object oriented database. O 2 has an easy-to-use interface to C++ enabling you to fully integrate your existing applications. You can also continue writing programs in C++ with all the added features integration to O 2 brings. Figure 1.2: A C++ application in O 2 In O 2, C++ applications are standard Unix or Windows programs which can read, modify and send messages to O 2 objects. These applications also use an O 2 database to make their objects persistent and they use O 2 system supplied generic methods, including the O 2 Look methods edit and display. They can also use OQL. 16 ODMG C++ Binding Guide

17 Features and Advantages O 2 enhances a standard C++ environment by providing new features for C++ programmers: Database system support All O 2 database features including class d_database used to create, open and delete a database and class d_transaction which provides a reliable environment for multi-user applications. Persistent pointers These allow you to access and manipulate persistent C++ objects stored in a database. For example, a persistent pointer to the class Person, is of the class d_ref<person>. Operators are the same as for standard C++ pointers and this minimizes changes required to existing C++ programs. Generic collections Th ese implem en t d_list, d_set, d_bag, d_varray and d_array. Th ese allow you to organize a database and to access large numbers of objects as though they were in memory. OQL You can query and browse your database using OQL as well as use it functionally as part of a C++ program. O 2 Look You can display and modify any O 2 object manipulated in C++ using O 2 Look. ODMG C++ Binding Guide 17

18 1 Introduction 1.3 O 2 and C++ An O 2 system is made up of a set of schemas and bases. The O 2 System Administration Guide outlines how to create and administer an O 2 system. It also gives more information on some of the concepts introduced here. You can define a schema as a set of C++ classes. You can then create a base and write C++ applications to populate it and share persistent objects in a multi-user environment. The C++ binding facility allows you to create and access persistent C++ objects as though they were in memory. You can logically organize a database by grouping C++ objects into generic collections. These are Set, List, Array and Bag. This allows you to store and manipulate large numbers of objects as though they were in memory. The database can be queried using OQL which has a seamless interface to C++. Without changing an existing application you can improve performance by using indexing and clustering techniques. The C++ inter face to O 2 is based on a set of twin classes, one class in O 2 and one in C++. A persistent C++ object is accessed in a totally transparent way through a special type of class in C++ called a persistent pointer. These classes are generated by O 2 when you import C++ classes to O 2 using the import tool or when you export O 2 classes to C++ u sing t h e expor t t ool. Figure 1.3 shows the class K in O 2 and its twin in C++. The persistent pointer class d_ref<k> manages the mapping between these twin classes transparently. C++ d_ref<k> class O 2 K class K class Figure 1.3: Link between C++ and O 2 18 ODMG C++ Binding Guide

19 O2 and C++ To program using persistent pointers, you generally change the declarations in your C++ programs from K*, wher e K is an imported C++ class or an exported O 2 class, to d_ref<k>. These changes are mandatory when specific O 2 oper at ion s are car ried ou t, for exam ple when accessing a named object or calling O 2 C methods. No other change is necessary as a C++ application running correctly on non-persistent classes works transparently. Persistent pointers are manipulated in exactly the same way as memory pointers. Development The following utilities and tools are provided to develop schemas and C++ applications: o2dsa_shell o2dsa_shell commands allow you to create schemas and administer an O 2 system. Before you define classes you must create a schema. You might use the following command: create schema Car_schema; You can then create bases in this schema with the following command, for exam ple: create base Car_base; The O 2 System Administration Reference Manual provides details of t h ese com m an ds. ODMG C++ Binding Guide 19

20 1 Introduction Import tool To import C++ classes to O 2 you use the o2cpp_import tool. For each imported C++ class, O 2 generates what is required to access C++ objects through the persistent pointer, d_ref<k>. It also generates the relevant files which contain the implementation of the new function members added to the imported C++ class. Each imported class becomes attached to the superclass o2_root, which is a subclass of d_object. It also generates a twin O 2 class which is the O 2 image of the C++ class. Export tool To export O 2 classes to C++, you use the o2cpp_export tool. For each expor t ed class, o2cpp_export generates the relevant files that contain the definition of the generated C++ class and the implementation of the new function members inherited from o2_root. Runtime libraries To build the final O 2 C++ application, the C++ interface has runtime libraries which provide the interface between O 2 and C++. These libraries ensure that objects representing the same entity in O 2 and C++ are consistent. Development environment You must compile the O 2 C++ application using a standard C++ compiler and link all the files produced by the import and export tools, the application files and the runtime library of C++ functions. You can u se o2makegen, which automatically builds Makefiles. The generated Makefiles have two functions: Importing and exporting C++ classes. Building the C++ executable from C++ files. Figure 1.4 shows the way a C++ application is developed to run with O ODMG C++ Binding Guide

21 O2 and C++ C++ class definitions O 2 class definitions Import Export C++ files generated by O 2 Application files O 2 runtime libraries C++ compiler and link editor O 2 - C++ application Figure 1.4: The C++ interface to O 2 ODMG C++ Binding Guide 21

22 1 Introduction Programming O 2 provides a class library which you can use to create classes and to manipulate persistent and transient objects and collections. Collections The collections d_set<t>, d_bag<t>, d_list<t>, d_varray<t>, d_array<t> and d_string allow you to design complex objects. For exam ple: class Car { d_list<sale*> sales; Manufacturer* man; d_string name; d_array<d_date> versions; }; Connection to an O 2 database The d_session and d_database classes allow you to connect a C++ program to O 2 and open a base to run an application. For exam ple: d_session connect; d_database base;... connect.set_default_env (); connect.begin(argc,argv); base.open("car_base"); //a C++ application... base.close(); connect.end(); 22 ODMG C++ Binding Guide

23 O2 and C++ Transactions To update persistent objects you must start a transaction. The d_transaction class provides all t h e pr opert ies of dat abase transactions, atomicity of operations up to commit point, isolation from concurrent transactions, rollback and recovery operations. O 2 provides transaction management which is XA compliant. For example: d_transaction create_cars; create_cars.begin(); d_ref<car> a_car; //create a named persistent set of cars base.create_persistent_root("all_cars", "d_set<d_ref<car>>"); d_set<d_ref<car> > all_cars("all_cars"); //create a Car and store it in the set a_car=new Car("Twingo"); all_cars.insert_element(a_car); //commit the transaction create_cars.commit(); Object manipulation Objects and collections are accessed as though they were in memory. O 2 transparently manages objects as it reads them from disk via the server. Once an object is loaded to memory it is accessed without added processing cost. Programming with persistent objects and collections is the same as with standard C++ objects. You can avoid a lot of programming by invoking OQL and using ODMG collections. ODMG C++ Binding Guide 23

24 1 Introduction For exam ple: d_ref<car> a_car; d_set<d_ref<car> > all.cars("all_cars"); a_car=all_cars.select_element("this.name=\"twingo"\"); a_car->man->print(); a_car->sales.insert_element(new Sale); ODMG C++ Binding Guide

25 Manual Overview 1.4 Manual Overview This manual is divided into the following chapters: Chapter 1 - Introduction In t r oduces t h e C++ interface to O 2 and outlines some of its advantages. Chapter 2 - Importing C++ Classes Describes how to import C++ class definitions using the import tool. Chapter 3 - Exporting O 2 Classes Describes how to export O 2 class definitions using the export tool. Chapter 4 - Development Environment Describes the development environment including the Makefile generator and configuration file. Chapter 5 - Programming Guidelines Provides guidelines on programming with the interface including managing persistent pointers, memory management, using several bases and several schemas and adapting an existing C++ application. Chapter 6 - Persistent Object Hierarchy Describes the hierarchy of persistent objects and methods which are automatically inherited. Chapter 7 - Collections Describes C++ collections provided by O 2. It describes how to declare collection variables and gives details of the collection, set, bag, list, varray and array classes. Chapter 8 - Database Operations Describes database operations. It describes the session, database and transaction classes. It also discusses O 2 exception handling, environment variables and using OQL and O 2 Look. ODMG C++ Binding Guide 25

26 1 Introduction Chapter 9 - Time and String Classes This section gives the definitions of classes which relate to time and also the definition of a string class. Chapter 10 - An example C++ Application An example is provided in this chapter. 26 ODMG C++ Binding Guide

27 2 Importing C++ Classes 2 This chapter describes how to use the import tools in the C++ interface to O 2. It contains the following sections: Getting started The O2 import tool The O2 unimport tool O2 named objects Confirming schema updates ODMG C++ Binding Guide 27

28 2 Importing C++ Classes 2.1 Getting started To invoke the import tool at operating system level, use the o2cpp_import command. Importing C++ classes in order to store and retrieve C++ objects using the O 2 Database is shown in Figure 2.1. C++ class definitions o2cpp_import C++ files generated by O Figure 2.1: O 2 Impor t Tool To begin work ing with O 2, you must first create a schem a. You then populate this schema with classes. You define these classes using the standard C++ programming language. You must use the import tool to make these classes accessible to O 2. To simplify your task, O 2 also provides an automatic Makefile generator, o2makegen. If you choose to use o2makegen, you define the parameters in a simple and platform independent configuration file. Using the Makefile generator is described in Section ODMG C++ Binding Guide

29 Getting started Creating a schema for C++ objects Before starting to import or export classes, you must create the schema in which you want to work and to receive the C++ classes. To create a new schema, type the following o2dsa_shell command: create schema schema_name; giving the name of the schema you wish to create. You can then start importing classes. Information on o2dsa_shell commands is given in the O 2 System Administration Guide and the O 2 System Administration Reference Manual. How to proceed?.h files Before importing your classes, begin by putting those C++ classes for which you want persistent instances in one or more.h files. You can adapt the definition of these classes using O 2 collections as members or member parameters (d_set, d_bag, d_list, d_varray, d_string, etc.) Import Now you can make the C++ classes known to O 2 using the o2cpp_import command. The C++ classes are then updated by o2cpp_import. Unless you use the nomodification option, the C++ class members are automatically adapted by changing a pointer of an imported class into a persistent pointer. This allows persistent references between persistent objects. Do not forget to import generic collections if you use them. Create names You do not need to import or export O 2 names explicitly. However, you must create these names in the relevant schema to be able to give names to your C++ persistent roots which can be objects or collections. ODMG C++ Binding Guide 29

30 2 Importing C++ Classes Compile the application You can now compile your application. The o2makegen tool builds the makefile for you. Modifications If you carry out modifications in a class simply redo make. O 2 automatically manages incremental changes in the schema. 30 ODMG C++ Binding Guide

31 The O2 import tool 2.2 The O 2 import tool The O 2 import tool processes the source code of C++ classes and outputs modifications to the imported classes. Each imported class becomes attached to the superclass o2_root. It also generates one C++ file per class which contains the implem en tation of th e n ew fu n ction m em ber s added t o t h e impor t ed class. If you import a class that has already been imported, modifications are carried out incrementally. You do not need to destroy files or classes to re-import a class. Before using the import tool ensure that an O 2 server is running for the system where t h e schem a h as been cr eated. See t h e O 2 System Administration Guide and the O 2 System Administration Reference Manual for details of the o2server command. Figure 2.2 shows how classes are imported using o2cpp_import. See the ODMG C++ Binding Reference Manual for full details. Class Person C++ class definitions in "Person.hxx" O 2 Schema o 2 import tool O 2 classes created/modified C++ files generated by O 2 Modified "Person.hxx" Person_code.cc Figure 2.2: Importing C++ class definitions and generating files. If the C++ class definition of Person is in the file Person.hxx, the file Person_code.cc is generated and the file Person.hxx is modified. ODMG C++ Binding Guide 31

32 2 Importing C++ Classes Example Let us suppose that in your C++ application you want to make persistent C++ objects of the class Person. To do this you must import the class Person, i.e. call the Import tool. The file Person.hxx contains the C++ definition of the class Person: class Person { private: char* name; int age; public: Person (); ~Person (); }; This definition characterizes the objects of the class Person as having a field name of type char* and a field age of type int. There are two member functions: Person () is the class constructor and ~Person () the class destructor. To import the class Person, type the following command: o2cpp_import -system system_name -server machine_name -schema schema_name -class Person Person.hxx Th e import tool t h en au tom atically m odifies t h e file Person.hxx, which contains the class definition shown below. The class Person is now inherited from the superclass o2_root as shown below. 32 ODMG C++ Binding Guide

33 The O2 import tool The class below is patched, i.e. it includes the original definition and the modified definition: #ifndef ODMG_93 class Person { private: char* name; int age; public: Original definition of the Person (); class Person ~Person (); }; #else //patch of class Person #include "o2_root_defs.hxx" class Person: public virtual o2_root { private: char* name; int age; public: Modified definition of the Person (); class Person ~Person (); protected: virtual void o2_new(); virtual void o2_read(); virtual void o2_release(); virtual int o2_diff(); virtual void o2_write(); virtual int o2_write_if_diff(); public: Person(o2_Shadow shad,handle hd); }; #endif //end of patch of class Person The im plementation of the associated member fu nctions, for exam ple, o2_new, o2_read, etc. is in Person_code.cc. These are inter nal O 2 functions. In the O 2 schema, the class Person becomes visible when the class Person is imported. ODMG C++ Binding Guide 33

34 2 Importing C++ Classes Important Carry out modifications in the original part of the definition and not in the patched part. Do not modify the patch comment itself. Any modified file used with the C++ interface to O 2 must be compiled using flag: ODMG_93. Submitting files Before beginning to import, you must declare your classes. The file that you are going to submit to the import tool must respect the three rules shown below. Rule 1 The file you import must be compilable in C++ or self-cont ained. For exam ple: #include "Q.hxx" class K:public Q{ int x; }; or #include "Q.hxx" class K { Q x; }; or 34 ODMG C++ Binding Guide

35 The O2 import tool class Q; class K { Q*x; }; Rule 2 The superclass declarations of an imported class K must be known to the file that contains the definition of the class K. For example: #include "Q.hxx" class K:public Q{ int x; }; Rule 3 If the class definition to be imported has an attribute which is an instance of a second imported class, then this second imported class must be known to the file given as input to o2cpp_import. #include "Q.hxx" class K { Q x; }; Generated file For each imported class, Class_name, one file is generated: Class_name_code.cc ODMG C++ Binding Guide 35

36 2 Importing C++ Classes This file contains the implementation of the new function members inherited from o2_root that are added to the C++ class. o2cpp_import -system system_name -server machine_name -schema schema_name -class Class_name File_name C++ file generated by O 2 Class_name_code.cc Figure 2.3: Generated file The file File_name is modified and you must use it as the new declaration of the class Class_name. If you do not change directories, then the original File_name is modified by default. Using an external C++ library You can make persistent instances of a class which belongs to an external C++ library. To do this, you must first create a subclass of the library class. You must also use the -library option in the o2cpp_import command to import the subclass. For example 1. Assuming that a class K is defined in the library file K.hxx, create a subclass SK of class K in your file SK.hxx as follows: #include "K.hxx" class SK: public K{... }; 36 ODMG C++ Binding Guide

37 The O2 import tool 2. Call o2cpp_import as follows: o2cpp_import... -class SK -library K SK.hxx The class K of the external library is not patched. Important You can only make persistent the protected and public members of the library class. The library class must have a default constructor. ODMG C++ Binding Guide 37

38 2 Importing C++ Classes o2cpp_import options The o2cpp_import command has a number of options. Several import commands can apply to a group of classes but you must respect their inheritance hierarchy. class To import a class you must give its name and you must respect the class hierarchy by always specifying a class before any of its subclasses. mf Use this option to import a public member function which can then be used with OQL and O 2 Look. For exam ple, o2cpp_import -system system_name -server machine_name -schema schema_name -class "Person -mf get_age" Person.hxx publicmf Use this option to import all public member functions. accpm Use this option to generate the access method for members. downto When you import a class, you must import all its superclasses. You can do this using the downto option which allows you to import a class and all its superclasses. 38 ODMG C++ Binding Guide

39 The O2 import tool Care must be taken if one of the superclasses is in a separate include file. Such include files cannot be modified and you must specify a directory using the output option in which the include file is recopied and modified (i.e patched). confirmclasses This option enables you to automatically confirm classes after they are imported. output You use this option to specify the directory in which the generated C++ files are created. By default, the current directory is taken. forward If the class to be imported points to another class, you must either import both classes or use the forward option: class C{ C1 * x }; To import this class C, use the option -forward C1. This option takes the class C1 as being already imported when the main file is parsed. The pointer in class C is modified and becomes a persistent pointer. list, set, bag and varray You can import collection classes, instances of which are collections of objects or atomic types. To obtain all the operations for these collections, you must use the list, set, bag and varray options. ODMG C++ Binding Guide 39

40 2 Importing C++ Classes nomodification Th is option pr even t s t h e impor t ed class being m odified so th at it h as t h e same structure before and after import. If this option is not used, a pointer to another imported class, found in the definition being processed, is modified into a persistent pointer. use If the file is dependent on other files, you can specify them using an explicit #include. Other wise, u se the -use option to specify that another file must be parsed before the main file. library This option allows you to specify a class which belongs to an external C++ library that is used as a superclass of one (or more) of your imported classes. Table 2.1 shows the C++ types that you can import into O 2. Q is taken as any C++ type shown, and P its corresponding O 2 type. Table 2.1 Corresponding C++ and O 2 types for importing C++ type [unsigned] int [unsigned] short d_short d_ushort [unsigned] long d_long d_ulong enum float d_float double d_double [unsigned signed] char d_char d_octet d_boolean char * O 2 type integer integer integer integer real real char string char[int] string (card. int) 40 ODMG C++ Binding Guide

41 The O2 import tool Table 2.1 Corresponding C++ and O 2 types for importing C++ type d_string d_bytes O 2 type string o2_bytes K* (wher e K is a C++ class) K (an O 2 class) d_ref<k> d_ref_any K Object d_list<q> o2_list_p (a collection class) d_bag<q> o2_bag_p (a collection class) d_set<q> d_varray<q> o2_set_p (a collection class) o2_list_p d_array<q> list (P) (card. d_ar r ay::len ()) d_array<char> d_ref<d_list<q>> d_ref<d_bag<q>> d_ref<d_set<q>> Q [int][int]... struct { Q1 attr1;... Qn attrn;} bits o2_list_p (a collection class) o2_bag_p (a collection class) o2_set_p (a collection class) list(list...(p)...))(car d.int, int) tuple (attr1: P1,.. attrn: Pn) Important You cannot import a static member of a class. The following message may be displayed when importing classes: WARNING : The class K is undefined. This means that the imported class refers to a class K which is not yet known to O 2. This is not an error as K is imported later. Translating C++ members When the twin set of classes are being created, the import tool uses the following programming conventions in order to translate those C++ members whose type is a fixed size array: ODMG C++ Binding Guide 41

42 2 Importing C++ Classes Take the C++ class c: class c{ char a [10]; struct { int x; char *y; } b [20]; int c [10] [20]; }; The corresponding twin O 2 class is as follows: class c inherit Object public type tuple( a:o2list1_10_char, b:o2list1_20_tuple6ctupp6c1b, c:o2list1_10_20_integer) end; o2list1_10_char, o2list1_20_tuple6ctupp6c1b, and o2list1_10_20_integer are O 2 named types with the following definitions: type o2list1_10_char: string type o2list1_20_tuple6ctupp6c1b: list (tuple (x: integer, y: string)) type o2list1_10_20_integer: list (list (integer)) Importing member functions You can import C++ member functions if you wish to use them with OQL or O 2 Look. For exam ple, t h e following OQL qu ery lau n ch es a C++ m em ber fu n ct ion get_name which h as already been impor t ed: d_oql_query get_name ("element(select p from p in people where p.get_name = \"total\")"); See Section 8.6 for more details on using OQL in C++. The parameter types and the result type of the member function that you want to import are limited to those shown in Table 2.2. The corresponding O 2 types are also given. 42 ODMG C++ Binding Guide

43 The O2 import tool Table 2.2 Parameter and Result types C++ type [unsigned] int [unsigned] short [unsigned] long [unsigned signed] char enum float double char * d_string d_bytes char[int] O 2 type integer integer integer char integer integer real string o2_bytes string K* (C++ class) K (an O 2 class) d_ref<k> K (an O 2 class) d_list<q> d_bag<q> d_set<q> d_varray<q> o2_list_p o2_bag_p o2_set_p o2_list_p Importing a class containing an object of another class You can choose whether or not to import the class of an object member of the im por ted class. An example follows : ODMG C++ Binding Guide 43

44 2 Importing C++ Classes class A{ private : int i; public : int j; }; class C{ A a; }; If the class A is not imported, only public members of the class A will be impor ted (member A::j). If you want to make private members of the class A persistent, you have to import the class A with the -accpm option (this option allows you to generate access function members for private members). In this case the member A::i can be made persistent. If you do not want to generate access methods, the private members must be made public. Importing a template class A class template (e.g. template<class T> class Temp...) cannot be directly imported. Only a template class (i.e. an instantiation like Temp<int>) can be imported. Th er e ar e t wo ways t o import a tem plate class: As a member of an imported class. By importing a subclass of the template class. 44 ODMG C++ Binding Guide

45 The O2 import tool Importing a template class as a member of an imported class Example: template <class T> class Temp { public: int x; T y; }; class A{ public: int a; }; class B{... Temp<A> b; }; If you import the class B, the member b will be made persistent. The corresponding O 2 generated class will be as follows: class B type tuple(... b: tuple( x: integer, y: tuple(a: integer)) ) end; Warning! Suppose the class template Temp has a member of type T* (where T always matches a class). If you want to make this member persistent, you have to change the type of the member to d_ref<t>. ODMG C++ Binding Guide 45

46 2 Importing C++ Classes Example: template <class T> class Temp { public: int x; T y; T *z; }; must be changed to: template <class T> class Temp { public: int x; T y; d_ref<t> z; }; The O 2 generated class will be as follows : class B type tuple(... b: tuple(x: integer, y: tuple(a: integer), z: A) ) end; The class cannot be automatically modified to change the T* to a d_ref<t> because the o2cpp_import tool cannot import a class template. Importing a subclass of a template class To import a template class, you must create and import a subclass of the template class. Example: class B: public Temp<A> {... }; Only the class B must be imported. This is the only class which will be modified by the o2cpp_import tool. 46 ODMG C++ Binding Guide

47 The O2 import tool You can also make a subclass of a template class with multiple inheritance. Example: class B: public Temp<A>, public C {... }; In this case, the superclass C must be imported before the class B. Warning! Private members of the template class cannot be made persistent. Relationship declarations Relationships are defined between two objects and are used to transparently maintain referential integrity. A relationship is similar to an attribute, but it is followed by the keyword inverse and the name of the relationship traversal path in the class at the end of the relationship. The type of a relationship can be of type d_ref<t>, d_set<d_ref<t> > or d_list<d_ref<t> > wher e T is a persistent class. The cardinality of a relationship can be one-to-one, one-to-many, many-to-one or many-to-many. Example: class Person{ public : d_string name; Address address; Relationships d_ref<person> spouse inverse Person::spouse; one-to-one d_list<d_ref<person> > children inverse Person::parents; many-to-many d_ref<person> master inverse Person::disciples; one-to-many d_set<d_ref<person> > disciples inverse Person::master; many-to-one... }; ODMG C++ Binding Guide 47

48 2 Importing C++ Classes To illustrate the consequences of relationship assignments, let p1, p2 and p3 be three objects of the class Person. One-to-one relationship: p1.spouse = &p2 p1 spouse p2 spouse p1 p2 p1.spouse = &p3 spouse p3 spouse :assignment :automatic inverse assignment spouse 48 ODMG C++ Binding Guide

49 The O2 import tool Many-to-one relationship: p1.disciples.insert_element(&p2);p4.master=&p3; p1 p2 disciples master p3 p4 disciples master p1.disciples.insert_element(&p4); p1 p2 disciples master p4 p3 master disciples :assignment :automatic inverse assignment ODMG C++ Binding Guide 49

50 2 Importing C++ Classes Important If you have defined a relationship on a collection of type d_list<d_ref<t> >, you should avoid inserting the same object twice in the list 1. If however you do not have duplicates, you must be aware that when the inverse link is deleted only the first occurrence of the object in the list is removed. class Person{ public: d_list<d_ref<person>>children inverse Person::parents; d_set<d_ref<person>>parents inverse Person::children;... }; d_ref<person>adam = new Person; d_ref<person>cain = new Person; adam->children.insert_element(cain); adam->children.insert_element(cain); //cain is now present twice in the list of children of adam. //adam appears only once in the collection of parents of cain //because parents is a set (no duplicates). adam->children.remove_all(); //Now adam has no children but cain->parents still contains one //occurrence of adam! When a class is imported, relationship declarations are transformed into template class declarations. The following table shows the appropriate transformations: Table 2.3 Relationships and their corresponding template classes Relationship one-to-one one-to-many Template class d_relref d_relref 1. Note that this is not possible with a d_set<d_ref<t> >. 50 ODMG C++ Binding Guide

51 The O2 import tool Table 2.3 Relationships and their corresponding template classes Relationship many-to-one many-to-many Template class d_relset or d_rellist d_relset or d_rellist For example, after importation the class Person would be modified as follows: class _spouse; class _children; class _master; class _disciples;... class Person : public virtual o2_root{ public : d_string name; Address address; }; d_relref<person, Person, _spouse, _spouse> spouse; d_rellist<person, Person, _children, _parents> children; d_relref<person, Person, _master, _disciples> master; d_relset<person, Person _disciples, _master> disciples;... ODMG C++ Binding Guide 51

52 2 Importing C++ Classes Relationship template class definitions The class d_relref inherits from the class d_ref. template <class L, class R, class al, class ar> class d_relref : public d_ref<r>{ public: d_ref<r>& d_relref<l,r,al,ar>& d_relref<l,r,al,ar>& d_relref<l,r,al,ar>& d_relref<l,r,al,ar>& d_relref<l,r,al,ar>& d_relref<l,r,al,ar>& void void d_relref(l* father): d_ref<r>(); Constructor ~d_relref(); Constructor Destructor get(); set(d_relref<l,r,al,ar>& p); set(d_ref<r>& p); Establish relationship set(r* p); operator=(d_relref<l,r,al,ar>& p); operator=(d_ref<r>& p); operator=(r* p); o2_assign_handle(handle); o2_assign_handle(handle, o2_kind); void void }; clear(); delete_object(); Remove relationship 52 ODMG C++ Binding Guide

53 The O2 import tool The class d_relset inherits from the class d_set. template <class L, class R, class al, class ar> class d_relset : public d_set<d_ref<r> > { public: Constructor d_relset(l* father): d_set<d_ref<r> >(); d_set<d_ref<r> > get(); d_relset<l,r,al,ar>& d_relset<l,r,al,ar>& d_relset<l,r,al,ar>& d_relset<l,r,al,ar>& set(d_relset<l,r,al,ar>& s); set(d_set<d_ref<r> >& s); operator=(d_relset<l,r,al,ar>& s); operator=(d_set<d_ref<r> >& s); Assignment void void void void d_relset<l,r,al,ar>& d_relset<l,r,al,ar>& d_relset<l,r,al,ar>& o2_assign_handle(handle); Establish relationship insert_element(const d_ref<r>&); Delete relationship remove_element(const d_ref<r>&); remove_all(); Set operators (hide d_set operators) union_of( const d_relset<l,r,al,ar>& SL, const d_relset<l,r,al,ar>& SR); union_with(const d_relset<l,r,al,ar>& SR); operator+=(const d_relset<l,r,al,ar>& SR); d_relset<l,r,al,ar>& intersection_of( const d_relset<l,r,al,ar>& SL, const d_relset<l,r,al,ar>& SR); d_relset<l,r,al,ar>& d_relset<l,r,al,ar>& intersection_with(const d_relset<l,r,al,ar>& SR); operator*=(const d_relset<l,r,al,ar>& SR); d_relset<l,r,al,ar>& difference_of( const d_relset<l,r,al,ar>& SL, const d_relset<l,r,al,ar>& SR); d_relset<l,r,al,ar>& d_relset<l,r,al,ar>& difference_with(const d_relset<l,r,al,ar>& SR); operator-=(const d_relset<l,r,al,ar>& SR); }; ODMG C++ Binding Guide 53

54 2 Importing C++ Classes The class d_rellist inherits from the class d_list. template <class L, class R, class al, class ar> class d_rellist : public d_list<d_ref<r> > { public: Constructor d_rellist(l* father): d_list<d_ref<r> >(); d_list<d_ref<r> > get() {return *this;} d_rellist<l,r,al,ar>& set(d_rellist<l,r,al,ar>&); d_rellist<l,r,al,ar>& set(d_list<d_ref<r> >&); d_rellist<l,r,al,ar>& operator=(d_rellist<l,r,al,ar>&); d_rellist<l,r,al,ar>& operator=(d_list<d_ref<r> >&); Assignment void void void void void void void o2_assign_handle(handle); Delete relationship remove_element(const d_ref<r>&); remove_first_element(); remove_last_element(); remove_element_at(unsigned long); remove_all(); Change relationship replace_element_at(const d_ref<r>&, unsigned long); Establish relationship void void void void void insert_element(const d_ref<r>&); insert_element_first(const d_ref<r>&); insert_element_last(const d_ref<r>&); insert_element_after(const d_ref<r>&, unsigned long); insert_element_before( const d_ref<r>&, unsigned long); List oper at ors (h ide th e d_list operators) d_rellist<l,r,al,ar>& append(const d_rellist<l,r,al,ar>&); d_rellist<l,r,al,ar>& operator+=(const d_rellist<l,r,al,ar>& ListR) {return append(listr);} }; 54 ODMG C++ Binding Guide

55 The O2 import tool Important You must initialize the relationship in the class constructor where the relationship is defined. The constructor s argument must be a pointer to the object of the relationship. For example, the constructor for the class Person must be as follows: Person::Person(const char* n): name(n), spouse(this), children(this), master(this), disciples(this) {... } Important A one-to-one relationship creates a closed cycle of pointers in memory. You must use the d_ref<t>::destroy() m eth od t o break t h e cycle. Refer to the subsection Reference cycle in section 5.6. ODMG C++ Binding Guide 55

56 2 Importing C++ Classes 2.3 Programmed mapping A C++ programmer can determine the mapping of a C++ object to a corresponding O 2 object, overriding the default mapping rules. The mapping of a C++ class K to an O 2 class is automatically generated from the structure of the class K. This mapping follows rules starting from atomic types and recursively mapping constructed attributes. In some circumstances, this automatic mapping creates cumbersome objects which must be handled both by a C++ program and by O 2 tools. For instance, depending on the O 2 class generated by the mapping, it may be difficult to write OQL queries or to browse the database, because the O 2 types are not logically adapted to manipulation, although well suited to be made persistent. Two t ypical exam ples are given below: The class d_date in O 2 is mapped to a tuple with one integer and two char acter s, becau se the C++ class is implemented with three integers stored in C++ short and char types. It is difficult to query such an object because the structure of the att r ibu t es ar e n ot eviden t to an O 2 user. Moreover, it is not possible to create a reasonable index for such a Date attribute. To create persistent objects constructed from instances of an external libr ar y class, e.g. STL, t h e u ser m u st cr eat e a su bclass of t h e librar y class and import the subclass. But this is limited to the public and protected data members of library classes, while the majority of library classes use private members. In such situations, the user can customize the mapping in order to obtain more suitable O 2 types. Mapping a C++ class to a persistent structure Given a C++ class K, suited for a C++ application we define a persistent structure of class K objects to be store in O 2. By default, a persistent structure is derived automatically from the class K by rules given in this chapter (see Table 2.1). We provide a way for a user to explicitly define the persistent structure of a class K. Let this structure be called PK. 56 ODMG C++ Binding Guide