From 96deed4d2ef7d23b6015c1564866b3e60519d57c Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Mon, 5 Mar 2012 16:07:54 +0200 Subject: Document new namespace-level pragmas (table, pointer) --- doc/manual.xhtml | 272 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 232 insertions(+), 40 deletions(-) (limited to 'doc') diff --git a/doc/manual.xhtml b/doc/manual.xhtml index 5060268..a36481d 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -524,7 +524,9 @@ for consistency. 12.5Namespace Pragmas - + + +
12.5.1schema
12.5.1pointer
12.5.2table
12.5.3schema
@@ -2298,17 +2300,47 @@ class name to use a smart pointer for a returned object or view, as well as to simplify the use of more advanced ODB functionality, such as sessions and bidirectional object relationships, it is recommended that you use - smart pointers with the sharing semantics as object and view pointers. + smart pointers with the sharing semantics as object pointers. The shared_ptr smart pointer from TR1, C++11, or Boost is a good default choice. However, if sharing is not required and sessions are not used, then std::unique_ptr or std::auto_ptr can be used just as well.

-

ODB provides two mechanisms for changing the object or view pointer - type. We can use the --default-pointer option to specify - the default pointer. All objects and views that don't have the pointer - type explicitly specified with the db pointer - pragma (see below) will use the default pointer type. Refer to the +

ODB provides several mechanisms for changing the object or view pointer + type. To specify the pointer type on the per object or per view basis + we can use the db pointer pragma, for example:

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

We can also specify the default pointer for a group of objects or + views at the namespace level:

+ + 
+#pragma db namespace pointer(std::tr1::shared_ptr)
+namespace accounting
+{
+  #pragma db object
+  class employee
+  {
+    ...
+  };
+
+  #pragma db object
+  class employer
+  {
+    ...
+  };
+}
+
+ +

Finally, we can use the --default-pointer option to specify + the default pointer for the whole file. Refer to the ODB Compiler Command Line Manual for details on this option's argument. The typical usage is shown below:

@@ -2317,21 +2349,40 @@ class name --default-pointer std::tr1::shared_ptr -

The second mechanism allows us to specify the pointer type on - the per object and per view basis using the - db pointer pragma, for example:

+

An alternative to this method with the same effect is to specify the + default pointer for the global namespace:

+ + 
+#pragma db namespace() pointer(std::tr1::shared_ptr)
+
+ +

Note that we can always override the default pointer specified + at the namespace level or with the command line option using + the db pointer object or view pragma. For + example:

-#pragma db object pointer(std::tr1::shared_ptr)
-class person
+#pragma db object pointer(std::shared_ptr)
+namespace accounting
 {
-  ...
-};
+  #pragma db object
+  class employee
+  {
+    ...
+  };
+
+  #pragma db object pointer(std::unique_ptr)
+  class employer
+  {
+    ...
+  };
+}

Refer to Section 12.1.2, "pointer - (object)" and Section 12.2.4, "pointer - (view)" for more information on this pragma.

+ (object)", Section 12.2.4, "pointer + (view)", and Section 12.5.1, "pointer + (namespace)" for more information on these mechanisms.

Built-in support that is provided by the ODB runtime library allows us to use shared_ptr (TR1 or C++11), @@ -8427,10 +8478,11 @@ 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 raw pointer is used by default.

+

If a pointer type is not explicitly specified, the default pointer, + specified at the namespace level (Section 12.5.1, + "pointer") or with the --default-pointer + ODB compiler option, is used. If neither of these two mechanisms is + used to specify the pointer, then the raw pointer is used by default.

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

@@ -8775,29 +8827,16 @@ namespace accounting } -

Similar to other qualifiers, the namespace qualifier - can also refer to a named C++ namespace, for example:

- - 
-namespace accounting
-{
-  ...
-}
-#pragma db namespace(accounting) schema("accounting")
-
-

If we want to assign a schema to all the persistent classes in - a file, then we can use the --schema - ODB compiler option. For example:

