From 7667f1698142e0a5ced34e6e5c73a08de00bd861 Mon Sep 17 00:00:00 2001 From: Constantin Michael Date: Tue, 29 Nov 2011 07:30:58 +0200 Subject: Document Oracle support --- doc/manual.xhtml | 1132 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 960 insertions(+), 172 deletions(-) diff --git a/doc/manual.xhtml b/doc/manual.xhtml index 6706322..a9f380f 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -598,25 +598,46 @@ for consistency. + 16Oracle Database + + + + + + + + +
16.1Oracle Type Mapping
16.2Oracle Database Class
16.3Oracle Connection and Connection Factory
16.4Oracle Exceptions
16.5Oracle Limitations + + + + +
16.5.1Query Result Caching
16.5.2Timezones
16.5.3NUMERIC Type Support
+
+ + + + PART III PROFILES - 16Profiles Introduction + 17Profiles Introduction - 17Boost Profile + 18Boost Profile - - - + + + - @@ -625,25 +646,27 @@ for consistency. -
17.1Smart Pointers Library
17.2Unordered Containers Library
17.3Optional Library
18.1Smart Pointers Library
18.2Unordered Containers Library
18.3Optional Library
17.4Date Time Library + 18.4Date Time Library - - - + + + +
17.4.1MySQL Database Type Mapping
17.4.2SQLite Database Type Mapping
17.4.3PostgreSQL Database Type Mapping
18.4.1MySQL Database Type Mapping
18.4.2SQLite Database Type Mapping
18.4.3PostgreSQL Database Type Mapping
18.4.4Oracle Database Type Mapping
18Qt Profile + 19Qt Profile - - - + + - @@ -6068,7 +6091,7 @@ namespace odb consider using a more efficient implementation of the optional value concept such as the optional class template from Boost - (Section 17.3, "Optional Library").

+ (Section 18.3, "Optional Library").

Another common C++ representation of a value that can be NULL is a pointer. ODB will automatically @@ -12309,186 +12332,819 @@ SHOW integer_datetimes store NUMERIC values refer to the PostgreSQL documentation.

- - - -
-

PART III   - PROFILES

-

Part III covers the integration of ODB with popular C++ frameworks - and libraries. It consists of the following chapters.

+ -
18.1Basic Types Library + 19.1Basic Types Library - - - + + + +
18.1.1MySQL Database Type Mapping
18.1.2SQLite Database Type Mapping
18.1.3PostgreSQL Database Type Mapping
19.1.1MySQL Database Type Mapping
19.1.2SQLite Database Type Mapping
19.1.3PostgreSQL Database Type Mapping
19.1.4Oracle Database Type Mapping
18.2Smart Pointers Library
18.3Containers Library
19.2Smart Pointers Library
19.3Containers Library
18.4Date Time Library + 19.4Date Time Library - - - + + + +
18.4.1MySQL Database Type Mapping
18.4.2SQLite Database Type Mapping
18.4.3PostgreSQL Database Type Mapping
19.4.1MySQL Database Type Mapping
19.4.2SQLite Database Type Mapping
19.4.3PostgreSQL Database Type Mapping
19.4.4Oracle Database Type Mapping
- - - -
16Profiles Introduction
17Boost Profile
18Qt Profile
+
+

16 Oracle Database

- +

To generate support code for the Oracle database you will need + to pass the "‑‑database oracle" + (or "‑d oracle") option to the ODB compiler. + Your application will also need to link to the Oracle ODB runtime + library (libodb‑oracle). All Oracle-specific ODB + classes are defined in the odb::oracle namespace.

+

16.1 Oracle Type Mapping

-
-

16 Profiles Introduction

+

The following table summarizes the default mapping between basic + C++ value types and Oracle database types. This mapping can be + customized on the per-type and per-member basis using the ODB + Pragma Language (Chapter 12, "ODB Pragma + Language").

-

ODB profiles are a generic mechanism for integrating ODB with - widely-used C++ frameworks and libraries. A profile provides glue - code which allows you to seamlessly persist various components, such - as smart pointers, containers, and value types found in these - frameworks or libraries. The code necessary to implement a profile - is packaged into the so called profile library. For example, the - Boost profile implementation is provided by the libodb-boost - profile library.

+ + + + + + + -

Besides linking the profile library to our application, it is also - necessary to let the ODB compiler know which profiles we - are using. This is accomplished with the --profile - (or -p alias) option. For example:

