From d9e5bead995338786bcd0a5a3b684c9b06e7e3db Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Tue, 26 Apr 2011 15:54:21 +0200 Subject: Add chapter on object inheritance, document abstract pragma --- doc/manual.xhtml | 746 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 517 insertions(+), 229 deletions(-) diff --git a/doc/manual.xhtml b/doc/manual.xhtml index 4242618..930d93f 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -389,71 +389,81 @@ for consistency. - 8Session + 8Inheritance - + +
8.1Object Cache
8.1Reuse Inheritance
8.2Polymorphism Inheritance
- 9ODB Pragma Language + 9Session + + +
9.1Object Cache
+ + + + + 10ODB Pragma Language - - - - @@ -466,30 +476,30 @@ for consistency. - - - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - +
9.1Object Type Pragmas + 10.1Object Type Pragmas - - + + +
9.1.1table
9.1.2pointer
10.1.1table
10.1.2pointer
10.1.3abstract
9.2Value Type Pragmas + 10.2Value Type Pragmas - - - - - - - - - - - + + + + + + + + + + +
9.2.1type
9.2.2id_type
9.2.3not_null
9.2.4unordered
9.2.5index_type
9.2.6key_type
9.2.7value_type
9.2.8id_column
9.2.9index_column
9.2.10key_column
9.2.11value_column
10.2.1type
10.2.2id_type
10.2.3not_null
10.2.4unordered
10.2.5index_type
10.2.6key_type
10.2.7value_type
10.2.8id_column
10.2.9index_column
10.2.10key_column
10.2.11value_column
9.3Data Member Pragmas + 10.3Data Member Pragmas - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + +
9.3.1id
9.3.2auto
9.3.3type
9.3.4column
9.3.5transient
9.3.6not_null
9.3.7inverse
9.3.8unordered
9.3.9table
9.3.10index_type
9.3.11key_type
9.3.12value_type
9.3.13id_column
9.3.14index_column
9.3.15key_column
9.3.16value_column
10.3.1id
10.3.2auto
10.3.3type
10.3.4column
10.3.5transient
10.3.6not_null
10.3.7inverse
10.3.8unordered
10.3.9table
10.3.10index_type
10.3.11key_type
10.3.12value_type
10.3.13id_column
10.3.14index_column
10.3.15key_column
10.3.16value_column
9.4C++ Compiler Warnings + 10.4C++ Compiler Warnings - - - - - + + + + +
9.4.1GNU C++
9.4.2Visual C++
9.4.3Sun C++
9.4.4IBM XL C++
9.4.5HP aC++
10.4.1GNU C++
10.4.2Visual C++
10.4.3Sun C++
10.4.4IBM XL C++
10.4.5HP aC++
10MySQL Database + 11MySQL Database - - - - + + + +
10.1MySQL Type Mapping
10.2MySQL Database Class
10.3MySQL Connection Factory
10.4MySQL Exceptions
11.1MySQL Type Mapping
11.2MySQL Database Class
11.3MySQL Connection Factory
11.4MySQL Exceptions
11SQLite Database + 12SQLite Database - - - - + + + + - @@ -502,19 +512,19 @@ for consistency. - + - - + - + - + - + - + - + - + - + - + - + - +
11.1SQLite Type Mapping
11.2SQLite Database Class
11.3SQLite Connection Factory
11.4SQLite Exceptions
12.1SQLite Type Mapping
12.2SQLite Database Class
12.3SQLite Connection Factory
12.4SQLite Exceptions
11.5SQLite Limitations + 12.5SQLite Limitations - - - - + + + +
11.5.1Query Result Caching
11.5.2Automatic Assignment of Object Ids
11.5.3Constraint Violations
11.5.4Sharing of Queries
12.5.1Query Result Caching
12.5.2Automatic Assignment of Object Ids
12.5.3Constraint Violations
12.5.4Sharing of Queries
12Profiles Introduction13Profiles Introduction
13Boost Profile + 14Boost Profile - - + + - @@ -523,23 +533,23 @@ for consistency. - - + - + + + + + + +
13.1Smart Pointers Library
13.2Unordered Containers Library
14.1Smart Pointers Library
14.2Unordered Containers Library
13.3Date Time Library + 14.3Date Time Library - - + +
13.3.1MySQL Database Type Mapping
13.3.2SQLite Database Type Mapping
14.3.1MySQL Database Type Mapping
14.3.2SQLite Database Type Mapping
14Qt Profile + 15Qt Profile - - - + + - @@ -659,8 +669,9 @@ for consistency. - - + + +
14.1Basic Types Library + 15.1Basic Types Library - - + +
14.1.1MySQL Database Type Mapping
14.1.2SQLite Database Type Mapping
15.1.1MySQL Database Type Mapping
15.1.2SQLite Database Type Mapping
14.2Smart Pointers Library
14.3Containers Library
15.2Smart Pointers Library
15.3Containers Library
14.4Date Time Library + 15.4Date Time Library - - + +
14.4.1MySQL Database Type Mapping
14.4.2SQLite Database Type Mapping
15.4.1MySQL Database Type Mapping
15.4.2SQLite Database Type Mapping
5Containers
6Relationships
7Composite Value Types
8Session
9ODB Pragma Language
8Inheritance
9Session
10ODB Pragma Language
@@ -1272,7 +1283,7 @@ main (int argc, char* argv[]) database name, etc., from the command line. In your own applications you may prefer to use other mysql::database constructors which allow you to pass this information directly - (Section 10.2, "MySQL Database Class").

+ (Section 11.2, "MySQL Database Class").

Next, we create three person objects. Right now they are transient objects, which means that if we terminate the application @@ -1825,7 +1836,7 @@ class person

