From 98b4c0dd4df979b5521e08445d7ca4f79ab18e70 Mon Sep 17 00:00:00 2001
From: Constantin Michael
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:
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 ...
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.
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.
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_; +}; ++ +
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.
The following table summarizes the default mapping between the currently
+ supported Boost date_time
types and the MySQL database
+ types.
Boost date_time type |
+ MySQL type | +
---|---|
gregorian::date |
+ DATE |
+
posix_time::ptime |
+ DATETIME |
+
posix_time::time_duration |
+ TIME |
+
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.