+ + + + + - 
-odb --profile boost ...
-
+ + + + + -

Some profiles, especially those covering frameworks or libraries that - consist of multiple sub-libraries, provide sub-profiles that allow you - to pick and choose which components you would like to use in your - application. For example, the boost profile contains - the boost/data-time sub-profile. If we are only - interested in the date_time types, then we can - pass boost/data-time instead of boost - to the --profile option, for example:

+ + + + + - 
-odb --profile boost/date-time ...
-
+ + + + + -

To summarize, you will need to perform the following steps in order - to make use of a profile in your application:

+ + + + + -
    -
  1. ODB compiler: if necessary, specify the path to the profile library - headers (-I option).
    2. -
  2. ODB compiler: specify the profile you would like to use with - the --profile option.
    3. -
  3. C++ compiler: if necessary, specify the path to the profile library - headers (normally -I option).
    4. -
  4. Linker: link the profile library to the application.
    5. -
+ + + + + -

The remaining chapters in this part of the manual describe the - standard profiles provided by ODB.

+ + + + + + + + + + - + + + + + + + + + + -
-

17 Boost Profile

+ + + + + -

The ODB profile implementation for Boost is provided by the - 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.13, "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.

+ + + + + -

17.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.

+ + + + + +
C++ TypeOracle TypeDefault NULL Semantics
boolNUMBER(1)NOT NULL
charNUMBER(3)NOT NULL
signed charNUMBER(3)NOT NULL
unsigned charNUMBER(3)NOT NULL
shortNUMBER(5)NOT NULL
unsigned shortNUMBER(5)NOT NULL
intNUMBER(10)NOT NULL
unsigned intNUMBER(10)NOT NULL
longNUMBER(19)NOT NULL
unsigned longNUMBER(20)NOT NULL
long longNUMBER(19)NOT NULL
unsigned long longNUMBER(20)NOT NULL
floatBINARY_FLOATNOT NULL
doubleBINARY_DOUBLENOT NULL
std::stringVARCHAR(4000)NOT NULL
-

The currently supported smart pointers are - boost::shared_ptr and boost::weak_ptr. For - more information on using smart pointers as pointers to objects and - views, refer to Section 3.2, "Object and View Pointers" - and Chapter 6, "Relationships". For more information - on using smart pointers as pointers to values, refer to - Section 7.3, "Pointers and NULL Value - Semantics". When used as a pointer to a value, only - boost::shared_ptr is supported. For example:

+

The Oracle ODB runtime library also provides support for mapping the + std::string type to the Oracle CLOB and + NCLOB types, and for mapping the + std::vector<char>, + std::vector<unsigned char>, + char[N], and unsigned char[N] types to + the Oracle BLOB and RAW types. However, these + mappings are not enabled by default (in particular, by default, + std::vector will be treated as a container). To enable the + non-default mappings for these types we need to specify the database type + explicitly using the db type pragma + (Section 12.4.3, "type"), for + example:

 #pragma db object
-class person
+class object
 {
   ...
 
-  #pragma db null
-  boost::shared_ptr<std::string> middle_name_;
+  #pragma db type ("CLOB")
+  std::string str_;
+
+  #pragma db type("RAW(256)")
+  std::vector<char> buf_;
+
+  #pragma db type("BLOB")
+  unsigned char[16] uuid_;
 };
-

To provide finer grained control over object relationship loading, - 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.

+

Alternatively, this can be done on the per-type basis, for example:

-
-class employee;
+  
+typedef std::vector<char> buffer;
+#pragma db value(buffer) type("BLOB")
 
 #pragma db object
-class position
+class object
 {
   ...
 
-  #pragma db inverse(position_)
-  odb::boost::lazy_weak_ptr<employee> employee_;
+  buffer buf_; // Mapped to BLOB.
 };
+  

 
-#pragma db object
-class employee
-{
-  ...
+  
Additionally, by default, C++ enumerations are automatically
+     mapped to NUMBER(10) with the default NULL
+     semantics being NOT NULL.

 
-  #pragma db not_null
-  boost::shared_ptr<position> position_;
-};
-
+

16.2 Oracle Database Class

-

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

+

The Oracle database class has the following + interface:

-

17.2 Unordered Containers Library

