From 9aab700d7fa01d0e6d2614ec22450241807b81be Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Mon, 29 Nov 2010 15:31:32 +0200 Subject: Update ODB Pragma Language chapter with new pragmas --- doc/manual.xhtml | 634 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 611 insertions(+), 23 deletions(-) diff --git a/doc/manual.xhtml b/doc/manual.xhtml index fbfb587..e14fdc7 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -181,7 +181,7 @@ for consistency. } /* specifiers table */ - #specifiers { + .specifiers { margin: 2em 0 2em 0; border-collapse : collapse; @@ -192,16 +192,16 @@ for consistency. line-height : 14px; } - #specifiers th, #specifiers td { + .specifiers th, .specifiers td { border: 1px solid; padding : 0.9em 0.9em 0.7em 0.9em; } - #specifiers th { + .specifiers th { background : #cde8f6; } - #specifiers td { + .specifiers td { text-align: left; } @@ -340,6 +340,7 @@ for consistency. 5.2Object Type Pragmas +
5.2.1table
5.2.2pointer
@@ -347,6 +348,14 @@ for consistency. 5.3Value Type Pragmas + + + + + + + +
5.3.1type
5.3.2unordered
5.3.3index_type
5.3.4key_type
5.3.5value_type
5.3.6id_column
5.3.7index_column
5.3.8key_column
5.3.9value_column
@@ -358,6 +367,16 @@ for consistency. 5.4.3type 5.4.4column 5.4.5transient + 5.4.6inverse + 5.4.7unordered + 5.4.8table + 5.4.9index_type + 5.4.10key_type + 5.4.11value_type + 5.4.12id_column + 5.4.13index_column + 5.4.14key_column + 5.4.15value_column @@ -3067,13 +3086,36 @@ xlC -qsuppress=1540-1401 ...

5.2 Object Type Pragmas

A pragma with the object qualifier declares a C++ class - as a persistent object type. The qualifier can be optionally followed - by the table specifier.

+ as a persistent object type. The qualifier can be optionally followed, + in any order, by one or more specifiers summarized in the table below:

+ + + + + + + + + + + + + + + + + + + + + +
SpecifierSummarySection
tablethe table name for the persistent class5.2.1
pointerthe pointer type for the persistent class5.2.2
+

5.2.1 table

The table specifier specifies the table name that should - be used to store objects of this class in a relational database. For + be used to store objects of the class in a relational database. For example:

@@ -3087,11 +3129,135 @@ class person
   
If the table name is not specified, the class name is used as the
      table name.

 
+  
5.2.2 pointer

+
+  
The pointer specifier specifies the pointer type for
+     the persistent class. The pointer type is used to return and pass
+     dynamically allocated instances of the persistent class in the
+     database operations. For example:

+
+  
+#pragma db object pointer(std::tr1::shared_ptr<person>)
+class person
+{
+  ...
+};
+  

+
+  
There are several ways to specify an object pointer with the
+     pointer specifier. You can use a complete pointer
+     type as shown in the example above. Alternatively, you can
+     specify only the template name of a smart pointer in which
+     case the ODB compiler will automatically append the class
+     name as a template argument. The following example is
+     equivalent to the one above:

+
+  
+#pragma db object pointer(std::tr1::shared_ptr)
+class person
+{
+  ...
+};
+  

+
+  
If you would like to use a naked pointer as an object pointer,
+     you can use * as a shortcut:

+
+  
+#pragma db object pointer(*) // Same as pointer(person*)
+class person
+{
+  ...
+};
+  

+
+  
If a pointer type is not explicitly specified, the default
+     pointer, specified with the --default-pointer
+     ODB compiler option, is used. If this option is not specified
+     either, then the naked pointer is used by default.

+
+  
For additional information on object pointers, refer to
+     Section @@, "".

+
   
5.3 Value Type Pragmas

 
   
A pragma with the value qualifier describes a value
-     type and can be optionally followed by the type
-     specifier.

+     type. It can be optionally followed, in any order, by one or more
+     specifiers summarized in the table below:

+
+  
+  
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+  
SpecifierSummarySection
typethe database type for the value type5.3.1
unorderedordered container should be stored unordered5.3.2
index_typethe database type for the container's index type5.3.3
key_typethe database type for the container's key type5.3.4
value_typethe database type for the container's value type5.3.5
id_columnthe column name for the container's table object id5.3.6
index_columnthe column name for the container's table index5.3.7
key_columnthe column name for the container's table key5.3.8
value_columnthe column name for the container's table value5.3.9

