From 98b4c0dd4df979b5521e08445d7ca4f79ab18e70 Mon Sep 17 00:00:00 2001 From: Constantin Michael Date: Wed, 9 Mar 2011 14:59:06 +0200 Subject: Add Boost profile docs --- doc/manual.xhtml | 239 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 231 insertions(+), 8 deletions(-) diff --git a/doc/manual.xhtml b/doc/manual.xhtml index 3d7cd2f..25151e5 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -2223,7 +2223,7 @@ update_age (database& db, person& p) instance, by obtaining a valid object id and trying again. The hard errors and corresponding ODB exceptions that can be thrown by each database function are described in the remainder - of this chapter with Section 3.11, "ODB Exceptions" + of this chapter with Section 3.11, "ODB Exceptions" providing a quick reference for all the ODB exceptions.

The second group of ODB exceptions signify soft or @@ -2625,7 +2625,7 @@ t.commit (); runtime.

The root of the ODB exception hierarchy is the abstract - odb::exception class. This class inherits + odb::exception class. This class derives from std::exception and has the following interface:

@@ -5218,7 +5218,7 @@ t.commit ();
-

5 ODB Pragma Language

+

9 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. @@ -6969,11 +6969,234 @@ odb --profile boost/date-time ...

12 Boost Profile

The ODB profile implementation for Boost is provided by the - libodb-boost profile library. To enable all the supported - Boost sub-libraries, specify boost as the profile name in - the --profile ODB compiler option. Alternatively you can - enable only specific sub-profiles. The available sub-profiles are - discussed in the following sections.

+ libodb-boost library and consists of multiple sub-profiles + corresponding to the individual Boost libraries. To enable all the + available Boost sub-profiles, pass boost as the profile + name to the --profile ODB compiler option. Alternatively, + you can enable only specific sub-profiles by passing individual + sub-profile names to --profile. The following sections in + this chapter discuss each Boost sub-profile in detail. The + boost example in the odb-examples + package shows how to enable and use the Boost profile.

+ +

Some sub-profiles may throw exceptions to indicate error conditions, + such as the inability to store a specific value in a particular database + system. All such exceptions derive from the + odb::boost::exception class which in turn derives from + the root of the ODB exception hierarchy, class odb::exception + (Section 3.11, "ODB Exceptions"). The + odb::boost::exception class is defined in the + <odb/boost/exception.hxx> header file and has the + same interface as odb::exception. The concrete exceptions + that can be thrown by the Boost sub-profiles are described in the + following sections.

+ +

12.1 Smart Pointers Library

+ +

The smart-ptr sub-profile provides persistence + support for a subset of smart pointers from the Boost + smart_ptr library. To enable only this profile, + pass boost/smart-ptr to the --profile + ODB compiler option.

+ +

The currently supported smart pointers are + boost::shared_ptr and boost::weak_ptr. For + more information on using smart pointers with ODB refer to + Section 3.2, "Object Pointers" and + Chapter 6, "Relationships". The smart-ptr + sub-profile also provides the lazy counterparts for the above + pointers: odb::boost::lazy_shared_ptr and + odb::boost::lazy_weak_ptr. You will need to include the + <odb/boost/lazy-ptr.hxx> header file to make the lazy + variants available in your application. For the description of the lazy + pointer interface and semantics refer to Section 6.3, + "Lazy Pointers". The following example shows how we can use these + smart pointers to establish a relationship between persistent objects.

+ +
+#pragma db object
+class position
+{
+  ...
+
+  #pragma db inverse(position_)
+  odb::boost::lazy_weak_ptr<employee> employee_;
+};
+
+#pragma db object
+class employee
+{
+  ...
+
+  #pragma db not_null
+  boost::shared_ptr<position> position_;
+};
+
+ +

Besides providing persistence support for the above smart pointers, + the smart-ptr sub-profile also changes the default object + pointer (Section 3.2, "Object Pointers") + to boost::shared_ptr. In particular, this means that + database functions that return dynamically allocated objects will return + them as boost::shared_ptr pointers. To override this + behavior, add the --default-pointer option specifying the + alternative object pointer after the --profile option.

+ +

12.2 Unordered Containers Library

+ +

The unordered sub-profile provides persistence support for + the containers from the Boost unordered library. To enable + only this profile, pass boost/unordered to + the --profile ODB compiler option.

+ +

The supported containers are boost::unordered_set, + boost::unordered_map, boost::unordered_multiset, + and boost::unordered_multimap. For more information on using + the set and multiset containers with ODB refer to Section + 5.2, "Set and Multiset Containers". For more information on using the + map and multimap containers with ODB refer to Section + 5.3, "Map and Multimap Containers". The following example shows how + the unordered_set container may be used within a persistent + object.

+ +
+#pragma db object
+class employee
+{
+  ...
+  boost::unordered_set<std::string> emails_;
+};
+
+ +

12.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 + further subdivided into two sub-profiles, gregorian + and posix_time. The gregorian sub-profile + provides support for types from the boost::gregorian + namespace, while the posix-time sub-profile provides support + for types from the boost::posix_time namespace. To enable + the entire date-time sub-profile, pass + boost/date-time to the --profile ODB compiler + option. To enable only the gregorian sub-profile, pass + boost/date-time/gregorian, and to enable only the + posix-time sub-profile, pass + boost/date-time/posix-time.

+ +

The only type that the gregorian sub-profile currently + supports is gregorian::date. The types currently supported + by the posix-time sub-profile are + posix_time::ptime and + posix_time::time_duration. The manner in which these these + types are persisted is database system dependent and is discussed in the + sub-sections that follow. The example below shows how + gregorian::date may be used within a persistent object.

+ +
+#pragma db object
+class person
+{
+  ...
+  boost::gregorian::date date_of_birth_;
+};
+
+ +

The concrete exceptions that can be thrown by the date-time + sub-profile implementation are presented below.

+ + +
+namespace odb
+{
+  namespace boost
+  {
+    namespace date_time
+    {
+      struct special_value: odb::boost::exception
+      {
+        virtual const char*
+        what () const throw ();
+      };
+
+      struct value_out_of_range: odb::boost::exception
+      {
+        virtual const char*
+        what () const throw ();
+      };
+    }
+  }
+}
+
+ +

You will need to include the + <odb/boost/date-time/exceptions.hxx> header file to + make these exceptions available in your application.

+ +

The special_value exception is thrown if an attempt is made + to store a Boost date-time special value that cannot be represented in + the target database. The value_out_of_range exception is + thrown if an attempt is made to store a date-time value that is out of + the target database range. The specific conditions under which these + exceptions are thrown are database system dependent and are discussed in + more detail in the following sub-sections.

+ +

12.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 + types.

+ + + + + + + + + + + + + + + + + + + + + + +
Boost date_time typeMySQL type
gregorian::dateDATE
posix_time::ptimeDATETIME
posix_time::time_durationTIME
+ +

The Boost special value date_time::not_a_date_time is stored + as a NULL value in a MySQL database.

+ +

The posix-time sub-profile implementation also provides + 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 + the following example:

+ +
+#pragma db object
+class employee
+{
+  ...
+  #pragma db type("TIMESTAMP")
+  boost::posix_time::ptime employment_date_;
+};
+
+ +

Some valid Boost date-time values cannot be stored in a MySQL database. + Attempting to persist any Boost date-time special value other than + date_time::not_a_date_time will result in the + special_value exception. Attempting to persist a Boost + date-time value that is out of the MySQL type range will result in + the out_of_range exception. Refer to the MySQL + documentation for more information on the MySQL data type ranges.

-- cgit v1.1