+ 
+namespace odb
+{
+  namespace oracle
+  {
+    class database: public odb::database
+    {
+    public:
+      database (const std::string& user,
+                const std::string& password,
+                const std::string& db,
+                ub2 charset = 0,
+                ub2 ncharset = 0,
+                OCIEnv* environment = 0,
+                std::auto_ptr<connection_factory> = 0);
 
-  
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.

+      database (const std::string& user,
+                const std::string& password,
+                const std::string& service,
+                const std::string& host = "",
+                unsigned int port = 0,
+                ub2 charset = 0,
+                ub2 ncharset = 0,
+                OCIEnv* environment = 0,
+                std::auto_ptr<connection_factory> = 0);
 
-  
The supported containers are boost::unordered_set,
-     boost::unordered_map, boost::unordered_multiset,
-     and boost::unordered_multimap. For more information on using
+      database (int& argc,
+                char* argv[],
+                bool erase = false,
+                ub2 charset = 0,
+                ub2 ncharset = 0,
+                OCIEnv* environment = 0,
+                std::auto_ptr<connection_factory> = 0);
+
+      static void
+      print_usage (std::ostream&);
+
+
+    public:
+      const std::string&
+      user () const;
+
+      const std::string&
+      password () const;
+
+      const std::string&
+      db () const;
+
+      const std::string&
+      service () const;
+
+      const std::string&
+      host () const;
+
+      unsigned int
+      port () const;
+
+      ub2
+      charset () const;
+
+      ub2
+      ncharset () const;
+
+      OCIEnv*
+      environment () const;
+
+    public:
+      connection_ptr
+      connection ();
+    };
+  }
+}
+
+ +

You will need to include the <odb/oracle/database.hxx> + header file to make this class available in your application.

+ +

The database class wraps an OCI environment handle, as well + as a database connection string and user credentials that can be used to + establish a database connection.

+ +

The overloaded database constructors allow us to specify the + Oracle database parameters that should be used when connecting to the + database. The database argument in the first constructor is a + connection identifier that specifies the database to connect to. For more + information on the format of the connection identifier, please refer to + the Oracle Net Services reference.

+ +

The second constructor allows the components of a connection identifier to + be specified individually using the service, + host, and port arguments. Specifying an empty + host string is equivalent to localhost. Specifying a zero port number + indicates that the default port should be used.

+ +

The last constructor extracts the database parameters + from the command line. The following options are recognized:

+ + 
+  --user <login>
+  --password <password>
+  --database <name>
+  --service <name>
+  --host <host>
+  --port <integer>
+  --options-file <file>
+
+ +

The --options-file option allows us to specify some + or all of the database options in a file with each option appearing + on a separate line followed by a space and an option value. Note that it + is invalid to specify the ‑‑database option + together with any of ‑‑service, + ‑‑host, or ‑‑port + options.

+ +

If the erase argument to this constructor is true, + then the above options are removed from the argv + array and the argc count is updated accordingly. + This is primarily useful if your application accepts other + options or arguments and you would like to get the Oracle + options out of the argv array.

+ +

This constructor throws the odb::oracle::cli_exception + exception if the Oracle option values are missing or invalid. See section + Section 16.4, "Oracle Exceptions" for more + information on this exception.

+ +

The static print_usage() function prints the list of options + with short descriptions that are recognized by this constructor.

+ +

All the constructors take charset and ncharset + arguments. These specify the client database character set and client + national character set, respectively.

+ +

Additionally, each constructor takes an environment argument + which is an OCI environment handle. If the handle is + non-NULL, it is used for all OCI function calls made against + the database instance that require an environment handle. The + database instance does not take ownership of this handle, + and it should be released by the user when it is no longer needed. The + charset and ncharset arguments are ignored if + the environment argument is non-NULL.

+ +

The last argument to all of the constructors is a pointer to a + connection factory. If we pass a non-NULL value, the + database instance assumes ownership of the factory instance. The + connection factory interface as well as the available implementations + are described in the next section.

+ +

The set of accessor functions following the constructors allows us + to query the parameters of the database instance.

+ +

The connection() function returns a pointer to the + Oracle database connection encapsulated by the + odb::oracle::connection class. For more information + on oracle::connection, refer to Section + 16.3, "Oracle Connection and Connection Factory".

+ +

16.3 Oracle Connection and Connection Factory

+ +

The oracle::connection class has the following interface:

