From 65713117ae73f692b25ad70f2e7d8650ee997c2d Mon Sep 17 00:00:00 2001 From: Constantin Michael Date: Thu, 21 Apr 2011 16:59:57 +0200 Subject: Add Qt profile chapter to manual --- doc/manual.xhtml | 409 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 397 insertions(+), 12 deletions(-) (limited to 'doc') diff --git a/doc/manual.xhtml b/doc/manual.xhtml index 97dc8b7..54e6a1e 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -521,6 +521,31 @@ for consistency. + + 14Qt Profile + + + + + + + + + +
14.1Basic Types Library + + + +
14.1.1MySQL Database Type Mapping
14.1.2SQLite Database Type Mapping
+
14.2Smart Pointers Library
14.3Containers Library
14.4Date Time Library + + + +
14.4.1MySQL Database Type Mapping
14.4.2SQLite Database Type Mapping
+
+ + + @@ -6534,7 +6559,7 @@ aCC +W2161 ... - + @@ -6617,7 +6642,7 @@ aCC +W2161 ... differently depending on whether the member of this type is an object id or not. If the member is an object id, then for this member std::string is mapped - to VARCHAR(255) NOT NULL MySQL type. Otherwise, + to the VARCHAR(255) NOT NULL MySQL type. Otherwise, it is mapped to TEXT NOT NULL.

Additionally, by default, C++ enumerations are automatically @@ -7029,7 +7054,7 @@ namespace odb

C++ TypeMySQL typeMySQL Type
- + @@ -7545,6 +7570,7 @@ class person
C++ TypeSQLite typeSQLite Type
+
12Profiles Introduction
13Boost Profile
14Qt Profile
@@ -7654,6 +7680,8 @@ odb --profile boost/date-time ... smart pointers to establish a relationship between persistent objects.