+ a file, then we can use the --schema ODB compiler + option. For example:

 odb ... --schema accounting ...
-

The alternative to this approach with the same effect is to - assign a schema to the global namespace. To refer to the global - namespace in the namespace qualifier we use - the following special syntax:

+

An alternative to this approach with the same effect is to + assign a schema to the global namespace:

 #pragma db namespace() schema("accounting")
@@ -8913,6 +8952,10 @@ class employee
 };
+

Table prefixes (Section 12.5.2, "table") + can be used as an alternative to database schemas if the target + database system does not support schemas.

+

12.2 View Type Pragmas

A pragma with the view qualifier declares a C++ class @@ -10695,7 +10738,26 @@ class person

12.5 Namespace Pragmas

A pragma with the namespace qualifier describes a - C++ namespace. The qualifier can be optionally followed, + C++ namespace. Similar to other qualifiers, namespace + can also refer to a named C++ namespace, for example:

+ + 
+namespace test
+{
+  ...
+}
+
+#pragma db namespace(test) ...
+
+ +

To refer to the global namespace in the namespace + qualifier the following special syntax is used:

+ + 
+#pragma db namespace() ....
+
+ +

The namespace qualifier can be optionally followed, in any order, by one or more specifiers summarized in the table below:

@@ -10708,14 +10770,144 @@ class person + pointer + pointer type for persistent classes and views inside a namespace + 12.5.1 + + + + table + table name prefix for persistent classes inside a namespace + 12.5.2 + + + schema database schema for persistent classes inside a namespace - 12.5.1 + 12.5.3 -

12.5.1 schema

+

12.5.1 pointer

+ +

The pointer specifier specifies the default pointer + type for persistent classes and views inside a namespace. For + example:

+ + 
+#pragma db namespace pointer(std::tr1::shared_ptr)
+namespace accounting
+{
+  #pragma db object
+  class employee
+  {
+    ...
+  };
+
+  #pragma db object
+  class employer
+  {
+    ...
+  };
+}
+
+ +

There are only two valid ways to specify a pointer with the + pointer specifier at the namespace level. We can + specify the template name of a smart pointer in which + case the ODB compiler will automatically append the class + name as a template argument. Or we can use * + to denote a raw pointer.

+ +

Note also that we can always override the default pointer + specified at the namespace level for any persistent class + or view inside this namespace. For example:

+ + 
+#pragma db namespace pointer(std::unique_ptr)
+namespace accounting
+{
+  #pragma db object pointer(std::shared_ptr)
+  class employee
+  {
+    ...
+  };
+
+  #pragma db object
+  class employer
+  {
+    ...
+  };
+}
+
+ +

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

+ +

12.5.2 table

+ +

The table specifier specifies a table prefix + that should be added to table names of persistent classes inside + a namespace. For example:

+ + 
+#pragma db namespace table("acc_")
+namespace accounting
+{
+  #pragma db object table("employees")
+  class employee
+  {
+    ...
+  };
+
+  #pragma db object table("employers")
+  class employer
+  {
+    ...
+  };
+}
+
+ +

In the above example the resulting table names will be + acc_employees and acc_employers.

+ +

The table name prefix can also be specified with the + --table-prefix ODB compiler option. Note + that table prefixes specified at the namespace level as well + as with the command line option are accumulated. For example:

+ + 
+#pragma db namespace() table("audit_")
+
+#pragma db namespace table("hr_")
+namespace hr
+{
+  #pragma db object table("employees")
+  class employee
+  {
+    ...
+  };
+}
+
+#pragma db object table("employers")
+class employer
+{
+  ...
+};
+
+ +

If we compile the above example with the + --table-prefix test_ option, then the + employee class table will be called + test_audit_hr_employees and employer — + test_audit_employers.

+ +

Table prefixes can be used as an alternative to database schemas + (Section 12.1.8, "schema") if + the target database system does not support schemas.

+ +

12.5.3 schema

The schema specifier specifies a database schema that should be used for persistent classes inside a namespace. -- cgit v1.1