+ + 
+namespace odb
+{
+  namespace oracle
+  {
+    class connection: public odb::connection
+    {
+    public:
+      connection (database&);
+      connection (database&, OCISvcCtx*);
+
+      OCISvcCtx*
+      handle ();
+
+      OCIError*
+      error_handle ();
+
+      details::buffer&
+      lob_buffer ();
+    };
+
+    typedef details::shared_ptr<connection> connection_ptr;
+  }
+}
+
+ +

For more information on the odb::connection interface, refer + to Section 3.5, "Connections". The first overloaded + oracle::connection constructor creates a new Oracle service + context. Statement caching is enabled for the underlying session. + Connection pooling and session pooling are not utilized. The second + constructor allows us to create a connection instance by + providing an already connected Oracle service context. Note that the + connection instance assumes ownership of this handle. The + handle() accessor returns the Oracle service context handle + associated with the connection.

+ +

An Oracle error handle is allocated for each connection + instance. This handle is publicly available via the + error_handle() accessor. Its lifetime is managed by, and + must remain valid for the entire lifetime of its containing + connection instance.

+ +

Finally, each connection instance maintains a LOB buffer. + This buffer is used as intermediate storage between the OCI and ODB + implementations, and allows for piecewise handling of LOB data. The + buffer capacity may be optionaly set using the lob_buffer() + accessor. If the capacity is not explicitly set, the buffer occupies zero + bytes until it is used for the first time, at which point 4096 bytes of + space is allocated.

+ +

The oracle::connection_factory abstract class has the + following interface:

+ + 
+namespace odb
+{
+  namespace oracle
+  {
+    class connection_factory
+    {
+    public:
+      virtual void
+      database (database&) = 0;
+
+      virtual connection_ptr
+      connect () = 0;
+    };
+  }
+}
+
+ +

The database() function is called when a connection + factory is associated with a database instance. This happens in + the odb::oracle::database class constructors. The + connect() function is called whenever a database + connection is requested.

+ +

The two implementations of the connection_factory + interface provided by the Oracle ODB runtime are + new_connection_factory and + connection_pool_factory. You will need to include + the <odb/oracle/connection-factory.hxx> + header file to make the connection_factory interface + and these implementation classes available in your application.

+ +

The new_connection_factory class creates a new + connection whenever one is requested. When a connection is no + longer needed, it is released and closed. The + new_connection_factory class has the following + interface:

