From 3a1eed21d4d5d0e7f6a9f400420fdc28d7be9b61 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Fri, 17 Feb 2012 10:08:18 +0200 Subject: Add support for composite object ids New pragma id_type (member). New test: common/composite-id. The composite example has also been updated. --- doc/manual.xhtml | 330 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 202 insertions(+), 128 deletions(-) (limited to 'doc') diff --git a/doc/manual.xhtml b/doc/manual.xhtml index 64d96f8..30f4901 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -390,7 +390,8 @@ for consistency. 7.2Composite Value Types - + +
7.2.1Composite Value Column and Table Names
7.2.1Composite Object Ids
7.2.2Composite Value Column and Table Names
@@ -492,29 +493,30 @@ for consistency. 12.4.1id 12.4.2auto 12.4.3type - 12.4.4null/not_null - 12.4.5default - 12.4.6options - 12.4.7column (object, composite value) - 12.4.8column (view) - 12.4.9transient - 12.4.10readonly - 12.4.11inverse - 12.4.12version - 12.4.13unordered - 12.4.14table - 12.4.15index_type - 12.4.16key_type - 12.4.17value_type - 12.4.18value_null/value_not_null - 12.4.19id_options - 12.4.20index_options - 12.4.21key_options - 12.4.22value_options - 12.4.23id_column - 12.4.24index_column - 12.4.25key_column - 12.4.26value_column + 12.4.4id_type + 12.4.5null/not_null + 12.4.6default + 12.4.7options + 12.4.8column (object, composite value) + 12.4.9column (view) + 12.4.10transient + 12.4.11readonly + 12.4.12inverse + 12.4.13version + 12.4.14unordered + 12.4.15table + 12.4.16index_type + 12.4.17key_type + 12.4.18value_type + 12.4.19value_null/value_not_null + 12.4.20id_options + 12.4.21index_options + 12.4.22key_options + 12.4.23value_options + 12.4.24id_column + 12.4.25index_column + 12.4.26key_column + 12.4.27value_column @@ -870,7 +872,7 @@ for consistency. object state in binary format instead of text which reduces the load on the application and the database server. Extensive caching of connections, prepared statements, and buffers saves - time and resources on connection establishment, statement parsing + time and resources on connection establishment, statement parsing, and memory allocations. For each supported database system the native C API is used instead of ODBC or higher-level wrapper APIs to reduce overhead and provide the most efficient implementation @@ -2157,8 +2159,11 @@ class person without the default constructor. However, in this case, the database operations can only load the persistent state into an existing instance (Section 3.8, "Loading Persistent Objects", - Section 4.4, "Query Result").

The object id type - should be default-constructible.

+ Section 4.4, "Query Result").

+ +

The object id can be of a simple or composite (Section + 7.2.1, "Composite Object Ids") value type which should be + default-constructible.

If an object class has private or protected non-transient data members or if its default constructor is not public, then the @@ -3140,7 +3145,7 @@ t.commit (); data members can be declared read-only (see Section 12.1.4, "readonly (object)", Section 12.3.6, "readonly (composite value)", and - Section 12.4.10, "readonly + Section 12.4.11, "readonly (data member)").

If an individual data member is declared read-only, then @@ -4446,7 +4451,7 @@ private: 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 12.3.7, - "unordered", Section 12.4.13, + "unordered", Section 12.4.14, "unordered"). For example:

@@ -4696,11 +4701,11 @@ class employee
 
   
By default, an object pointer can be NULL. To
      specify that a pointer always points to a valid object we can
-     use the not_null pragma (Section
-     12.4.4, "null/not_null") for
+     use the not_null pragma (Section
+     12.4.5, "null/not_null") for
      single object pointers and the value_not_null pragma
-     (Section
-     12.4.18, "value_null/value_not_null")
+     (Section
+     12.4.19, "value_null/value_not_null")
      for containers of object pointers. For example:

 
   
