From 276647c836adec33bee3e1cb16a37db47e872265 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Wed, 1 Aug 2012 14:41:33 +0200 Subject: Document new definition pragma --- doc/manual.xhtml | 201 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 157 insertions(+), 44 deletions(-) (limited to 'doc') diff --git a/doc/manual.xhtml b/doc/manual.xhtml index 700294c..155b0ac 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -458,6 +458,7 @@ for consistency. 12.1.8schema 12.1.9polymorphic 12.1.10session + 12.1.11definition @@ -469,6 +470,7 @@ for consistency. 12.2.3query 12.2.4pointer 12.2.5callback + 12.2.6definition @@ -481,19 +483,20 @@ for consistency. 12.3.4default 12.3.5options 12.3.6readonly - 12.3.7unordered - 12.3.8index_type - 12.3.9key_type - 12.3.10value_type - 12.3.11value_null/value_not_null - 12.3.12id_options - 12.3.13index_options - 12.3.14key_options - 12.3.15value_options - 12.3.16id_column - 12.3.17index_column - 12.3.18key_column - 12.3.19value_column + 12.3.7definition + 12.3.8unordered + 12.3.9index_type + 12.3.10key_type + 12.3.11value_type + 12.3.12value_null/value_not_null + 12.3.13id_options + 12.3.14index_options + 12.3.15key_options + 12.3.16value_options + 12.3.17id_column + 12.3.18index_column + 12.3.19key_column + 12.3.20value_column @@ -4643,7 +4646,7 @@ 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 12.3.7, + db unordered pragma (Section 12.3.8, "unordered", Section 12.4.16, "unordered"). For example:

@@ -9125,6 +9128,12 @@ class person 12.1.10 + + definition + definition location for a persistent class + 12.1.11 + +

12.1.1 table

@@ -9464,7 +9473,7 @@ private:

12.1.8 schema

The schema specifier specifies a database schema - that should be used for a persistent class.

+ that should be used for the persistent class.

In relational databases the term schema can refer to two related but ultimately different concepts. Normally it means a collection @@ -9685,14 +9694,14 @@ class employee

12.1.9 polymorphic

-

The polymorphic specifier specifies that a persistent +

The polymorphic specifier specifies that the persistent class is polymorphic. For more information on polymorphism support, refer to Chapter 8, "Inheritance".

12.1.10 session

The session specifier specifies whether to enable - session support for a persistent class. For example:

+ session support for the persistent class. For example:

 #pragma db object session        // Enable.
@@ -9721,6 +9730,20 @@ class employer
      For more information on sessions, refer to Chapter
      10, "Session".

 
+  
12.1.11 definition

+
+  
The definition specifier specifies an alternative
+     definition location for the persistent class. By
+     default, the ODB compiler generates the database support code for
+     a persistent class when we compile the header file that
+     defines this class. However, if the  definition
+     specifier is used, then the ODB compiler will instead generate
+     the database support code when we compile the header file
+     containing this pragma.

+
+  
For more information on this functionality, refer to
+     Section 12.3.7, "definition".

+
   
12.2 View Type Pragmas

 
   
A pragma with the view qualifier declares a C++ class
@@ -9766,6 +9789,12 @@ class employer
       12.2.5
     
 
+    
+      definition
+      definition location for a view
+      12.2.6
+    
+
   
 
   
For more information on view types refer to  Chapter 9,
@@ -9817,6 +9846,19 @@ class employer
      call in the case of a view are pre_load and
      post_load.

 
+  
12.2.6 definition

+
+  
The definition specifier specifies an alternative
+     definition location for the view class. By
+     default, the ODB compiler generates the database support code for
+     a view class when we compile the header file that
+     defines this class. However, if the  definition
+     specifier is used, then the ODB compiler will instead generate
+     the database support code when we compile the header file
+     containing this pragma.

+
+  
For more information on this functionality, refer to
+     Section 12.3.7, "definition".

 
   
12.3 Value Type Pragmas

 
@@ -9869,81 +9911,87 @@ class employer
     
 
     
+      definition
+      definition location for a composite value type
+      12.3.7
+    
+
+    
       unordered
       ordered container should be stored unordered
-      12.3.7
+      12.3.8
     
 
     
       index_type
       database type for a container's index type
-      12.3.8
+      12.3.9
     
 
     
       key_type
       database type for a container's key type
-      12.3.9
+      12.3.10
     
 
     
       value_type
       database type for a container's value type
-      12.3.10
+      12.3.11
     
 
     
       value_null/value_not_null
       container's value can/cannot be NULL
-      12.3.11
+      12.3.12
     
 
     
       id_options
       database options for a container's id column
-      12.3.12
+      12.3.13
     
 
     
       index_options
       database options for a container's index column
-      12.3.13
+      12.3.14
     
 
     
       key_options
       database options for a container's key column
-      12.3.14
+      12.3.15
     
 
     
       value_options
       database options for a container's value column
