From a91f7d4d0db038a4d055c9aa9a9baa1c406d0c7a Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Tue, 20 Sep 2011 16:27:01 +0200 Subject: Update documentation with new query syntax for pointers and composites --- NEWS | 26 ++++++++++------ doc/manual.xhtml | 90 +++++++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 84 insertions(+), 32 deletions(-) diff --git a/NEWS b/NEWS index 41aa273..d997127 100644 --- a/NEWS +++ b/NEWS @@ -1,14 +1,5 @@ Version 1.6.0 - * SQLite ODB runtime now enables foreign key constraints checking by - default. While this should not affect correct applications, due to - bugs in SQLite DDL foreign keys support, you may need to temporarily - disable foreign key constraints checking when re-creating the database - schema (the sign that you may need to do so is the "foreign key - constraint failed" exception thrown by the commit() function after the - call to schema_catalog::create_schema()). For more information, refer - to Section 12.5.3, "Foreign Key Constraints" in the ODB manual. - * New function, database::erase_query(), allows the deletion of the database state of multiple objects matching certain criteria. It uses the same query expression as the database::query() function. For more @@ -58,6 +49,23 @@ Version 1.6.0 that can be overridden to implement custom connection establishment and configuration. + * The query expression syntax for object pointers and composite values has + changed. Now, instead of using the scope resolution operator ('::') the + member access via pointer operator (->) is used for object pointers and + the member access operator (.) is used for composite values. Examples of + old and new syntax for pointers, old: query::employer::name + and new: query::employer->name. For composites values, old: + query::name::first and new: query::name.first. + + * SQLite ODB runtime now enables foreign key constraints checking by + default. While this should not affect correct applications, due to + bugs in SQLite DDL foreign keys support, you may need to temporarily + disable foreign key constraints checking when re-creating the database + schema (the sign that you may need to do so is the "foreign key + constraint failed" exception thrown by the commit() function after the + call to schema_catalog::create_schema()). For more information, refer + to Section 12.5.3, "Foreign Key Constraints" in the ODB manual. + * Support for specifying the client character set for the MySQL database. For more information, refer to Section 11.2, "MySQL Database Class" in the ODB manual. diff --git a/doc/manual.xhtml b/doc/manual.xhtml index ba8b309..13c694f 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -2911,6 +2911,36 @@ db.erase_query<person> (query::last == "Doe" && query::are < 30); t.commit (); +

Unlike the query() function, when calling + erase_query() we cannot use members from pointed-to + objects in the query expression. However, we can still use + a member corresponding to a pointer as an ordinary object + member that has the id type of the pointed-to object + (Chapter 6, "Relationships"). This allows us + to compare object ids as well as test the pointer for + NULL. As an example, the following transaction + makes sure that all the employee objects that + reference an employer object that is about to + be deleted are deleted as well. Here we assume that the + employee class contains a pointer to the + employer class. Refer to Chapter 6, + "Relationships" for complete definitions of these + classes.

+ + 
+typedef odb::query<employee> query;
+
+transaction t (db.begin ());
+
+employer& e = ... // Employer object to be deleted.
+
+db.erase_query<employee> (query::employer == e.id ());
+db.erase (e);
+
+t.commit ();
+
+ +

3.11 Executing Native SQL Statements

In some situations we may need to execute native SQL statements @@ -4208,17 +4238,19 @@ unsigned long john_id, jane_id;

We can also use data members from pointed-to objects in database queries (Chapter 4, "Querying the Database"). For each pointer in a persistent class, the query - class defines a nested scope containing members corresponding - to the data members in the pointed-to object. For example, the - query class for the employee object contains - the employer scope (derived from the employer_ - pointer) which in turn contains the name member - (derived from the employer::name_ data member of the - pointed-to object). As a result, we can use the - query::employer::name expression while querying - the database for the employee objects. For example, - the following transaction finds all the employees of Example Inc - that have the Doe last name:

+ class defines a smart pointer-like member that contains members + corresponding to the data members in the pointed-to object. We + can then use the access via pointer syntax (->) + to refer to data members in pointed-to objects. + For example, the query class for the employee object + contains the employer member (its name is derived from the + employer_ pointer) which in turn contains the + name member (its name is derived from the + employer::name_ data member of the pointed-to object). + As a result, we can use the query::employer->name + expression while querying the database for the employee + objects. For example, the following transaction finds all the + employees of Example Inc that have the Doe last name:

 typedef odb::query<employee> query;
@@ -4228,7 +4260,7 @@ session s;
 transaction t (db.begin ());
 
 result r (db->query<employee> (
-  query::employer::name == "Example Inc" && query::last == "Doe"));
+  query::employer->name == "Example Inc" && query::last == "Doe"));
 
 for (result::iterator i (r.begin ()); i != r.end (); ++i)
   cout << i->first_ << " " << i->last_ << endl;
@@ -4236,6 +4268,16 @@ for (result::iterator i (r.begin ()); i != r.end (); ++i)
 t.commit ();
+

A query class member corresponding to a non-inverse + (Section 6.2, "Bidirectional Relationships") object + pointer can also be used as a normal member that has the id type + of the pointed-to object. For example, the following query locates + all the employee objects that don't have an associated + employer object:

+ + 
+result r (db->query<employee> (query::employer.is_null ()));
+

An important concept to keep in mind when working with object relationships is the independence of persistent objects. In particular, @@ -5198,17 +5240,19 @@ class person

We can also use data members from composite value types in database queries (Chapter 4, "Querying the - Database"). For each composite value in a persistent class, - the query class defines a nested scope containing members corresponding - to the data members in the value type. For example, the + Database"). For each composite value in a persistent class, the + query class defines a nested member that contains members corresponding + to the data members in the value type. We can then use the member access + syntax (.) to refer to data members in value types. For example, the query class for the person object presented above - contains the name scope (derived from the name_ - data member) which in turn contains the extras member - (derived from the name::extras_ data member of the - composite value type). This process continues recursively for nested - composite value types and, as a result, we can use the - query::name::extras::nickname expression while querying - the database for the person objects. For example:

+ contains the name member (its name is derived from + the name_ data member) which in turn contains the + extras member (its name is derived from the + name::extras_ data member of the composite value type). + This process continues recursively for nested composite value types + and, as a result, we can use the query::name.extras.nickname + expression while querying the database for the person + objects. For example:

 typedef odb::query<person> query;
@@ -5217,7 +5261,7 @@ typedef odb::result<person> result;
 transaction t (db->begin ());
 
 result r (db->query<person> (
-  query::name::extras::nickname == "Squeaky"));
+  query::name.extras.nickname == "Squeaky"));
 
 ...
 
-- 
cgit v1.1