@@ -5069,7 +5074,7 @@ CREATE TABLE employee (
      of these references.

 
   
To eliminate redundant database schema references we can use the
-     inverse pragma (Section 12.4.11,
+     inverse pragma (Section 12.4.12,
      "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:

@@ -5113,7 +5118,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 12.4.13, "unordered")
+     (Section 12.4.14, "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).

@@ -5859,12 +5864,42 @@ result r (db.query<person> (
 t.commit ();
   

 
-  
7.2.1 Composite Value Column and Table Names

+  
7.2.1 Composite Object Ids

+
+  
An object id can be of a composite value type, for example:

+
+  
+#pragma db value
+class name
+{
+  ...
+
+  std::string first_;
+  std::string last_;
+};
+
+#pragma db object
+class person
+{
+  ...
+
+  #pragma db id
+  name name_;
+};
+  

+
+  
However, a value type that can be used as an object id has a number
+     of restrictions. Such a value type cannot have container, object
+     pointer, or read-only data members. It also must be
+     default-constructible and implement the less-than comparison operator
+     (operator<).

+
+  
7.2.2 Composite Value Column and Table Names

 
   
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
-     12.4.7, "column"). For composite value
+     the db column pragma (Section
+     12.4.8, "column"). For composite value
      types things are slightly more complex since they are mapped to
      multiple columns. Consider the following example:

 
@@ -5965,9 +6000,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 12.4.26, "value_column") or
+     (Section 12.4.27, "value_column") or
      db key_column
-     (Section 12.4.25, "key_column")
+     (Section 12.4.26, "key_column")
      pragmas are used to specify the column prefix.

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

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

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

 #pragma db value
@@ -6053,7 +6088,7 @@ CREATE TABLE person_nickname (
      of a valid value in a column. While by default ODB maps
      values to columns that do not allow NULL values,
      it is possible to change that with the db null
-     pragma (Section 12.4.4,
+     pragma (Section 12.4.5,
      "null/not_null").

 
   
To properly support the NULL semantics, the
@@ -6804,7 +6839,7 @@ struct employee_birth_code
      or the match is ambiguous, the ODB compiler will issue an error.
      To associate two differently-named members or to resolve an ambiguity,
      we can explicitly specify the member association using the
-     db column pragma (Section 12.4.7,
+     db column pragma (Section 12.4.8,
      "column"). For example:

 
   
@@ -7822,7 +7857,7 @@ p.age (age);
   
To declare a persistent class with the optimistic concurrency model we
      use the optimistic pragma (Section 12.1.5,
      "optimistic"). We also use the version
-     pragma (Section 12.4.12, "version")
+     pragma (Section 12.4.13, "version")
      to specify which data member will store the object version. For
      example:

 
@@ -8402,7 +8437,7 @@ class person
      read-only while the rest is treated as read-write.

 
   
Note that it is also possible to declare individual data members
-    (Section 12.4.10, "readonly")
+    (Section 12.4.11, "readonly")
      as well as composite value types (Section 12.3.6,
      "readonly") as read-only.

 
@@ -8412,7 +8447,7 @@ class person
      has the optimistic concurrency model. A class with the optimistic
      concurrency model must also specify the data member that is used to
      store the object version using the version pragma
-     (Section 12.4.12, "version").
+     (Section 12.4.13, "version").
      For example:

 
   
@@ -8794,8 +8829,8 @@ class employee
 
   
The standard syntax for qualified names used in the
      schema and table specifiers as well
-     as the view column specifier (Section
-     12.4.8, "column (view)") has the
+     as the view column specifier (Section
+     12.4.9, "column (view)") has the
      "name.name..."
      form where, as discussed above, the leading name component
      can be empty to denote a fully qualified name. This form, however,
@@ -9181,7 +9216,7 @@ typedef shared_ptr<person> person_ptr;
   

 
   
The NULL semantics can also be specified on the
-     per-member basis (Section 12.4.4,
+     per-member basis (Section 12.4.5,
      "null/not_null"). If both a type and
      a member have null/not_null specifiers,
      then the member specifier takes precedence. If a member specifier
@@ -9234,7 +9269,7 @@ class person
 
   
The semantics of the default specifier for a value type
      are similar to those of the default specifier for a
-     data member (Section 12.4.5,
+     data member (Section 12.4.6,
      "default").

 
   
12.3.5 options

@@ -9257,7 +9292,7 @@ class person
 
   
The semantics of the options specifier for a value type
      are similar to those of the options specifier for a
-     data member (Section 12.4.6,
+     data member (Section 12.4.7,
      "options").

 
   
12.3.6 readonly

@@ -9286,7 +9321,7 @@ class person_name
      read-only while the rest is treated as read-write.

 
   
Note that it is also possible to declare individual data members
-     (Section 12.4.10, "readonly")
+     (Section 12.4.11, "readonly")
      as well as whole objects (Section 12.1.4,
      "readonly") as read-only.

 
@@ -9395,7 +9430,7 @@ typedef std::vector<std::string> nicknames;
 
   
The semantics of the id_options specifier for a container
      type are similar to those of the id_options specifier for
-     a container data member (Section 12.4.19,
+     a container data member (Section 12.4.20,
      "id_options").

 
 
@@ -9412,7 +9447,7 @@ typedef std::vector<std::string> nicknames;
 
   
The semantics of the index_options specifier for a container
      type are similar to those of the index_options specifier for
-     a container data member (Section 12.4.20,
+     a container data member (Section 12.4.21,
      "index_options").

 
 
@@ -9429,7 +9464,7 @@ typedef std::map<std::string, std::string> properties;
 
   
The semantics of the key_options specifier for a container
      type are similar to those of the key_options specifier for
-     a container data member (Section 12.4.21,
+     a container data member (Section 12.4.22,
      "key_options").

 
 
@@ -9446,7 +9481,7 @@ typedef std::set<std::string> nicknames;
 
   
The semantics of the value_options specifier for a container
      type are similar to those of the value_options specifier for
-     a container data member (Section 12.4.22,
+     a container data member (Section 12.4.23,
      "value_options").

 
 
@@ -9543,141 +9578,147 @@ typedef std::map<unsigned short, float> age_weight_map;
     
 
     
+      id_type
+      database type for a member when used as an object id
+      12.4.4
+    
+
+    
       null/not_null
       member can/cannot be NULL
-      12.4.4
+      12.4.5
     
 
     
       default
       default value for a member
-      12.4.5
+      12.4.6
     
 
     
       options
       database options for a member
-      12.4.6
+      12.4.7
     
 
     
       column
       column name for a member of an object or composite value
-      12.4.7
+      12.4.8
     
 
     
       column
       column name for a member of a view
-      12.4.8
+      12.4.9
     
 
     
       transient
       member is not stored in the database
-      12.4.9
+      12.4.10
     
 
     
       readonly
       member is read-only
-      12.4.10
+      12.4.11
     
 
     
       inverse
       member is an inverse side of a bidirectional relationship
-      12.4.11
+      12.4.12
     
 
     
       version
       member stores object version
-      12.4.12
+      12.4.13
     
 
     
       unordered
       ordered container should be stored unordered
-      12.4.13
+      12.4.14
     
 
     
       table
       table name for a container
-      12.4.14
+      12.4.15
     
 
     
       index_type
       database type for a container's index type
-      12.4.15
+      12.4.16
     
 
     
       key_type
       database type for a container's key type
-      12.4.16
+      12.4.17
     
 
     
       value_type
       database type for a container's value type
-      12.4.17
+      12.4.18
     
 
     
       value_null/value_not_null
       container's value can/cannot be NULL
-      12.4.18
+      12.4.19
     
 
     
       id_options
       database options for a container's id column
-      12.4.19
+      12.4.20
     
 
     
       index_options
       database options for a container's index column
-      12.4.20
+      12.4.21
     
 
     
       key_options
       database options for a container's key column
-      12.4.21
+      12.4.22
     
 
     
       value_options
       database options for a container's value column
-      12.4.22
+      12.4.23
     
 
     
       id_column
       column name for a container's object id
-      12.4.23
+      12.4.24
     
 
     
       index_column
       column name for a container's index
-      12.4.24
+      12.4.25
     
 
     
       key_column
       column name for a container's key
-      12.4.25
+      12.4.26
     
 
     
       value_column
       column name for a container's value
-      12.4.26
+      12.4.27
     
 
   
@@ -9764,11 +9805,44 @@ class person
 };
   

 
-  
The null and not_null (Section
-     12.4.4, "null/not_null") specifiers
+  
The null and not_null (Section
+     12.4.5, "null/not_null") specifiers
      can be used to control the NULL semantics of a data member.

 
-  
12.4.4 null/not_null

+  
12.4.4 id_type

+
+  
The type specifier specifies the native database type
+     that should be used for a data member when it is part of an
+     object identifier. This specifier only makes sense when applied to
+     a member of a composite value type that is used for both id and
+     non-id members. For example:

+
+  
+#pragma db value
+class name
+{
+  ...
+
+  #pragma db type("VARCHAR(256)") id_type("VARCHAR(64)")
+  std::string first_;
+
+  #pragma db type("VARCHAR(256)") id_type("VARCHAR(64)")
+  std::string last_;
+};
+
+#pragma db object
+class person
+{
+  ...
+
+  #pragma db id
+  name name_;  // name_.first_, name_.last_ mapped to VARCHAR(64)
+
+  name alias_; // alias_.first_, alias_.last_ mapped to VARCHAR(256)
+};
+  

+
+  
12.4.5 null/not_null

 
   
The null and not_null specifiers specify that
      a data member can or cannot be NULL, respectively.
@@ -9823,7 +9897,7 @@ class account
      discussion of the NULL semantics for object pointers,
      refer to Chapter 6, "Relationships".

 
-  
12.4.5 default

+  
12.4.6 default

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

@@ -9844,8 +9918,8 @@ class person
      an integer literal, a floating point literal, a string literal, or
      an enumerator name. If you need to specify a default value that is
      an expression, for example an SQL function call, then you can use
-     the options specifier (Section
-     12.4.6, "options") instead. For example:

+     the options specifier (Section
+     12.4.7, "options") instead. For example:

 
   
 enum gender {male, female, undisclosed};
@@ -9931,7 +10005,7 @@ class person
   
Additionally, the default specifier cannot be specified
      for view data members.

 
-  
12.4.6 options

+  
12.4.7 options

 
   
The options specifier specifies additional column
      definition options that should be used for a data member. For
@@ -9979,9 +10053,9 @@ class person
 
   
ODB provides dedicated specifiers for specifying column types
      (Section 12.4.3, "type"),
-     NULL constraints (Section 12.4.4,
+     NULL constraints (Section 12.4.5,
      "null/not_null"), and default
-     values (Section 12.4.5, "default").
+     values (Section 12.4.6, "default").
      For ODB to function correctly these specifiers should always be
      used instead of the opaque options specifier for
      these components of a column definition.

@@ -9989,7 +10063,7 @@ class person
   
Note also that the options specifier cannot be specified
      for view data members.

 
-  
12.4.7 column (object, composite value)

+  
12.4.8 column (object, composite value)

 
   
The column specifier specifies the column name
      that should be used to store a data member of a persistent class
@@ -10007,7 +10081,7 @@ class person
   

 
   
For a member of a composite value type, the column specifier
-     specifies the column name prefix. Refer to Section 7.2.1,
+     specifies the column name prefix. Refer to Section 7.2.2,
      "Composite Value Column and Table Names" for details.

 
   
If the column name is not specified, it is derived from the member's
@@ -10015,7 +10089,7 @@ class person
      the common data member name decorations, such as leading and trailing
      underscores, the m_ prefix, etc.

 
-  
12.4.8 column (view)

+  
12.4.9 column (view)

 
   
The column specifier can be used to specify the associated
      object data member, the potentially qualified column name, or the column
@@ -10023,7 +10097,7 @@ class person
      refer to Section 9.1, "Object Views" and
      Section 9.2, "Table Views".

 
-  
12.4.9 transient

+  
12.4.10 transient

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

@@ -10045,7 +10119,7 @@ class person
      references that are only meaningful in the application's
      memory, as well as utility members such as mutexes, etc.

 
-  
12.4.10 readonly

+  
12.4.11 readonly

 
   
The readonly specifier specifies that a data member of
      an object or composite value type is read-only. Changes to a read-only
@@ -10054,7 +10128,7 @@ class person
      containing such a member. Since views are read-only, it is not
      necessary to use this specifier for view data members. Object id
      (Section 12.4.1, "id")
-     and inverse (Section 12.4.11,
+     and inverse (Section 12.4.12,
      "inverse") data members are automatically treated
      as read-only and must not be explicitly declared as such. For
      example:

@@ -10138,7 +10212,7 @@ class person
      as well as whole objects (Section 12.1.4,
      "readonly") as read-only.

 
-  
12.4.11 inverse

+  
12.4.12 inverse

 
   
The inverse specifier specifies that a data member of
      an object pointer or a container of object pointers type is an
@@ -10176,12 +10250,12 @@ class person
      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 12.4.13, "unordered").

+     (Section 12.4.14, "unordered").

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

 
-  
12.4.12 version

+  
12.4.13 version

 
   
The version specifier specifies that the data member stores
      the object version used to support optimistic concurrency.  If a class
@@ -10211,7 +10285,7 @@ class person
   
For a more detailed discussion of optimistic concurrency, refer to
      Chapter 11, "Optimistic Concurrency".

 
-  
12.4.13 unordered

+  
12.4.14 unordered

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

 
-  
12.4.14 table

+  
12.4.15 table

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

@@ -10261,7 +10335,7 @@ class person
   
The table specifier can also be used for members of
      composite value types. In this case it specifies the table name
      prefix for container members inside the composite value type. Refer
-     to Section 7.2.1, "Composite Value Column and Table
+     to Section 7.2.2, "Composite Value Column and Table
      Names" for details.

 
   
The container table name can be qualified with a database
@@ -10282,7 +10356,7 @@ class person
      qualified names, refer to Section 12.1.8,
      "schema".

 
-  
12.4.15 index_type

+  
12.4.16 index_type

 
   
The index_type specifier specifies the native
      database type that should be used for an ordered container's
@@ -10302,7 +10376,7 @@ class person
 };
-

12.4.16 key_type

+

12.4.17 key_type

The key_type specifier specifies the native database type that should be used for a map container's @@ -10322,7 +10396,7 @@ class person }; -

12.4.17 value_type

+

12.4.18 value_type

The value_type specifier specifies the native database type that should be used for a container's @@ -10343,18 +10417,18 @@ class person

The value_null and value_not_null - (Section 12.4.18, + (Section 12.4.19, "value_null/value_not_null") specifiers can be used to control the NULL semantics of a value column.

-

12.4.18 value_null/value_not_null

+

12.4.19 value_null/value_not_null

The value_null and value_not_null specifiers specify that a container's element value for a data member can or cannot be NULL, respectively. The semantics of value_null and value_not_null are similar to those of the null and not_null specifiers - (Section 12.4.4, "null/not_null"). + (Section 12.4.5, "null/not_null"). For example:

@@ -10380,7 +10454,7 @@ class account
      Multiset Containers") the element value is automatically treated
      as not allowing a NULL value.

 
-  
12.4.19 id_options

+  
12.4.20 id_options

 
   
The id_options specifier specifies additional
      column definition options that should be used for a container's
@@ -10401,10 +10475,10 @@ class person

The semantics of id_options are similar to those - of the options specifier (Section - 12.4.6, "options").

+ of the options specifier (Section + 12.4.7, "options").

-

12.4.20 index_options

+

12.4.21 index_options

The index_options specifier specifies additional column definition options that should be used for a container's @@ -10422,10 +10496,10 @@ class person

The semantics of index_options are similar to those - of the options specifier (Section - 12.4.6, "options").

+ of the options specifier (Section + 12.4.7, "options").

-

12.4.21 key_options

+

12.4.22 key_options

The key_options specifier specifies additional column definition options that should be used for a container's @@ -10443,10 +10517,10 @@ class person

The semantics of key_options are similar to those - of the options specifier (Section - 12.4.6, "options").

+ of the options specifier (Section + 12.4.7, "options").

-

12.4.22 value_options

+

12.4.23 value_options

The value_options specifier specifies additional column definition options that should be used for a container's @@ -10464,17 +10538,17 @@ class person

The semantics of value_options are similar to those - of the options specifier (Section - 12.4.6, "options").

+ of the options specifier (Section + 12.4.7, "options").

-

12.4.23 id_column

+

12.4.24 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 those of the column specifier - (Section 12.4.7, "column"). + (Section 12.4.8, "column"). For example:

@@ -10491,14 +10565,14 @@ class person
   
If the column name is not specified, then object_id
      is used by default.

 
-  
12.4.24 index_column

+  
12.4.25 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 those of the
      column specifier
-     (Section 12.4.7, "column").
+     (Section 12.4.8, "column").
      For example:

 
   
@@ -10515,14 +10589,14 @@ class person
   
If the column name is not specified, then index
      is used by default.

 
-  
12.4.25 key_column

+  
12.4.26 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 those of the
      column specifier
-     (Section 12.4.7, "column").
+     (Section 12.4.8, "column").
      For example:

 
   
@@ -10539,14 +10613,14 @@ class person
   
If the column name is not specified, then key
      is used by default.

 
-  
12.4.26 value_column

+  
12.4.27 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 those of the
      column specifier
-     (Section 12.4.7, "column").
+     (Section 12.4.8, "column").
      For example:

 
   
@@ -12885,7 +12959,7 @@ SHOW integer_datetimes
      in the generated schema, columns of these types are always
      declared as NULL, even if explicitly declared as
      NOT NULL with the db not_null pragma
-     (Section 12.4.4, "null/not_null").

+     (Section 12.4.5, "null/not_null").

 
   
The Oracle ODB runtime library also provides support for mapping the
      std::string type to the Oracle CHAR,
-- 
cgit v1.1