+ + 
+namespace odb
+{
+  namespace oracle
+  {
+    class new_connection_factory: public connection_factory
+    {
+    public:
+      new_connection_factory ();
+    };
+};
+
+ +

The connection_pool_factory class implements a + connection pool. It has the following interface:

+ + 
+namespace odb
+{
+  namespace oracle
+  {
+    class connection_pool_factory: public connection_factory
+    {
+    public:
+      connection_pool_factory (std::size_t max_connections = 0,
+                               std::size_t min_connections = 0);
+
+    protected:
+      class pooled_connection: public connection
+      {
+      public:
+        pooled_connection (database_type&);
+        pooled_connection (database_type&, PGconn*);
+      };
+
+      typedef details::shared_ptr<pooled_connection> pooled_connection_ptr;
+
+      virtual pooled_connection_ptr
+      create ();
+    };
+};
+
+ +

The max_connections argument in the + connection_pool_factory constructor specifies the maximum + number of concurrent connections that this pool factory will + maintain. Similarly, the min_connections argument + specifies the minimum number of available connections that + should be kept open.

+ +

Whenever a connection is requested, the pool factory first + checks if there is an unused connection that can be returned. + If there is none, the pool factory checks the + max_connections value to see if a new connection + can be created. If the total number of connections maintained + by the pool is less than this value, then a new connection is + created and returned. Otherwise, the caller is blocked until + a connection becomes available.

+ +

When a connection is released, the pool factory first checks + if there are blocked callers waiting for a connection. If so, then + one of them is unblocked and is given the connection. Otherwise, + the pool factory checks whether the total number of connections + maintained by the pool is greater than the min_connections + value. If that's the case, the connection is closed. Otherwise, the + connection is added to the pool of available connections to be + returned on the next request. In other words, if the number of + connections maintained by the pool exceeds min_connections + and there are no callers waiting for a new connection, + the pool will close the excess connections.

+ +

If the max_connections value is 0, then the pool will + create a new connection whenever all of the existing connections + are in use. If the min_connections value is 0, then + the pool will never close a connection and instead maintain all + the connections that were ever created.

+ +

The create() virtual function is called whenever the + pool needs to create a new connection. By deriving from the + connection_pool_factory class and overriding this + function we can implement custom connection establishment + and configuration.

+ +

If you pass NULL as the connection factory to one of the + database constructors, then the + connection_pool_factory instance will be created by default + with the min and max connections values set to 0. The + following code fragment shows how we can pass our own connection factory + instance:

+ + 
+#include <odb/database.hxx>
+
+#include <odb/oracle/database.hxx>
+#include <odb/oracle/connection-factory.hxx>
+
+int
+main (int argc, char* argv[])
+{
+  auto_ptr<odb::oracle::connection_factory> f (
+    new odb::oracle::connection_pool_factory (20));
+
+  auto_ptr<odb::database> db (
+    new oracle::database (argc, argv, false, 0, 0, 0, f));
+}
+
+ +

16.4 Oracle Exceptions

+ +

The Oracle ODB runtime library defines the following + Oracle-specific exceptions:

+ + 
+namespace odb
+{
+  namespace oracle
+  {
+    class database_exception: odb::database_exception
+    {
+    public:
+      int
+      error () const;
+
+      const std::string&
+      message () const;
+
+      virtual const char*
+      what () const throw ();
+    };
+
+    class cli_exception: odb::exception
+    {
+    public:
+      virtual const char*
+      what () const throw ();
+    };
+
+    class invalid_oci_handle: odb::exception
+    {
+    public:
+      virtual const char*
+      what () const throw ();
+    };
+  }
+}
+
+ +

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

+ +

The odb::oracle::database_exception is thrown if + an Oracle database operation fails. The Oracle-specific error + information is accessible via the message() and + error() functions. All this information is also + combined and returned in a human-readable form by the what() + function.

+ +

The odb::oracle::cli_exception is thrown by the + command line parsing constructor of the odb::oracle::database + class if the Oracle option values are missing or invalid. The + what() function returns a human-readable description + of an error.

+ +

The odb::oracle::invalid_oci_handle is thrown if an OCI + function returns the status code OCI_INVALID_HANDLE. The + what() function returns a human-readable description + of an error.

+ +

16.5 Oracle Limitations

+ +

The following sections describe Oracle-specific limitations imposed + by the current Oracle and ODB runtime versions.

+ +

16.5.1 Query Result Caching

+ +

Oracle ODB runtime implementation does not perform query result caching + (Section 4.4, "Query Result") even when explicitly requested. OCI supports + supports interleaving execution of multiple prepared statements on a + single connection. As a result, with Oracle, it is possible to have + multiple uncached results and calls to other database functions do not + invalidate them. The only limitation of the uncached Oracle results is + the unavailability of the result::size() function. If you call this + function on an Oracle query result, then the odb::result_not_cached + exception (Section 3.13, "ODB Exceptions") is always thrown. Future + versions of the Oracle ODB runtime library may add support for result + caching.

+ +

16.5.2 Timezones

+ +

ODB does not currently support the Oracle date-time types with timezone + information.

+ +

16.5.3 Floating point NUMBER Type + Support

+ +

Support for the Oracle NUMBER type when it represents a + floating point number (declared by specifying NUMBER without any range or + scale) is limited to providing a buffer containing the binary + representation of the value. For more information on the binary format + used to store NUMBER values refer to the OCI + documentation.

+ + + + + +
+

PART III   + PROFILES

+ +

Part III covers the integration of ODB with popular C++ frameworks + and libraries. It consists of the following chapters.

+ + + + + +
17Profiles Introduction
18Boost Profile
19Qt Profile
+ + + + + +
+

17 Profiles Introduction

+ +

ODB profiles are a generic mechanism for integrating ODB with + widely-used C++ frameworks and libraries. A profile provides glue + code which allows you to seamlessly persist various components, such + as smart pointers, containers, and value types found in these + frameworks or libraries. The code necessary to implement a profile + is packaged into the so called profile library. For example, the + Boost profile implementation is provided by the libodb-boost + profile library.

+ +

Besides linking the profile library to our application, it is also + necessary to let the ODB compiler know which profiles we + are using. This is accomplished with the --profile + (or -p alias) option. For example:

+ + 
+odb --profile boost ...
+
+ +

Some profiles, especially those covering frameworks or libraries that + consist of multiple sub-libraries, provide sub-profiles that allow you + to pick and choose which components you would like to use in your + application. For example, the boost profile contains + the boost/data-time sub-profile. If we are only + interested in the date_time types, then we can + pass boost/data-time instead of boost + to the --profile option, for example:

+ + 
+odb --profile boost/date-time ...
+
+ +

To summarize, you will need to perform the following steps in order + to make use of a profile in your application:

+ +
    +
  1. ODB compiler: if necessary, specify the path to the profile library + headers (-I option).
    2. +
  2. ODB compiler: specify the profile you would like to use with + the --profile option.
    3. +
  3. C++ compiler: if necessary, specify the path to the profile library + headers (normally -I option).
    4. +
  4. Linker: link the profile library to the application.
    5. +
+ +

The remaining chapters in this part of the manual describe the + standard profiles provided by ODB.

+ + + + + +
+

18 Boost Profile

+ +

The ODB profile implementation for Boost is provided by the + 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.13, "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.

+ +

18.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 as pointers to objects and + views, refer to Section 3.2, "Object and View Pointers" + and Chapter 6, "Relationships". For more information + on using smart pointers as pointers to values, refer to + Section 7.3, "Pointers and NULL Value + Semantics". When used as a pointer to a value, only + boost::shared_ptr is supported. For example:

+ + 
+#pragma db object
+class person
+{
+  ...
+
+  #pragma db null
+  boost::shared_ptr<std::string> middle_name_;
+};
+
+ +

To provide finer grained control over object relationship loading, + 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.

+ +
+class employee;
+
+#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 + pointer (Section 3.2, "Object and View Pointers") + to boost::shared_ptr. In particular, this means that + database functions that return dynamically allocated objects and views + will return them as boost::shared_ptr pointers. To override + this behavior, add the --default-pointer option specifying + the alternative pointer type after the --profile option.

+ +

18.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 @@ -12505,7 +13161,7 @@ class person }; -

17.3 Optional Library

+

18.3 Optional Library

The optional sub-profile provides persistence support for the boost::optional container from the Boost @@ -12537,7 +13193,7 @@ class person this profile is used, the NULL values are automatically enabled for data members of the boost::optional type.

-

17.4 Date Time Library

+

18.4 Date Time Library

The date-time sub-profile provides persistence support for a subset of types from the Boost date_time library. It is @@ -12610,7 +13266,7 @@ namespace odb exceptions are thrown are database system dependent and are discussed in more detail in the following sub-sections.

-

17.4.1 MySQL Database Type Mapping

+

18.4.1 MySQL Database Type Mapping

The following table summarizes the default mapping between the currently supported Boost date_time types and the MySQL database @@ -12671,7 +13327,7 @@ class person the out_of_range exception. Refer to the MySQL documentation for more information on the MySQL data type ranges.

-

17.4.2 SQLite Database Type Mapping

+

18.4.2 SQLite Database Type Mapping

The following table summarizes the default mapping between the currently supported Boost date_time types and the SQLite database @@ -12749,7 +13405,7 @@ class person will result in the out_of_range exception.

-

17.4.3 PostgreSQL Database Type Mapping

+

18.4.3 PostgreSQL Database Type Mapping

The following table summarizes the default mapping between the currently supported Boost date_time types and the PostgreSQL database @@ -12800,11 +13456,55 @@ class person result in the special_value exception.

+

18.4.4 Oracle Database Type Mapping

+ +

The following table summarizes the default mapping between the currently + supported Boost date_time types and the Oracle database + types.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Boost date_time TypeOracle TypeDefault NULL Semantics
gregorian::dateDATENULL
posix_time::ptimeTIMESTAMPNULL
posix_time::time_durationINTERVAL DAY TO SECONDNULL
+ +

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

+ +

Some valid Boost date-time values cannot be stored in an Oracle database. + An attempt to persist a gregorian::date, + posix_time::time_duration, or + posix_time::time_duration value representing any special + value other than date_time::not_a_date_time will result in + the special_value exception.

+ +
-

18 Qt Profile

+

19 Qt Profile

The ODB profile implementation for Qt is provided by the libodb-qt library and consists of multiple sub-profiles @@ -12830,7 +13530,7 @@ class person that can be thrown by the Qt sub-profiles are described in the following sections.

-

18.1 Basic Types

+

19.1 Basic Types

The basic sub-profile provides persistence support for basic types defined by Qt. To enable only this profile, pass @@ -12852,7 +13552,7 @@ class Person }; -