+
+  
Many of the value type specifiers have corresponding member type
+     specifiers with the same names (see Section 5.4,
+     "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
+     members of this value type that don't have a pre-member version
+     of the specifier. While the member specifier always applies only
+     to a single member. In other words, member specifiers take precedence
+     over values specified with value specifiers.

 
   
5.3.1 type

 
@@ -3141,9 +3307,119 @@ private:
      mapping example in the odb-examples
      package shows how to do this for all the supported database systems.

 
-  
It is also possible to change the database type mapping for individual
-     members, as described in Section 5.4, "Data Member
-     Pragmas".

+  
5.3.2 unordered

+
+  
The unordered specifier specifies that the ordered
+     container should be stored in the database unordered. The database
+     table for such a container will not contain the index column
+     and the order in which elements are retrieved from the database may
+     not be the same as the order in which they were stored. For example:

+
+  
+typedef std::vector<std::string> names;
+#pragma db value(names) unordered
+  

+
+  
5.3.3 index_type

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

+
+  
+typedef std::vector<std::string> names;
+#pragma db value(names) index_type("SMALLINT UNSIGNED NOT NULL")
+  

+
+  
5.3.4 key_type

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

+
+  
+typedef std::map<unsigned short, double> age_weight_map;
+#pragma db value(age_weight_map) key_type("INT UNSIGNED NOT NULL")
+  

+
+  
5.3.5 value_type

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

+
+  
+typedef std::vector<std::string> names;
+#pragma db value(names) value_type("VARCHAR(255) NOT NULL")
+  

+
+  
5.3.6 id_column

+
+  
The id_column specifier specifies the column
+     name that should be used to store the object id in the
+     container's table. For example:

+
+  
+typedef std::vector<std::string> names;
+#pragma db value(names) id_column("id")
+  

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

+
+  
5.3.7 index_column

+
+  
The index_column specifier specifies the column
+     name that should be used to store the element index in the
+     ordered container's table. For example:

+
+  
+typedef std::vector<std::string> names;
+#pragma db value(names) index_column("name_number")
+  

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

+
+  
5.3.8 key_column

+
+  
The key_column specifier specifies the column
+     name that should be used to store the key in the map
+     container's table. For example:

+
+  
+typedef std::map<unsigned short, double> age_weight_map;
+#pragma db value(age_weight_map) key_column("age")
+  

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

+
+  
5.3.9 value_column

+
+  
The value_column specifier specifies the column
+     name that should be used to store the element value in the
+     container's table. For example:

+
+  
+typedef std::map<unsigned short, double> age_weight_map;
+#pragma db value(age_weight_map) value_column("weight")
+  

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

+
+  
+
 
   
5.4 Data Member Pragmas

 
@@ -3153,7 +3429,7 @@ private:
      summarized in the table below:

 
   
-  
+  

@@ -3190,8 +3466,79 @@ private:
       
 
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
+    
+      
+      
+      
+    
+
   

     

       Specifier
       Summary5.4.5
     
inversethe member is an inverse side of a bidirectional relationship5.4.6
unorderedordered container should be stored unordered5.4.7
tablethe table name for the container5.4.8
index_typethe database type for the container's index type5.4.9
key_typethe database type for the container's key type5.4.10
value_typethe database type for the container's value type5.4.11
id_columnthe column name for the container's table object id5.4.12
index_columnthe column name for the container's table index5.4.13
key_columnthe column name for the container's table key5.4.14
value_columnthe column name for the container's table value5.4.15

 
+  
Many of the member specifiers have corresponding value type
+     specifiers with the same names (see Section 5.3,
+     "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
+     members of this value type that don't have a pre-member version
+     of the specifier. While the member specifier always applies only
+     to a single member. In other words, member specifiers take precedence
+     over values specified with value specifiers.

+
   
5.4.1 id

 
   
The id specifier specifies that the data member contains
@@ -3244,7 +3591,7 @@ private:
   
5.4.3 type

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

+     that should be used for the data member. For example:

 
   
 #pragma db object
@@ -3258,18 +3605,10 @@ private:
 };
   

 
-  
The behavior of this specifier for members is similar to that
-     for value types. The only difference is the scope. The value
-     type pragma applies to all members with this value type that
-     don't have their own type specifiers, while the
-     member pragma applies only to a single member. For more
-     information on the semantics of this specifier, refer to
-     Section 5.3, "Value Type Pragmas".

-
   
5.4.4 column

 
   
The column specifier specifies the column name
-     that should be used to store this member in a relational database.
+     that should be used to store the member in a relational database.
      For example:

 
   
@@ -3311,6 +3650,255 @@ private:
      references that are only meaningful in the application's
      memory, as well as utility members such as mutexes, etc.

 
+  
5.4.6 inverse

+
+  
The inverse specifier specifies that the member of
+     a pointer or a container of pointers type is an inverse side of
+     a bidirectional object relationship. The single required argument
+     to this specifier is the data member name in the referenced object.
+     For example:

+
+
+using std::tr1::shared_ptr;
+using std::tr1::weak_ptr;
+
+class person;
+
+#pragma db object pointer(shared_ptr)
+class employer
+{
+  ...
+private:
+  std::vector<shared_ptr<person> > employees_;
+  ...
+};
+
+#pragma db object pointer(shared_ptr)
+class person
+{
+  ...
+private:
+  #pragma db inverse(employee_)
+  weak_ptr<employer> employer_;
+  ...
+};
+  

+
+  
An inverse member does not have a corresponding column or table in
+     the resulting database schema. Instead, the column or table from
+     the referenced object is used to retrieve the 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 (see
+     Section 5.4.7, "unordered").

+
+  
5.4.7 unordered

+
+  
The unordered specifier specifies that the member of
+     an ordered container type should be stored in the database unordered.
+     The database table for such a member will not contain the index column
+     and the order in which elements are retrieved from the database may
+     not be the same as the order in which they were stored. For example:

+
+  
+#pragma db object
+class person
+{
+  ...
+private:
+  #pragma db unordered
+  std::vector<std::string> nicknames_;
+  ...
+};
+  

+
+  
5.4.8 table

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

+
+  
+#pragma db object
+class person
+{
+  ...
+private:
+  #pragma db table("nicknames")
+  std::vector<std::string> nicknames_;
+  ...
+};
+  

+
+  
If the table name is not specified, then the container table name
+     is constructed by concatenating the object's table name, underscore,
+     and the sanitized member name. The sanitized member name is obtained
+     by removing the common member name decorations, such as leading and
+     trailing underscores, the m_ prefix, etc. In the example
+     above, without the table specifier, the container's
+     table name would have been person_nicknames.

+
+  
5.4.9 index_type

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

+
+  
+#pragma db object
+class person
+{
+  ...
+private:
+  #pragma db index_type("SMALLINT UNSIGNED NOT NULL")
+  std::vector<std::string> nicknames_;
+  ...
+};
+  

+
+  
5.4.10 key_type

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

+
+  
+#pragma db object
+class person
+{
+  ...
+private:
+  #pragma db key_type("INT UNSIGNED NOT NULL")
+  std::map<unsigned short, double> age_weight_map_;
+  ...
+};
+  

+
+  
5.4.11 value_type

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

+
+  
+#pragma db object
+class person
+{
+  ...
+private:
+  #pragma db value_type("VARCHAR(255) NOT NULL")
+  std::vector<std::string> nicknames_;
+  ...
+};
+  

+
+  
5.4.12 id_column

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

+
+  
+#pragma db object
+class person
+{
+  ...
+private:
+  #pragma db id_column("person_id")
+  std::vector<std::string> nicknames_;
+  ...
+};
+  

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

+
+  
5.4.13 index_column

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

+
+  
+#pragma db object
+class person
+{
+  ...
+private:
+  #pragma db index_column("nickname_number")
+  std::vector<std::string> nicknames_;
+  ...
+};
+  

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

+
+  
5.4.14 key_column

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

+
+  
+#pragma db object
+class person
+{
+  ...
+private:
+  #pragma db key_column("age")
+  std::map<unsigned short, double> age_weight_map_;
+  ...
+};
+  

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

+
+  
5.4.15 value_column

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

+
+  
+#pragma db object
+class person
+{
+  ...
+private:
+  #pragma db value_column("weight")
+  std::map<unsigned short, double> age_weight_map_;
+  ...
+};
+  

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

 
   
 
-- 
cgit v1.1