These two pragmas are the minimum required to declare a persistent class. Other pragmas can be used to fine-tune the database-related properties of a class and its - members (Chapter 9, "ODB Pragma Language").

+ members (Chapter 10, "ODB Pragma Language").

Normally, an object class should define the default constructor. The generated database support code uses this constructor when @@ -1871,7 +1882,7 @@ private: mapping to the database system type and, possibly, the code to convert between the two. For more information on how to achieve this refer to the db type pragma description - in Section 9.2.1, "type". Similar + in Section 10.2.1, "type". Similar to object types, composite value types have to be explicitly declared as persistent using the db value pragma, for example:

@@ -1939,7 +1950,7 @@ class name return pointers to these instances. As we will see in later chapters, pointers are also used to establish relationships between objects (Chapter 6, Relationships) as well as to cache - persistent objects in a session (Chapter 8, Session).

+ persistent objects in a session (Chapter 9, Session).

By default, all these mechanisms use raw pointers to return, pass, and cache objects. This is normally sufficient for applications @@ -1982,7 +1993,7 @@ class person }; -

Refer to Section 9.1.2, "pointer" +

Refer to Section 10.1.2, "pointer" for more information on this pragma.

Built-in support that is provided by the ODB runtime library allows us @@ -2106,7 +2117,7 @@ namespace odb our application. To map persistent classes to custom database schemas, ODB provides a wide range of mapping customization pragmas, such as db table, db column, - and db type (Chapter 9, "ODB Pragma + and db type (Chapter 10, "ODB Pragma Language"). For sample code that shows how to perform such mapping for various C++ constructs, refer to the schema/custom example in the odb-examples package.

@@ -2395,7 +2406,7 @@ for (unsigned short retry_count (0); ; retry_count++)

The first persist() function expects a constant reference to an instance being persisted. The second function expects a constant object pointer. Both of these functions can only be used on objects with - application-assigned object ids (Section 9.3.2, + application-assigned object ids (Section 10.3.2, "auto").

The second and third persist() functions are similar to the @@ -2839,7 +2850,7 @@ namespace odb not_in_session, and const_object) are thrown by the odb::session class and are discussed - in Chapter 8, "Session".

+ in Chapter 9, "Session".

The recoverable exception serves as a common base for all the recoverable exceptions, which are: connection_lost, @@ -3569,7 +3580,7 @@ private:

A number of ODB pragmas allow us to customize the table name, column names, and native database types of an ordered container both, on the per-container and per-member basis. For more information on - these pragmas, refer to Chapter 9, "ODB Pragma + these pragmas, refer to Chapter 10, "ODB Pragma Language". The following example shows some of the possible customizations:

@@ -3595,8 +3606,8 @@ private: the order information. In the example above, for instance, the order of person's nicknames is probably not important. To instruct the ODB compiler to ignore the order in ordered containers we can use the - db unordered pragma (Section 9.2.4, - "unordered", Section 9.3.8, + db unordered pragma (Section 10.2.4, + "unordered", Section 10.3.8, "unordered"). For example:

@@ -3657,7 +3668,7 @@ private:
   
A number of ODB pragmas allow us to customize the table name,
      column names, and native database types of a set container, both on
      the per-container and per-member basis. For more information on
-     these pragmas, refer to Chapter 9, "ODB Pragma
+     these pragmas, refer to Chapter 10, "ODB Pragma
      Language". The following example shows some of the possible
      customizations:

 
@@ -3719,7 +3730,7 @@ private:
   
A number of ODB pragmas allow us to customize the table name,
      column names, and native database types of a map container, both on
      the per-container and per-member basis. For more information on
-     these pragmas, refer to Chapter 9, "ODB Pragma
+     these pragmas, refer to Chapter 10, "ODB Pragma
      Language". The following example shows some of the possible
      customizations:

 
@@ -3907,7 +3918,7 @@ unsigned long john_id, jane_id;
 
   
The only notable line in the above code is the creation of a
      session before the second transaction starts. As discussed in
-     Chapter 8, "Session", a session acts as a cache
+     Chapter 9, "Session", a session acts as a cache
      of persistent objects.
      By creating a session before loading the employee
      objects we make sure that their employer_ pointers
@@ -4075,7 +4086,7 @@ CREATE TABLE employee_projects (
 
   
To obtain a more canonical database schema, the names of tables
      and columns above can be customized using ODB pragmas
-     (Chapter 9, "ODB Pragma Language"). For example:

+     (Chapter 10, "ODB Pragma Language"). For example:

 
   
 #pragma db object
@@ -4198,7 +4209,7 @@ CREATE TABLE employee (
      of these references.

 
   
To eliminate redundant database schema references we can use the
-     inverse pragma (Section 9.3.7,
+     inverse pragma (Section 10.3.7,
      "inverse") which tells the ODB compiler that
      a pointer is the inverse side of a bidirectional relationship.
      Either side of a relationship can be made inverse. For example:

@@ -4242,7 +4253,7 @@ CREATE TABLE employee (
      pointer. Also note that an ordered container (Section
      5.1, "Ordered Containers") of pointers that is an inverse side
      of a bidirectional relationship is always treated as unordered
-     (Section 9.3.8, "unordered")
+     (Section 10.3.8, "unordered")
      because the contents of such a container are implicitly built from
      the direct side of the relationship which does not contain the
      element order (index).

@@ -4924,8 +4935,8 @@ t.commit ();
 
   
Customizing a column name for a data member of a simple value
      type is straightforward: we simply specify the desired name with
-     the db column pragma (Section
-     9.3.4, "column"). For composite value
+     the db column pragma (Section
+     10.3.4, "column"). For composite value
      types things are slightly more complex since they are mapped to
      multiple columns. Consider the following example:

 
@@ -5026,9 +5037,9 @@ CREATE TABLE person (
   
The same principle applies when a composite value type is used
      as an element of a container, except that instead of
      db column, either the db value_column
-     (Section 9.3.16, "value_column") or
+     (Section 10.3.16, "value_column") or
      db key_column
-     (Section 9.3.15, "key_column")
+     (Section 10.3.15, "key_column")
      pragmas are used to specify the column prefix.

 
   
When a composite value type contains a container, an extra table
@@ -5072,8 +5083,8 @@ CREATE TABLE person (
   

 
   
To customize the container table name we can use the
-     db table pragma (Section
-     9.3.9, "table"), for example:

+     db table pragma (Section
+     10.3.9, "table"), for example:

 
   
 #pragma db value
@@ -5111,7 +5122,246 @@ CREATE TABLE `person_nickname` (
 
 
   

-  
8 Session

+  
8 Inheritance

+
+  
In C++ inheritance can be used to achieve two different goals.
+     We can employ inheritance to reuse common data and functionality
+     in multiple classes. For example:

+
+  
+class person
+{
+public:
+  const std::string&
+  first () const;
+
+  const std::string&
+  last () const;
+
+private:
+  std::string first_;
+  std::string last_;
+};
+
+class employee: public person
+{
+  ...
+};
+
+class contractor: public person
+{
+  ...
+};
+

+
+ 
In the above example both the employee and
+    contractor classes inherit the first_
+    and last_ data members as well as the first()
+    and last() accessors from the person base
+    class.

+
+ 
A common trait of this inheritance style, referred to as reuse
+    inheritance from now on, is the lack of virtual functions and
+    a virtual destructor in the base class. Also with this style the
+    application code is normally written in terms of derived classes
+    instead of a base.

+
+ 
The second way to utilize inheritance in C++ is to provide polymorphic
+    behavior through a common interface. In this case the base class
+    defines a number of virtual functions and, normally, a virtual
+    destructor while the derived classes provide specific
+    implementations of these virtual functions. For example:

+
+  
+class person
+{
+public:
+  enum employment_status
+  {
+    unemployed,
+    temporary,
+    permanent,
+    self_employed
+  };
+
+  virtual employment_status
+  employment () const = 0;
+
+  virtual
+  ~person ();
+};
+
+class employee: public person
+{
+public:
+  virtual employment_status
+  employment () const
+  {
+    return temporary_ ? temporary : permanent;
+  }
+
+private:
+  bool temporary_;
+};
+
+class contractor: public person
+{
+public:
+  virtual employment_status
+  employment () const
+  {
+    return self_employed;
+  }
+};
+

+
+  
With this inheritance style, which we will call polymorphism
+     inheritance, the application code normally works with derived
+     classes via the base class interface. Note also that it is very common
+     to mix both styles in the same hierarchy. For example, the above two
+     code fragments can be combined so that the person base
+     class provides the common data members and functions as well as
+     defines the polymorphic interface.

+
+  
The following sections describe the available strategies for
+     mapping reuse and polymorphism inheritance styles to a relational
+     data model. Note also that the distinction between the two styles is
+     conceptual rather than formal. For example, it is possible to treat
+     a class hierarchy that defines virtual functions as a case of reuse
+     inheritance if this results in the desired database mapping and
+     semantics.

+
+  
Generally, classes that employ reuse inheritance are mapped to
+     completely independent entities in the database. They use different
+     object id spaces and should always be passed to and returned from
+     the database operations as pointers or references to derived types.
+     In other words, from the persistence point of view, such classes
+     behave as if the data members from the base classes were copied
+     verbatim into the derived ones.

+
+  
In contrast, classes that employ polymorphism inheritance share
+     the object id space and can be passed to and returned from the
+     database operations polymorphically as pointers or
+     references to the base class.

+
+  
For both inheritance styles it is sometimes desirable to prevent
+     instances of a base class from being stored in the database.
+     To achieve this a persistent
+     class can be declared abstract using the db abstract
+     pragma (Section 10.1.3, "abstract").
+     Note that a C++-abstract class, or a class that
+     has one or more pure virtual functions and therefore cannot be
+     instantiated, is also database-abstract. However, a
+     database-abstract class is not necessarily C++-abstract. The
+     ODB compiler automatically treats C++-abstract classes as
+     database-abstract.

+
+  
8.1 Reuse Inheritance

+
+  
Each non-abstract class from the reuse inheritance hierarchy is
+     mapped to a separate database table that contains all its data
+     members, including those inherited from base classes. An abstract
+     persistent class does not have to define an object id, nor a default
+     constructor, and it does not have a corresponding database table.
+     An abstract class cannot be a pointed-to object in a relationship.
+     Multiple inheritance is supported as long as each base
+     class is only inherited once. The following example shows a
+     persistent class hierarchy employing reuse inheritance:

+
+
+// Abstract person class. Note that it does not declare the
+// object id.
+//
+#pragma db object abstract
+class person
+{
+  ...
+
+  std::string first_;
+  std::string last_;
+};
+
+// Abstract employee class. It derives from the person class and
+// declares the object id for all the concrete employee types.
+//
+#pragma db object abstract
+class employee: public person
+{
+  ...
+
+  #pragma db id auto
+  unsigned long id_;
+};
+
+// Concrete permanent_employee class. Note that it doesn't define
+// any data members of its own.
+//
+#pragma db object
+class permanent_employee: public employee
+{
+  ...
+};
+
+// Concrete temporary_employee class. It adds the employment
+// duration in months.
+//
+#pragma db object
+class temporary_employee: public employee
+{
+  ...
+
+  unsigned long duration_;
+};
+
+// Concrete contractor class. It derives from the person class
+// (and not employee; an independent contractor is not considered
+// an employee). We use the contractor's external email address
+// as the object id.
+//
+#pragma db object
+class contractor: public person
+{
+  ...
+
+  #pragma db id
+  std::string email_;
+};
+

+
+  
The sample database schema for this hierarchy is shown below.

+
+
+CREATE TABLE permanent_employee (
+  first TEXT NOT NULL,
+  last TEXT NOT NULL,
+  id BIGINT UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT);
+
+CREATE TABLE temporary_employee (
+  first TEXT NOT NULL,
+  last` TEXT NOT NULL,
+  id BIGINT UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT,
+  duration BIGINT UNSIGNED NOT NULL);
+
+CREATE TABLE contractor (
+  first TEXT NOT NULL,
+  last TEXT NOT NULL,
+  email VARCHAR (255) NOT NULL PRIMARY KEY);
+

+
+  
The complete version of the code presented in this section is
+     available in the inheritance example in the
+     odb-examples package.

+
+  
8.2 Polymorphism Inheritance

+
+  
Polymorphism inheritance mapping is not yet implemented. Future
+     versions of ODB will add support for this functionality.

+
+  
+
+
+  

+  
9 Session

 
   
A session is an application's unit of work that may encompass several
      database transactions. In this version of ODB a session is just an
@@ -5233,7 +5483,7 @@ namespace odb
      it could be useful in some cases, for example, to find out whether
      an object has already been loaded.

 
-  
8.1 Object Cache

+  
9.1 Object Cache

 
   
A session is an object cache. Every time an object is made persistent
      by calling the database::persist() function
@@ -5301,7 +5551,7 @@ t.commit ();
 
 
   

-  
9 ODB Pragma Language

+  
10 ODB Pragma Language

 
   
As we have already seen in previous chapters, ODB uses a pragma-based
      language to capture database-specific information about C++ types.
@@ -5464,10 +5714,10 @@ class person
      the C++ compiler to build the application. Some C++ compilers
      issue warnings about pragmas that they do not recognize. There
      are several ways to deal with this problem which are covered
-     at the end of this chapter in Section 9.4,
+     at the end of this chapter in Section 10.4,
      "C++ Compiler Warnings".

 
-  
9.1 Object Type Pragmas

+  
10.1 Object Type Pragmas

 
   
A pragma with the object qualifier declares a C++ class
      as a persistent object type. The qualifier can be optionally followed,
@@ -5484,19 +5734,25 @@ class person
table table name for a persistent class9.1.110.1.1
pointer pointer type for a persistent class9.1.210.1.2
abstractpersistent class is abstract10.1.3
-

9.1.1 table

+

10.1.1 table

The table specifier specifies the table name that should be used to store objects of a class in a relational database. For @@ -5513,7 +5769,7 @@ class person

If the table name is not specified, the class name is used as the table name.

-

9.1.2 pointer

+

10.1.2 pointer

The pointer specifier specifies the object pointer type for a persistent class. The object pointer type is used to return, @@ -5563,7 +5819,39 @@ class person

For a more detailed discussion of object pointers, refer to Section 3.2, "Object Pointers".

-

9.2 Value Type Pragmas

+

10.1.3 abstract

+ +

The abstract specifier specifies that a persistent class + is abstract. An instance of an abstract class cannot be stored in + the database and is normally used as a base for other persistent + classes. For example:

+ + 
+#pragma db object abstract
+class person
+{
+  ...
+};
+
+#pragma db object
+class employee: public person
+{
+  ...
+};
+
+#pragma db object
+class contractor: public person
+{
+  ...
+};
+
+ +

Persistent classes with pure virtual functions are automatically + treated as abstract by the ODB compiler. For a more detailed + discussion of persistent class inheritance, refer to + Chapter 8, "Inheritance".

+ +

10.2 Value Type Pragmas

A pragma with the value qualifier describes a value type. It can be optionally followed, in any order, by one or more @@ -5580,73 +5868,73 @@ class person

type database type for a value type9.2.110.2.1
id_type database type for a value type when used as an object id9.2.210.2.2
not_null object pointer cannot be NULL9.2.310.2.3
unordered ordered container should be stored unordered9.2.410.2.4
index_type database type for a container's index type9.2.510.2.5
key_type database type for a container's key type9.2.610.2.6
value_type database type for a container's value type9.2.710.2.7
id_column column name for a container's table object id9.2.810.2.8
index_column column name for a container's table index9.2.910.2.9
key_column column name for a container's table key9.2.1010.2.10
value_column column name for a container's table value9.2.1110.2.11

Many of the value type specifiers have corresponding member type - specifiers with the same names (Section 9.3, + specifiers with the same names (Section 10.3, "Data Member Pragmas"). The behavior of such specifiers for members is similar to that for value types. The only difference is the scope. A particular value type specifier applies to all the @@ -5655,7 +5943,7 @@ class person to a single member. In other words, member specifiers take precedence over parameters specified with value specifiers.

-

9.2.1 type

+

10.2.1 type

The type specifier specifies the native database type that should be used for data members of this type. For example:

@@ -5703,13 +5991,13 @@ private: mapping example in the odb-examples package shows how to do this for all the supported database systems.

-

9.2.2 id_type

+

10.2.2 id_type

The id_type specifier specifies the native database type that should be used for data members of this type that are designated as - object identifiers (Section 9.3.1, + object identifiers (Section 10.3.1, "id"). In combination with the type - specifier (Section 9.2.1, "type") + specifier (Section 10.2.1, "type") id_type allows you to map a C++ type differently depending on whether it is used in an ordinary member or an object id. For example:

@@ -5746,7 +6034,7 @@ private: }; -

9.2.3 not_null

+

10.2.3 not_null

The not_null specifier specifies that an object pointer or a container of object pointers cannot have or contain the @@ -5777,7 +6065,7 @@ typedef std::vector<shared_ptr<account> > accounts;

For a more detailed discussion of the NULL object pointer semantics, refer to Chapter 6, "Relationships".

-

9.2.4 unordered

+

10.2.4 unordered

The unordered specifier specifies that the ordered container should be stored unordered in the database. The database @@ -5794,13 +6082,13 @@ typedef std::vector<std::string> names; storage in the database, refer to Section 5.1, "Ordered Containers".

-

9.2.5 index_type

+

10.2.5 index_type

The index_type specifier specifies the native database type that should be used for an ordered container's index column. The semantics of index_type are similar to that of the type specifier - (Section 9.2.1, "type"). The native + (Section 10.2.1, "type"). The native database type is expected to be an integer type. For example:

@@ -5808,13 +6096,13 @@ typedef std::vector<std::string> names;
 #pragma db value(names) index_type("SMALLINT UNSIGNED NOT NULL")
-

9.2.6 key_type

+

10.2.6 key_type

The key_type specifier specifies the native database type that should be used for a map container's key column. The semantics of key_type are similar to that of the type specifier - (Section 9.2.1, "type"). For + (Section 10.2.1, "type"). For example:

@@ -5822,13 +6110,13 @@ typedef std::map<unsigned short, float> age_weight_map;
 #pragma db value(age_weight_map) key_type("INT UNSIGNED NOT NULL")
-

9.2.7 value_type

+

10.2.7 value_type

The value_type specifier specifies the native database type that should be used for a container's value column. The semantics of value_type are similar to that of the type specifier - (Section 9.2.1, "type"). For + (Section 10.2.1, "type"). For example:

@@ -5836,7 +6124,7 @@ typedef std::vector<std::string> names;
 #pragma db value(names) value_type("VARCHAR(255) NOT NULL")
-

9.2.8 id_column

+

10.2.8 id_column

The id_column specifier specifies the column name that should be used to store the object id in a @@ -5850,7 +6138,7 @@ typedef std::vector<std::string> names;

If the column name is not specified, then object_id is used by default.

-

9.2.9 index_column

+

10.2.9 index_column

The index_column specifier specifies the column name that should be used to store the element index in an @@ -5864,7 +6152,7 @@ typedef std::vector<std::string> names;

If the column name is not specified, then index is used by default.

-

9.2.10 key_column

+

10.2.10 key_column

The key_column specifier specifies the column name that should be used to store the key in a map @@ -5878,7 +6166,7 @@ typedef std::map<unsigned short, float> age_weight_map;

If the column name is not specified, then key is used by default.

-

9.2.11 value_column

+

10.2.11 value_column

The value_column specifier specifies the column name that should be used to store the element value in a @@ -5895,7 +6183,7 @@ typedef std::map<unsigned short, float> age_weight_map; -

9.3 Data Member Pragmas

+

10.3 Data Member Pragmas

A pragma with the member qualifier or a positioned pragma without a qualifier describes a data member. It can @@ -5913,104 +6201,104 @@ typedef std::map<unsigned short, float> age_weight_map;

id member is an object id9.3.110.3.1
auto id is assigned by the database9.3.210.3.2
type database type for member9.3.310.3.3
column column name for member9.3.410.3.4
transient member is not stored in the database9.3.510.3.5
not_null object pointer cannot be NULL9.3.610.3.6
inverse member is an inverse side of a bidirectional relationship9.3.710.3.7
unordered ordered container should be stored unordered9.3.810.3.8
table table name for a container9.3.910.3.9
index_type database type for a container's index type9.3.1010.3.10
key_type database type for a container's key type9.3.1110.3.11
value_type database type for a container's value type9.3.1210.3.12
id_column column name for a container's object id9.3.1310.3.13
index_column column name for a container's index9.3.1410.3.14
key_column column name for a container's key9.3.1510.3.15
value_column column name for a container's value9.3.1610.3.16

Many of the member specifiers have corresponding value type - specifiers with the same names (Section 9.2, + specifiers with the same names (Section 10.2, "Value Type Pragmas"). The behavior of such specifiers for members is similar to that for value types. The only difference is the scope. A particular value type specifier applies to all the @@ -6019,7 +6307,7 @@ typedef std::map<unsigned short, float> age_weight_map; to a single member. In other words, member specifiers take precedence over parameters specified with value specifiers.

-

9.3.1 id

+

10.3.1 id

The id specifier specifies that a data member contains the object id. Every persistent class must have a member designated @@ -6040,7 +6328,7 @@ private:

In a relational database, an identifier member is mapped to a primary key.

-

9.3.2 auto

+

10.3.2 auto

The auto specifier specifies that the object's identifier is automatically assigned by the database. Only a member that was @@ -6068,7 +6356,7 @@ private:

For additional information on the automatic identifier assignment, refer to Section 3.6, "Making Objects Persistent".

-

9.3.3 type

+

10.3.3 type

The type specifier specifies the native database type that should be used for a data member. For example:

@@ -6085,7 +6373,7 @@ private: }; -

9.3.4 column

+

10.3.4 column

The column specifier specifies the column name that should be used to store a data member in a relational database. @@ -6111,7 +6399,7 @@ private: name by removing the common data member name decorations, such as leading and trailing underscores, the m_ prefix, etc.

-

9.3.5 transient

+

10.3.5 transient

The transient specifier instructs the ODB compiler not to store a data member in the database. For example:

@@ -6134,7 +6422,7 @@ private: references that are only meaningful in the application's memory, as well as utility members such as mutexes, etc.

-

9.3.6 not_null

+

10.3.6 not_null

The not_null specifier specifies that a data member of an object pointer or a container of object pointers type cannot @@ -6166,7 +6454,7 @@ private:

For a more detailed discussion of the NULL object pointer semantics, refer to Chapter 6, "Relationships".

-

9.3.7 inverse

+

10.3.7 inverse

The inverse specifier specifies that a data member of an object pointer or a container of object pointers type is an @@ -6206,12 +6494,12 @@ private: relationship information. Only ordered and set containers can be used for inverse members. If an inverse member is of an ordered container type, it is automatically marked as unordered - (Section 9.3.8, "unordered").

+ (Section 10.3.8, "unordered").

For a more detailed discussion of inverse members, refer to Section 6.2, "Bidirectional Relationships".

-

9.3.8 unordered

+

10.3.8 unordered

The unordered specifier specifies that a member of an ordered container type should be stored unordered in the database. @@ -6235,7 +6523,7 @@ private: storage in the database, refer to Section 5.1, "Ordered Containers".

-

9.3.9 table

+

10.3.9 table

The table specifier specifies the table name that should be used to store the contents of a container member. For example:

@@ -6266,13 +6554,13 @@ private: to Section 7.1, "Composite Value Column and Table Names" for details.

-

9.3.10 index_type

+

10.3.10 index_type

The index_type specifier specifies the native database type that should be used for an ordered container's index column of a data member. The semantics of index_type are similar to that of the type specifier - (Section 9.3.3, "type"). The native + (Section 10.3.3, "type"). The native database type is expected to be an integer type. For example:

@@ -6287,13 +6575,13 @@ private:
 };
-

9.3.11 key_type

+

10.3.11 key_type

The key_type specifier specifies the native database type that should be used for a map container's key column of a data member. The semantics of key_type are similar to that of the type specifier - (Section 9.3.3, "type"). For + (Section 10.3.3, "type"). For example:

@@ -6308,13 +6596,13 @@ private:
 };
-

9.3.12 value_type

+

10.3.12 value_type

The value_type specifier specifies the native database type that should be used for a container's value column of a data member. The semantics of value_type are similar to that of the type specifier - (Section 9.3.3, "type"). For + (Section 10.3.3, "type"). For example:

@@ -6329,14 +6617,14 @@ private:
 };
-

9.3.13 id_column

+

10.3.13 id_column

The id_column specifier specifies the column name that should be used to store the object id in a container's table for a data member. The semantics of id_column are similar to that of the column specifier - (Section 9.3.4, "column"). + (Section 10.3.4, "column"). For example:

@@ -6354,14 +6642,14 @@ private:
   
If the column name is not specified, then object_id
      is used by default.

 
-  
9.3.14 index_column

+  
10.3.14 index_column

 
   
The index_column specifier specifies the column
      name that should be used to store the element index in an
      ordered container's table for a data member. The semantics of
      index_column are similar to that of the
      column specifier
-     (Section 9.3.4, "column").
+     (Section 10.3.4, "column").
      For example:

 
   
@@ -6379,14 +6667,14 @@ private:
   
If the column name is not specified, then index
      is used by default.

 
-  
9.3.15 key_column

+  
10.3.15 key_column

 
   
The key_column specifier specifies the column
      name that should be used to store the key in a map
      container's table for a data member. The semantics of
      key_column are similar to that of the
      column specifier
-     (Section 9.3.4, "column").
+     (Section 10.3.4, "column").
      For example:

 
   
@@ -6404,14 +6692,14 @@ private:
   
If the column name is not specified, then key
      is used by default.

 
-  
9.3.16 value_column

+  
10.3.16 value_column

 
   
The value_column specifier specifies the column
      name that should be used to store the element value in a
      container's table for a data member. The semantics of
      value_column are similar to that of the
      column specifier
-     (Section 9.3.4, "column").
+     (Section 10.3.4, "column").
      For example:

 
   
@@ -6429,7 +6717,7 @@ private:
   
If the column name is not specified, then value
      is used by default.

 
-  
9.4 C++ Compiler Warnings

+  
10.4 C++ Compiler Warnings

 
   
When a C++ header file defining persistent classes and containing
      ODB pragmas is used to build the application, the C++ compiler may
@@ -6484,7 +6772,7 @@ private:
   
The disadvantage of this approach is that it can quickly become
      overly verbose when positioned pragmas are used.

 
-  
9.4.1 GNU C++

+  
10.4.1 GNU C++

 
   
GNU g++ does not issue warnings about unknown pragmas
      unless requested with the -Wall command line option.
@@ -6496,7 +6784,7 @@ private:
 g++ -Wall -Wno-unknown-pragmas ...
   

 
-  
9.4.2 Visual C++

+  
10.4.2 Visual C++

 
   
Microsoft Visual C++ issues an unknown pragma warning (C4068) at
      warning level 1 or higher. This means that unless we have disabled
@@ -6531,7 +6819,7 @@ private:
 #pragma warning (pop)
   

 
-  
9.4.3 Sun C++

+  
10.4.3 Sun C++

 
   
The Sun C++ compiler does not issue warnings about unknown pragmas
      unless the +w or +w2 option is specified.
@@ -6543,7 +6831,7 @@ private:
 CC +w -erroff=unknownpragma ...
   

 
-  
9.4.4 IBM XL C++

+  
10.4.4 IBM XL C++

 
   
IBM XL C++ issues an unknown pragma warning (1540-1401) by default.
      To disable this warning we can add the -qsuppress=1540-1401
@@ -6553,7 +6841,7 @@ CC +w -erroff=unknownpragma ...
 xlC -qsuppress=1540-1401 ...
-

9.4.5 HP aC++

+

10.4.5 HP aC++

HP aC++ (aCC) issues an unknown pragma warning (2161) by default. To disable this warning we can add the +W2161 @@ -6579,8 +6867,8 @@ aCC +W2161 ... chapters.

- - + +
10MySQL Database
11SQLite Database
11MySQL Database
12SQLite Database
@@ -6588,7 +6876,7 @@ aCC +W2161 ...
-

10 MySQL Database

+

11 MySQL Database

To generate support code for the MySQL database you will need to pass the "--database mysql" @@ -6597,12 +6885,12 @@ aCC +W2161 ... library (libodb-mysql). All MySQL-specific ODB classes are defined in the odb::mysql namespace.

-

10.1 MySQL Type Mapping

+

11.1 MySQL Type Mapping

The following table summarizes the default mapping between basic C++ value types and MySQL database types. This mapping can be customized on the per-type and per-member basis using the ODB - Pragmas Language (Chapter 9, "ODB Pragma + Pragmas Language (Chapter 10, "ODB Pragma Language").

@@ -6721,7 +7009,7 @@ class object }; -

10.2 MySQL Database Class

+

11.2 MySQL Database Class

The MySQL database class has the following interface:

@@ -6860,7 +7148,7 @@ namespace odb

This constructor throws the odb::mysql::cli_exception exception if the MySQL option values are missing or invalid. - See section Section 10.4, "MySQL Exceptions" + See section Section 11.4, "MySQL Exceptions" for more information on this exception.

The static print_usage() function prints the list of options @@ -6884,7 +7172,7 @@ namespace odb handle, refer to the MySQL ODB runtime source code for the interface of the connection class.

-

10.3 MySQL Connection Factory

+

11.3 MySQL Connection Factory

The connection_factory abstract class has the following interface:

@@ -7026,7 +7314,7 @@ main (int argc, char* argv[]) } -

10.4 MySQL Exceptions

+

11.4 MySQL Exceptions

The MySQL ODB runtime library defines the following MySQL-specific exceptions:

@@ -7083,7 +7371,7 @@ namespace odb
-

11 SQLite Database

+

12 SQLite Database

To generate support code for the SQLite database you will need to pass the "--database sqlite" @@ -7092,12 +7380,12 @@ namespace odb library (libodb-sqlite). All SQLite-specific ODB classes are defined in the odb::sqlite namespace.

-

11.1 SQLite Type Mapping

+

12.1 SQLite Type Mapping

The following table summarizes the default mapping between basic C++ value types and SQLite database types. This mapping can be customized on the per-type and per-member basis using the ODB - Pragmas Language (Chapter 9, "ODB Pragma + Pragmas Language (Chapter 10, "ODB Pragma Language").

@@ -7191,7 +7479,7 @@ namespace odb a result, greater unsigned long long values will be represented in the database as negative values.

-

11.2 SQLite Database Class

+

12.2 SQLite Database Class

The SQLite database class has the following interface:

@@ -7296,7 +7584,7 @@ auto_ptr<odb::database> db (

The second constructor throws the odb::sqlite::cli_exception exception if the SQLite option values are missing or invalid. - See section Section 11.4, "SQLite Exceptions" + See section Section 12.4, "SQLite Exceptions" for more information on this exception.

The static print_usage() function prints the list of options @@ -7329,7 +7617,7 @@ auto_ptr<odb::database> db ( handle, refer to the SQLite ODB runtime source code for the interface of the connection class.

-

11.3 SQLite Connection Factory

+

12.3 SQLite Connection Factory

The connection_factory abstract class has the following interface:

@@ -7489,7 +7777,7 @@ main (int argc, char* argv[]) } -

11.4 SQLite Exceptions

+

12.4 SQLite Exceptions

The SQLite ODB runtime library defines the following SQLite-specific exceptions:

@@ -7542,12 +7830,12 @@ namespace odb of an error.

-

11.5 SQLite Limitations

+

12.5 SQLite Limitations

The following sections describe SQLite-specific limitations imposed by the current SQLite and ODB runtime versions.

-

11.5.1 Query Result Caching

+

12.5.1 Query Result Caching

SQLite ODB runtime implementation does not perform query result caching (Section 4.4, "Query Result") even when explicitly @@ -7562,17 +7850,17 @@ namespace odb thrown. Future versions of the SQLite ODB runtime library may add support for result caching.

-

11.5.2 Automatic Assignment of Object Ids

+

12.5.2 Automatic Assignment of Object Ids

Due to SQLite API limitations, every automatically assigned object id - (Section 9.3.2, "auto") should have + (Section 10.3.2, "auto") should have the INTEGER SQLite type. While SQLite will treat other integer type names (such as INT, BIGINT, etc.) as INTEGER, automatic id assignment will not work. By default, ODB maps all C++ integral types to INTEGER. This means that the only situation that requires consideration is the assignment of a custom database type using the db type pragma - (Section 9.3.3, "type"). For + (Section 10.3.3, "type"). For example:

@@ -7588,7 +7876,7 @@ class person
 };
-

11.5.3 Constraint Violations

+

12.5.3 Constraint Violations

Due to the granularity of the SQLite error codes, it is impossible to distinguish between the duplicate primary key and other constraint @@ -7597,7 +7885,7 @@ class person object_not_persistent exception (Section 3.11, "ODB Exceptions").

-

11.5.4 Sharing of Queries

+

12.5.4 Sharing of Queries

As discussed in Section 4.3, "Executing a Query", a query instance that does not have any by-reference parameters is @@ -7618,9 +7906,9 @@ class person and libraries. It consists of the following chapters.

- - - + + +
12Profiles Introduction
13Boost Profile
14Qt Profile
13Profiles Introduction
14Boost Profile
15Qt Profile
@@ -7628,7 +7916,7 @@ class person
-

12 Profiles Introduction

+

13 Profiles Introduction

ODB profiles are a generic mechanism for integrating ODB with widely-used C++ frameworks and libraries. A profile provides glue @@ -7682,7 +7970,7 @@ odb --profile boost/date-time ...

-

13 Boost Profile

+

14 Boost Profile

The ODB profile implementation for Boost is provided by the libodb-boost library and consists of multiple sub-profiles @@ -7707,7 +7995,7 @@ odb --profile boost/date-time ... that can be thrown by the Boost sub-profiles are described in the following sections.

-

13.1 Smart Pointers Library

+

14.1 Smart Pointers Library

The smart-ptr sub-profile provides persistence support for a subset of smart pointers from the Boost @@ -7760,7 +8048,7 @@ class employee behavior, add the --default-pointer option specifying the alternative object pointer after the --profile option.

-

13.2 Unordered Containers Library

+

14.2 Unordered Containers Library

The unordered sub-profile provides persistence support for the containers from the Boost unordered library. To enable @@ -7786,7 +8074,7 @@ class person }; -

13.3 Date Time Library

+

14.3 Date Time Library

The date-time sub-profile provides persistence support for a subset of types from the Boost date_time library. It is @@ -7859,7 +8147,7 @@ namespace odb exceptions are thrown are database system dependent and are discussed in more detail in the following sub-sections.

-

13.3.1 MySQL Database Type Mapping

+

14.3.1 MySQL Database Type Mapping

The following table summarizes the default mapping between the currently supported Boost date_time types and the MySQL database @@ -7895,7 +8183,7 @@ namespace odb support for mapping posix_time::ptime to the TIMESTAMP MySQL type. However, this mapping has to be explicitly requested using the db type pragma - (Section 9.3.3, "type"), as shown in + (Section 10.3.3, "type"), as shown in the following example:

@@ -7916,7 +8204,7 @@ class person
      the out_of_range exception.  Refer to the MySQL
      documentation for more information on the MySQL data type ranges.

 
-  
13.3.2 SQLite Database Type Mapping

+  
14.3.2 SQLite Database Type Mapping

 
   
The following table summarizes the default mapping between the currently
      supported Boost date_time types and the SQLite database
@@ -7955,7 +8243,7 @@ class person
      alternative mapping for posix_time::time_duration to the
      INTEGER type represents the duration as a number of
      seconds. These mappings have to be explicitly requested using the
-     db type pragma (Section 9.3.3,
+     db type pragma (Section 10.3.3,
      "type"), as shown in the following example:

 
 
@@ -7994,7 +8282,7 @@ class person
 
 
   

-  
14 Qt Profile

+  
15 Qt Profile

 
   
The ODB profile implementation for Qt is provided by the
      libodb-qt library and consists of multiple sub-profiles
@@ -8020,7 +8308,7 @@ class person
      that can be thrown by the Qt sub-profiles are described in the
      following sections.

 
-  
14.1 Basic Types

+  
15.1 Basic Types

 
   
The basic sub-profile provides persistence support for basic
      types defined by Qt. To enable only this profile, pass
@@ -8042,7 +8330,7 @@ class Person
 };
 

 
-  
14.1.1 MySQL Database Type Mapping

+  
15.1.1 MySQL Database Type Mapping

 
   
The following table summarizes the default mapping between the currently
      supported basic Qt types and the MySQL database types.

@@ -8077,7 +8365,7 @@ class Person
      it is mapped to TEXT.

 
 
-  
14.1.2 SQLite Database Type Mapping

+  
15.1.2 SQLite Database Type Mapping

 
   
The following table summarizes the default mapping between the currently
      supported basic Qt types and the SQLite database types.

@@ -8104,7 +8392,7 @@ class Person
      are stored as a NULL value if their isNull() member
      function returns true.

 
-  
14.2 Smart Pointers

+  
15.2 Smart Pointers

 
   
The smart-ptr sub-profile provides persistence support the
      Qt smart pointers. To enable only this profile, pass
@@ -8156,7 +8444,7 @@ class Employee
      behavior, add the --default-pointer option specifying the
      alternative object pointer after the --profile option.

 
-  
14.3 Containers Library

+  
15.3 Containers Library

 
   
The container sub-profile provides persistence support for
      Qt containers. To enable only this profile, pass
@@ -8181,7 +8469,7 @@ class Person
 };
-

14.4 Date Time Types

+

15.4 Date Time Types

The date-time sub-profile provides persistence support for the Qt date-time types. To enable only this profile, pass @@ -8234,7 +8522,7 @@ namespace odb system dependent and is discussed in more detail in the following sub-sections.

-

14.4.1 MySQL Database Type Mapping

+

15.4.1 MySQL Database Type Mapping

The following table summarizes the default mapping between the currently supported Qt date-time types and the MySQL database types.

@@ -8270,7 +8558,7 @@ namespace odb support for mapping QDateTime to the TIMESTAMP MySQL type. However, this mapping has to be explicitly requested using the db type pragma - (Section 9.3.3, "type"), as shown in + (Section 10.3.3, "type"), as shown in the following example:

@@ -8289,7 +8577,7 @@ class Person
      the MySQL documentation for more information on the MySQL data type
      ranges.

 
-  
14.4.2 SQLite Database Type Mapping

+  
15.4.2 SQLite Database Type Mapping

 
   
The following table summarizes the default mapping between the currently
      supported Qt date-time types and the SQLite database types.

@@ -8328,7 +8616,7 @@ class Person
      the INTEGER type represents a clock time as the number of
      seconds since midnight. These mappings have to be explicitly requested
      using the db type pragma
-     (Section 9.3.3,value "type"), as shown
+     (Section 10.3.3,value "type"), as shown
      in the following example:

 
 
-- 
cgit v1.1