18.1.1 MySQL Database Type Mapping

+

19.1.1 MySQL Database Type Mapping

The following table summarizes the default mapping between the currently supported basic Qt types and the MySQL database types.

@@ -12890,7 +13590,7 @@ class Person it is mapped to TEXT.

-

18.1.2 SQLite Database Type Mapping

+

19.1.2 SQLite Database Type Mapping

The following table summarizes the default mapping between the currently supported basic Qt types and the SQLite database types.

@@ -12920,7 +13620,7 @@ class Person are stored as a NULL value if their isNull() member function returns true.

-

18.1.3 PostgreSQL Database Type Mapping

+

19.1.3 PostgreSQL Database Type Mapping

The following table summarizes the default mapping between the currently supported basic Qt types and the PostgreSQL database types.

@@ -12950,7 +13650,59 @@ class Person are stored as a NULL value if their isNull() member function returns true.

-

18.2 Smart Pointers

+

19.1.4 Oracle Database Type Mapping

+ +

The following table summarizes the default mapping between the currently + supported basic Qt types and the Oracle database types.

+ + + + + + + + + + + + + + + + + + + + +
Qt TypeOracle TypeDefault NULL Semantics
QStringVARCHAR(4000)NULL
QByteArrayBLOBNULL
+ +

Instances of the QString and QByteArray types + are stored as a NULL value if their isNull() member + function returns true.