-      12.3.15
+      12.3.16
     
 
     
       id_column
       column name for a container's object id
-      12.3.16
+      12.3.17
     
 
     
       index_column
       column name for a container's index
-      12.3.17
+      12.3.18
     
 
     
       key_column
       column name for a container's key
-      12.3.18
+      12.3.19
     
 
     
       value_column
       column name for a container's value
-      12.3.19
+      12.3.20
     
 
   
@@ -10188,7 +10236,72 @@ class person_name
      as well as whole objects (Section 12.1.4,
      "readonly") as read-only.

 
-  
12.3.7 unordered

+  
12.3.7 definition

+
+  
The definition specifier specifies an alternative
+     definition location for the composite value type. By
+     default, the ODB compiler generates the database support code for
+     a composite value type when we compile the header file that
+     defines this value type. However, if the  definition
+     specifier is used, then the ODB compiler will instead generate
+     the database support code when we compile the header file containing
+     this pragma.

+
+  
This mechanism is primarily useful for converting third-party
+     types to ODB composite value types. In such cases we normally
+     cannot modify the header files to add the necessary pragmas.
+     It is also often inconvenient to compile these header files
+     with the ODB compiler. With the definition
+     specifier we can create a wrapper header that contains
+     the necessary pragmas and instructs the ODB compiler to generate
+     the database support code for a third-party type when we compile
+     the wrapper header. As an example, consider struct timeval
+     that is defined in the <sys/time.h> system header.
+     This type has the following (or similar) definition:

+
+  
+struct timeval
+{
+  long tv_sec;
+  long tv_usec;
+};
+  

+
+  
If we would like to make this type an ODB composite value type,
+     then we can create a wrapper header, for example
+     time-mapping.hxx, with the following content:

+
+  
+#ifndef TIME_MAPPING_HXX
+#define TIME_MAPPING_HXX
+
+#include <sys/time.h>
+
+#pragma db value(timeval) definition
+#pragma db member(timeval::tv_sec) column("sec")
+#pragma db member(timeval::tv_usec) column("usec")
+
+#endif // TIME_MAPPING_HXX
+  

+
+  
If we now compile this header with the ODB compiler, the
+     resulting time-mapping-odb.?xx files will
+     contain the database support code for struct timeval.
+     To use timeval in our persistent classes, we simply
+     include the time-mapping.hxx header:

+
+  
+#include <sys/time.h>
+#include "time-mapping.hxx"
+
+#pragma db object
+class object
+{
+  timeval timestamp;
+};
+  

+
+  
12.3.8 unordered

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

 
-  
12.3.8 index_type

+  
12.3.9 index_type

 
   
The index_type specifier specifies the native
      database type that should be used for an ordered container's
@@ -10219,7 +10332,7 @@ typedef std::vector<std::string> names;
 #pragma db value(names) index_type("SMALLINT UNSIGNED")
-

12.3.9 key_type

+

12.3.10 key_type

The key_type specifier specifies the native database type that should be used for a map container's @@ -10233,7 +10346,7 @@ typedef std::map<unsigned short, float> age_weight_map; #pragma db value(age_weight_map) key_type("INT UNSIGNED") -

12.3.10 value_type

+

12.3.11 value_type

The value_type specifier specifies the native database type that should be used for a container's @@ -10248,11 +10361,11 @@ typedef std::vector<std::string> names;

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

-

12.3.11 value_null/value_not_null

+

12.3.12 value_null/value_not_null

The value_null and value_not_null specifiers specify that a container type's element value can or cannot be @@ -10280,7 +10393,7 @@ typedef std::vector<shared_ptr<account> > accounts; as not allowing a NULL value.

-

12.3.12 id_options

+

12.3.13 id_options

The id_options specifier specifies additional column definition options that should be used for a container's @@ -10297,7 +10410,7 @@ typedef std::vector<std::string> nicknames; "id_options").

-

12.3.13 index_options

+

12.3.14 index_options

The index_options specifier specifies additional column definition options that should be used for a container's @@ -10314,7 +10427,7 @@ typedef std::vector<std::string> nicknames; "index_options").

-

12.3.14 key_options

+

12.3.15 key_options

The key_options specifier specifies additional column definition options that should be used for a container's @@ -10331,7 +10444,7 @@ typedef std::map<std::string, std::string> properties; "key_options").

-

12.3.15 value_options

+

12.3.16 value_options

The value_options specifier specifies additional column definition options that should be used for a container's @@ -10348,7 +10461,7 @@ typedef std::set<std::string> nicknames; "value_options").

-

12.3.16 id_column

+

12.3.17 id_column

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

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

-

12.3.17 index_column

+

12.3.18 index_column

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

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

-

12.3.18 key_column

+

12.3.19 key_column

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

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

-

12.3.19 value_column

+

12.3.20 value_column

The value_column specifier specifies the column name that should be used to store the element value in a -- cgit v1.1