+class employee;
+
 #pragma db object
 class position
 {
@@ -7701,7 +7729,7 @@ class employee
 
 
 #pragma db object
-class employee
+class person
 {
   ...
   boost::unordered_set<std::string> emails_;
@@ -7790,8 +7818,8 @@ namespace odb
   
   
-      
-      
+      
+      
@@ -7822,11 +7850,11 @@ namespace odb
 
 
 #pragma db object
-class employee
+class person
 {
   ...
   #pragma db type("TIMESTAMP")
-  boost::posix_time::ptime employment_date_;
+  boost::posix_time::ptime updated_;
 };
 

 
@@ -7847,8 +7875,8 @@ class employee
   

     
Boost date_time typeMySQL typeBoost date_time TypeMySQL Type
     

 
     

   

-      
-      
+      
+      
@@ -7882,7 +7910,7 @@ class employee
 
 
 #pragma db object
-class employee
+class person
 {
   ...
   #pragma db type("INTEGER")
@@ -7911,9 +7939,366 @@ class employee
      posix_time::time_duration value as SQLite TEXT
      will result in the out_of_range exception.

 
+
+  
+
+
+  

+  
14 Qt Profile

+
+  
The ODB profile implementation for Qt is provided by the
+     libodb-qt library and consists of multiple sub-profiles
+     corresponding to the common type groups within Qt. Currently,
+     only types from the QtCore module are supported. To
+     enable all the available Qt sub-profiles, pass qt 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 Qt sub-profile in detail. The
+     qt example in the odb-examples
+     package shows how to enable and use the Qt 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::qt::exception class which in turn derives from
+     the root of the ODB exception hierarchy, class odb::exception
+     (Section 3.11, "ODB Exceptions"). The
+     odb::qt::exception class is defined in the
+     <odb/qt/exception.hxx> header file and has the
+     same interface as odb::exception. The concrete exceptions
+     that can be thrown by the Qt sub-profiles are described in the
+     following sections.

+
+  
14.1 Basic Types

+
+  
The basic sub-profile provides persistence support for basic
+     types defined by Qt. To enable only this profile, pass
+     qt/basic to the --profile ODB compiler
+     option.

+
+  
The currently supported basic types are QString and
+    QByteArray. The manner in which these types
+     are persisted is database system dependent and is discussed in the
+     sub-sections that follow. The example below shows how
+     QString may be used within a persistent object.

+
+
+#pragma db object
+class Person
+{
+  ...
+  QString name_;
+};
+

+
+  
14.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.

+
+  
+  

     
Boost date_time typeSQLite typeBoost date_time TypeSQLite Type
     

 
     

+    
+      
+      
+    
+
+    
+      
+      
+    
+
+    
+      
+      
+    
+  
Qt TypeMySQL Type
QStringTEXT
QByteArrayBLOB

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

+
+  
Note also that the QString type is mapped
+     differently depending on whether the member of this type
+     is an object id or not. If the member is an object id,
+     then for this member QString is mapped
+     to the VARCHAR(255) NOT NULL MySQL type. Otherwise,
+     it is mapped to TEXT.

+
+
+  
14.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.

+
+  
+  
+    
+      
+      
+    
+
+    
+      
+      
+    
+
+    
+      
+      
+    
+  
Qt TypeSQLite Type
QStringTEXT
QByteArrayBLOB

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

+
+  
14.2 Smart Pointers

+
+  
The smart-ptr sub-profile provides persistence support the
+     Qt smart pointers. To enable only this profile, pass
+     qt/smart-ptr to the --profile ODB compiler
+     option.

+
+  
The currently supported smart pointers are
+     QSharedPointer and QWeakPointer. 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: QLazySharedPointer
+     and QLazyWeakPointer. You will need to include the
+     <odb/qt/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_)
+  QLazyWeakPointer<Employee> employee_;
+};
+
+#pragma db object
+class Employee
+{
+  ...
+
+  #pragma db not_null
+  QSharedPointer<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 QSharedPointer.  In particular, this means that
+     database functions that return dynamically allocated objects will return
+     them as QSharedPointer pointers.  To override this
+     behavior, add the --default-pointer option specifying the
+     alternative object pointer after the --profile option.

+
+  
14.3 Containers Library

+
+  
The container sub-profile provides persistence support for
+     Qt containers. To enable only this profile, pass
+     qt/containers to the --profile ODB compiler
+     option.

+
+  
The currently supported ordered containers are QVector,
+     QList, and QLinkedList. Supported map
+     containers are QMap, QMultiMap,
+     QHash, and QMultiHash. The supported set
+     container is QSet. For more information on using
+     containers with ODB refer to Chapter 5, "Containers".
+     The following example shows how the QSet container may
+     be used within a persistent object.

+
+
+#pragma db object
+class Person
+{
+  ...
+  QSet<QString> emails_;
+};
+

+
+  
14.4 Date Time Types

+
+  
The date-time sub-profile provides persistence support for
+     the Qt date-time types. To enable only this profile, pass
+     qt/date-time to the --profile ODB compiler
+     option.

+
+  
The currently supported date-time types are QDate,
+     QTime, and QDateTime. The manner in which
+     these types are persisted is database system dependent and is
+     discussed in the sub-sections that follow. The example below shows how
+     QDate may be used within a persistent object.

+
+
+#pragma db object
+class Person
+{
+  ...
+  QDate dateOfBirth_;
+};
+

+
+  
The single concrete exception that can be thrown by the
+     date-time sub-profile implementation is presented below.

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

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

+
+  
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 it is thrown is database
+     system dependent and is discussed in more detail in the
+     following sub-sections.

+
+  
14.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.

+
+  
+  
+    
+      
+      
+    
+
+    
+      
+      
+    
+
+    
+      
+      
+    
+
+    
+      
+      
+    
+  
Qt Date Time TypeMySQL Type
QDateDATE
QTimeTIME
QDateTimeDATETIME

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

+
+  
The date-time sub-profile implementation also provides
+     support for mapping QDateTime 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 Person
+{
+  ...
+  #pragma db type("TIMESTAMP")
+  QDateTime updated_;
+};
+

+
+  
Some valid Qt date-time values cannot be stored in a MySQL database.  An
+     attempt to persist a Qt 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.

+
+  
14.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.

+
+  
+  
+    
+      
+      
+    
+
+    
+      
+      
+    
+
+    
+      
+      
+    
+
+    
+      
+      
+    
+  
Qt Date Time TypeSQLite Type
QDateTEXT
QTimeTEXT
QDateTimeTEXT

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

+
+  
The date-time sub-profile implementation also provides
+     support for mapping QDate and QDateTime to the
+     SQLite INTEGER type, with the integer value representing the
+     UNIX time. Similarly, an alternative mapping for QTime to
+     the INTEGER type represents a clock time as the number of
+     seconds since midnight. These mappings have to be explicitly requested
+     using the db type pragma
+     (Section 9.3.3,value "type"), as shown
+     in the following example:

+
+
+#pragma db object
+class Person
+{
+  ...
+  #pragma db type("INTEGER")
+  QDate born_;
+};
+

+
+  
Some valid Qt date-time values cannot be stored in an SQLite database.
+     An attempt to persist any Qt date-time value representing a negative UNIX
+     time (any point in time prior to the 1970-01-01 00:00:00 UNIX time
+     epoch) as an SQLite INTEGER will result in the
+     out_of_range exception.

+
   
 
 
-
 
 
-- 
cgit v1.1