+ +

The basic sub-profile implementation also provides support + for mapping QString to the CLOB and NCLOB Oracle + types, and for mapping QByteArray to the RAW Oracle type. + However, these mappings need to be explicitly requested using the + db type pragma + (Section 12.4.3, "type"), as show in the + following example:

+ + 
+#pragma db object
+class Person
+{
+  ...
+
+  #pragma db type("NCLOB") not_null
+  QString first_name_;
+
+  #pragma db type("RAW(128)") null
+  QByteArray uuid_;
+};
+
+ +

19.2 Smart Pointers

The smart-ptr sub-profile provides persistence support the Qt smart pointers. To enable only this profile, pass @@ -13019,7 +13771,7 @@ class Employee this behavior, add the --default-pointer option specifying the alternative pointer type after the --profile option.

-

18.3 Containers Library

+

19.3 Containers Library

The container sub-profile provides persistence support for Qt containers. To enable only this profile, pass @@ -13044,7 +13796,7 @@ class Person }; -

18.4 Date Time Types

+

19.4 Date Time Types

The date-time sub-profile provides persistence support for the Qt date-time types. To enable only this profile, pass @@ -13097,7 +13849,7 @@ namespace odb system dependent and is discussed in more detail in the following sub-sections.

-

18.4.1 MySQL Database Type Mapping

+

19.4.1 MySQL Database Type Mapping

The following table summarizes the default mapping between the currently supported Qt date-time types and the MySQL database types.

@@ -13156,7 +13908,7 @@ class Person the MySQL documentation for more information on the MySQL data type ranges.

-

18.4.2 SQLite Database Type Mapping

+

19.4.2 SQLite Database Type Mapping

The following table summarizes the default mapping between the currently supported Qt date-time types and the SQLite database types.

@@ -13218,7 +13970,7 @@ class Person epoch) as an SQLite INTEGER will result in the out_of_range exception.

-

18.4.3 PostgreSQL Database Type Mapping

+

19.4.3 PostgreSQL Database Type Mapping

The following table summarizes the default mapping between the currently supported Qt date-time types and the PostgreSQL database types.

@@ -13261,6 +14013,42 @@ class Person TIMESTAMP will result in the out_of_range exception.

+

19.4.4 Oracle Database Type Mapping

+ +

The following table summarizes the default mapping between the currently + supported Qt date-time types and the Oracle database types.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
Qt Date Time TypeOracle TypeDefault NULL Semantics
QDateDATENULL
QTimeINTERVAL DAY(0) TO SECOND(3)NULL
QDateTimeTIMESTAMP(3)NULL
+ +

Instances of the QDate, QTime, and + QDateTime types are stored as a NULL value if their + isNull() member function returns true.

+ -- cgit v1.1