From 5c0867663937e5af1ca9eb44a8a2b1dfa3aea49c Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Thu, 20 Oct 2011 15:18:35 +0200 Subject: Documentation for readonly members, objects, and values --- doc/manual.xhtml | 402 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 297 insertions(+), 105 deletions(-) (limited to 'doc') diff --git a/doc/manual.xhtml b/doc/manual.xhtml index 26cc64a..20bdf89 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -437,7 +437,8 @@ for consistency. 11.1.1table 11.1.2pointer 11.1.3abstract - 11.1.4callback + 11.1.4readonly + 11.1.5callback @@ -460,19 +461,20 @@ for consistency. 11.3.3null/not_null 11.3.4default 11.3.5options - 11.3.6unordered - 11.3.7index_type - 11.3.8key_type - 11.3.9value_type - 11.3.10value_null/value_not_null - 11.3.11id_options - 11.3.12index_options - 11.3.13key_options - 11.3.14value_options - 11.3.15id_column - 11.3.16index_column - 11.3.17key_column - 11.3.18value_column + 11.3.6readonly + 11.3.7unordered + 11.3.8index_type + 11.3.9key_type + 11.3.10value_type + 11.3.11value_null/value_not_null + 11.3.12id_options + 11.3.13index_options + 11.3.14key_options + 11.3.15value_options + 11.3.16id_column + 11.3.17index_column + 11.3.18key_column + 11.3.19value_column @@ -488,21 +490,22 @@ for consistency. 11.4.7column (object, composite value) 11.4.8column (view) 11.4.9transient - 11.4.10inverse - 11.4.11unordered - 11.4.12table - 11.4.13index_type - 11.4.14key_type - 11.4.15value_type - 11.4.16value_null/value_not_null - 11.4.17id_options - 11.4.18index_options - 11.4.19key_options - 11.4.20value_options - 11.4.21id_column - 11.4.22index_column - 11.4.23key_column - 11.4.24value_column + 11.4.10readonly + 11.4.11inverse + 11.4.12unordered + 11.4.13table + 11.4.14index_type + 11.4.15key_type + 11.4.16value_type + 11.4.17value_null/value_not_null + 11.4.18id_options + 11.4.19index_options + 11.4.20key_options + 11.4.21value_options + 11.4.22id_column + 11.4.23index_column + 11.4.24key_column + 11.4.25value_column @@ -2959,6 +2962,25 @@ db.update (from); t.commit (); +

In ODB persistent classes, composite value types, as well as individual + data members can be declared read-only (see Section + 11.1.4, "readonly (object)", Section + 11.3.6, "readonly (composite value)", and + Section 11.4.10, "readonly + (data member)").

+ +

If an individual data member is declared read-only, then + any changes to this member will be ignored when updating the database + state of an object using any of the above update() + functions. A const data member is automatically treated + as read-only. If a composite value is declared read-only then all its + data members are treated as read-only.

+ +

If the whole object is declared read-only then the database state of + this object cannot be changed. Calling any of the above + update() functions for such an object will result in a + compile-time error.

+

3.10 Deleting Persistent Objects

To delete a persistent object's state from the database we use the @@ -4033,8 +4055,8 @@ private: the order information. In the example above, for instance, the order of person's nicknames is probably not important. To instruct the ODB compiler to ignore the order in ordered containers we can use the - db unordered pragma (Section 11.3.6, - "unordered", Section 11.4.11, + db unordered pragma (Section 11.3.7, + "unordered", Section 11.4.12, "unordered"). For example:

@@ -4287,8 +4309,8 @@ class employee
      use the not_null pragma (Section
      11.4.4, "null/not_null") for
      single object pointers and the value_not_null pragma
-     (Section
-     11.4.16, "value_null/value_not_null")
+     (Section
+     11.4.17, "value_null/value_not_null")
      for containers of object pointers. For example:

 
   
@@ -4657,7 +4679,7 @@ CREATE TABLE employee (
      of these references.

 
   
To eliminate redundant database schema references we can use the
-     inverse pragma (Section 11.4.10,
+     inverse pragma (Section 11.4.11,
      "inverse") which tells the ODB compiler that
      a pointer is the inverse side of a bidirectional relationship.
      Either side of a relationship can be made inverse. For example:

@@ -4701,7 +4723,7 @@ CREATE TABLE employee (
      pointer. Also note that an ordered container (Section
      5.1, "Ordered Containers") of pointers that is an inverse side
      of a bidirectional relationship is always treated as unordered
-     (Section 11.4.11, "unordered")
+     (Section 11.4.12, "unordered")
      because the contents of such a container are implicitly built from
      the direct side of the relationship which does not contain the
      element order (index).

@@ -5506,9 +5528,9 @@ CREATE TABLE person (
   
The same principle applies when a composite value type is used
      as an element of a container, except that instead of
      db column, either the db value_column
-     (Section 11.4.24, "value_column") or
+     (Section 11.4.25, "value_column") or
      db key_column
-     (Section 11.4.23, "key_column")
+     (Section 11.4.24, "key_column")
      pragmas are used to specify the column prefix.

 
   
When a composite value type contains a container, an extra table
@@ -5552,8 +5574,8 @@ CREATE TABLE person (
   

 
   
To customize the container table name we can use the
-     db table pragma (Section
-     11.4.12, "table"), for example:

+     db table pragma (Section
+     11.4.13, "table"), for example:

 
   
 #pragma db value
@@ -7461,9 +7483,15 @@ class person
     
 
     
+      readonly
+      persistent class is read-only
+      11.1.4
+    
+
+    
       callback
       database operations callback
-      11.1.4
+      11.1.5
     
 
   
@@ -7567,7 +7595,36 @@ class contractor: public person
      discussion of persistent class inheritance, refer to
      Chapter 8, "Inheritance".

 
-  
11.1.4 callback

+  
11.1.4 readonly

+
+  
The readonly specifier specifies that the persistent class
+     is read-only. The database state of read-only objects cannot be
+     updated. In particular, this means that you cannot call the
+     database::update() function (Section 3.9,
+     "Updating Persistent Objects") for such objects. For example:

+
+  
+#pragma db object readonly
+class person
+{
+  ...
+};
+  

+
+  
Read-only and read-write objects can derive from each other without
+     any restrictions. When a read-only object derives from a read-write
+     object, the resulting whole object is read-only, including the part
+     corresponding to the read-write base. On the other hand, when a
+     read-write object derives from a read-only object, all the data
+     members that correspond to the read-only base are treated as
+     read-only while the rest is treated as read-write.

+
+  
Note that it is also possible to declare individual data members
+    (Section 11.4.10, "readonly")
+     as well as composite value types (Section 11.3.6,
+     "readonly") as read-only.

+
+  
11.1.5 callback

 
   
The callback specifier specifies the persist class
      member function that should be called before and after a
@@ -7776,7 +7833,7 @@ private:
      result iteration. The semantics of the callback
      specifier for a view are similar to those of the
      callback specifier for an object
-     (Section 11.1.4, "callback")
+     (Section 11.1.5, "callback")
      except that the only events that can trigger a callback
      call in the case of a view are pre_load and
      post_load.

@@ -7827,81 +7884,87 @@ private:
     
 
     
+      readonly
+      composite value type is read-only
+      11.3.6
+    
+
+    
       unordered
       ordered container should be stored unordered
-      11.3.6
+      11.3.7
     
 
     
       index_type
       database type for a container's index type
-      11.3.7
+      11.3.8
     
 
     
       key_type
       database type for a container's key type
-      11.3.8
+      11.3.9
     
 
     
       value_type
       database type for a container's value type
-      11.3.9
+      11.3.10
     
 
     
       value_null/value_not_null
       container's value can/cannot be NULL
-      11.3.10
+      11.3.11
     
 
     
       id_options
       database options for a container's id column
-      11.3.11
+      11.3.12
     
 
     
       index_options
       database options for a container's index column
-      11.3.12
+      11.3.13
     
 
     
       key_options
       database options for a container's key column
-      11.3.13
+      11.3.14
     
 
     
       value_options
       database options for a container's value column
-      11.3.14
+      11.3.15
     
 
     
       id_column
       column name for a container's object id
-      11.3.15
+      11.3.16
     
 
     
       index_column
       column name for a container's index
-      11.3.16
+      11.3.17
     
 
     
       key_column
       column name for a container's key
-      11.3.17
+      11.3.18
     
 
     
       value_column
       column name for a container's value
-      11.3.18
+      11.3.19
     
 
   
@@ -8116,7 +8179,37 @@ class person
      data member (Section 11.4.6,
      "options").

 
-  
11.3.6 unordered

+  
11.3.6 readonly

+
+  
The readonly specifier specifies that the composite
+     value type is read-only. Changes to data members of a read-only
+     composite value type are ignored when updating the database
+     state of an object (Section 3.9, "Updating Persistent
+     Objects") containing such a value type. Note that this specifier
+     is only valid for composite value types. For example:

+
+  
+#pragma db value readonly
+class person_name
+{
+  ...
+};
+  

+
+  
Read-only and read-write composite values can derive from each other
+     without any restrictions. When a read-only value derives from a
+     read-write value, the resulting whole value is read-only, including
+     the part corresponding to the read-write base. On the other hand, when a
+     read-write value derives from a read-only value, all the data
+     members that correspond to the read-only base are treated as
+     read-only while the rest is treated as read-write.

+
+  
Note that it is also possible to declare individual data members
+     (Section 11.4.10, "readonly")
+     as well as whole objects (Section 11.1.4,
+     "readonly") as read-only.

+
+  
11.3.7 unordered

 
   
The unordered specifier specifies that the ordered
      container should be stored unordered in the database. The database
@@ -8133,7 +8226,7 @@ typedef std::vector<std::string> names;
      storage in the database, refer to Section 5.1,
      "Ordered Containers".

 
-  
11.3.7 index_type

+  
11.3.8 index_type

 
   
The index_type specifier specifies the native
      database type that should be used for an ordered container's
@@ -8147,7 +8240,7 @@ typedef std::vector<std::string> names;
 #pragma db value(names) index_type("SMALLINT UNSIGNED")
   

 
-  
11.3.8 key_type

+  
11.3.9 key_type

 
   
The key_type specifier specifies the native
      database type that should be used for a map container's
@@ -8161,7 +8254,7 @@ typedef std::map<unsigned short, float> age_weight_map;
 #pragma db value(age_weight_map) key_type("INT UNSIGNED")
-

11.3.9 value_type

+

11.3.10 value_type

The value_type specifier specifies the native database type that should be used for a container's @@ -8176,11 +8269,11 @@ typedef std::vector<std::string> names;

The value_null and value_not_null - (Section 11.3.10, + (Section 11.3.11, "value_null/value_not_null") specifiers can be used to control the NULL semantics of a value column.

-

11.3.10 value_null/value_not_null

+

11.3.11 value_null/value_not_null

The value_null and value_not_null specifiers specify that a container type's element value can or cannot be @@ -8208,7 +8301,7 @@ typedef std::vector<shared_ptr<account> > accounts; as not allowing a NULL value.

-

11.3.11 id_options

+

11.3.12 id_options

The id_options specifier specifies additional column definition options that should be used for a container's @@ -8221,11 +8314,11 @@ typedef std::vector<std::string> nicknames;

The semantics of the id_options specifier for a container type are similar to those of the id_options specifier for - a container data member (Section 11.4.17, + a container data member (Section 11.4.18, "id_options").

-

11.3.12 index_options

+

11.3.13 index_options

The index_options specifier specifies additional column definition options that should be used for a container's @@ -8238,11 +8331,11 @@ typedef std::vector<std::string> nicknames;

The semantics of the index_options specifier for a container type are similar to those of the index_options specifier for - a container data member (Section 11.4.18, + a container data member (Section 11.4.19, "index_options").

-

11.3.13 key_options

+

11.3.14 key_options

The key_options specifier specifies additional column definition options that should be used for a container's @@ -8255,11 +8348,11 @@ typedef std::map<std::string, std::string> properties;

The semantics of the key_options specifier for a container type are similar to those of the key_options specifier for - a container data member (Section 11.4.19, + a container data member (Section 11.4.20, "key_options").

-

11.3.14 value_options

+

11.3.15 value_options

The value_options specifier specifies additional column definition options that should be used for a container's @@ -8272,11 +8365,11 @@ typedef std::set<std::string> nicknames;

The semantics of the value_options specifier for a container type are similar to those of the value_options specifier for - a container data member (Section 11.4.20, + a container data member (Section 11.4.21, "value_options").

-

11.3.15 id_column

+

11.3.16 id_column

The id_column specifier specifies the column name that should be used to store the object id in a @@ -8290,7 +8383,7 @@ typedef std::vector<std::string> names;

If the column name is not specified, then object_id is used by default.

-

11.3.16 index_column

+

11.3.17 index_column

The index_column specifier specifies the column name that should be used to store the element index in an @@ -8304,7 +8397,7 @@ typedef std::vector<std::string> names;

If the column name is not specified, then index is used by default.

-

11.3.17 key_column

+

11.3.18 key_column

The key_column specifier specifies the column name that should be used to store the key in a map @@ -8318,7 +8411,7 @@ typedef std::map<unsigned short, float> age_weight_map;

If the column name is not specified, then key is used by default.

-

11.3.18 value_column

+

11.3.19 value_column

The value_column specifier specifies the column name that should be used to store the element value in a @@ -8405,93 +8498,99 @@ typedef std::map<unsigned short, float> age_weight_map; + readonly + member is read-only + 11.4.10 + + + inverse member is an inverse side of a bidirectional relationship - 11.4.10 + 11.4.11 unordered ordered container should be stored unordered - 11.4.11 + 11.4.12 table table name for a container - 11.4.12 + 11.4.13 index_type database type for a container's index type - 11.4.13 + 11.4.14 key_type database type for a container's key type - 11.4.14 + 11.4.15 value_type database type for a container's value type - 11.4.15 + 11.4.16 value_null/value_not_null container's value can/cannot be NULL - 11.4.16 + 11.4.17 id_options database options for a container's id column - 11.4.17 + 11.4.18 index_options database options for a container's index column - 11.4.18 + 11.4.19 key_options database options for a container's key column - 11.4.19 + 11.4.20 value_options database options for a container's value column - 11.4.20 + 11.4.21 id_column column name for a container's object id - 11.4.21 + 11.4.22 index_column column name for a container's index - 11.4.22 + 11.4.23 key_column column name for a container's key - 11.4.23 + 11.4.24 value_column column name for a container's value - 11.4.24 + 11.4.25 @@ -8857,7 +8956,100 @@ class person references that are only meaningful in the application's memory, as well as utility members such as mutexes, etc.

-

11.4.10 inverse

+

11.4.10 readonly

+ +

The readonly specifier specifies that a data member of + an object or composite value type is read-only. Changes to a read-only + data member are ignored when updating the database state of an object + (Section 3.9, "Updating Persistent Objects") + containing such a member. Since views are read-only, it is not + necessary to use this specifier for view data members. Object id + (Section 11.4.1, "id") + and inverse (Section 11.4.11, + "inverse") data members are automatically treated + as read-only and must not be explicitly declared as such. For + example:

+ + 
+#pragma db object
+class person
+{
+  ...
+
+  #pragma db readonly
+  date born_;
+};
+
+ +

Besides simple value members, object pointer, container, and composite + value members can also be declared read-only. A change of a pointed-to + object is ignored when updating the state of a read-only object + pointer. Similarly, any changes to the number or order of + elements or to the element values themselves are ignored when + updating the state of a read-only container. Finally, any changes + to the members of a read-only composite value type are also ignored + when updating the state of such a composite value.

+ +

ODB automatically treats const data members as read-only. + For example, the following person object is equivalent + to the above declaration for the database persistence purposes:

+ + 
+#pragma db object
+class person
+{
+  ...
+
+  const date born_; // Automatically read-only.
+};
+
+ +

When declaring an object pointer const, make sure to + declare the pointer as const rather than (or in addition + to) the object itself. For example:

+ + 
+#pragma db object
+class person
+{
+  ...
+
+  const person* father_; // Read-write pointer to a read-only object.
+  person* const mother_; // Read-only pointer to a read-write object.
+};
+
+ +

Note that in case of a wrapper type (Section 7.3, + "Pointers and NULL Value Semantics"), both the + wrapper and the wrapped type must be const in + order for the ODB compiler to automatically treat the data + member as read-only. For example:

+ + 
+#pragma db object
+class person
+{
+  ...
+
+  const std::auto_ptr<const date> born_;
+};
+
+ +

Read-only members are useful when dealing with + asynchronous changes to the state of a data member in the + database which should not be overwritten. In other cases, + where the state of a data member never changes, declaring such a member + read-only allows ODB to perform more efficient object updates. + In such cases, however, it is conceptually more correct to + declare such a data member as const rather than + as read-only.

+ +

Note that it is also possible to declare composite value types + (Section 11.3.6, "readonly") + as well as whole objects (Section 11.1.4, + "readonly") as read-only.

+ +

11.4.11 inverse

The inverse specifier specifies that a data member of an object pointer or a container of object pointers type is an @@ -8895,12 +9087,12 @@ class person relationship information. Only ordered and set containers can be used for inverse members. If an inverse member is of an ordered container type, it is automatically marked as unordered - (Section 11.4.11, "unordered").

+ (Section 11.4.12, "unordered").

For a more detailed discussion of inverse members, refer to Section 6.2, "Bidirectional Relationships".

-

11.4.11 unordered

+

11.4.12 unordered

The unordered specifier specifies that a member of an ordered container type should be stored unordered in the database. @@ -8923,7 +9115,7 @@ class person storage in the database, refer to Section 5.1, "Ordered Containers".

-

11.4.12 table

+

11.4.13 table

The table specifier specifies the table name that should be used to store the contents of a container member. For example:

@@ -8953,7 +9145,7 @@ class person to Section 7.2.1, "Composite Value Column and Table Names" for details.

-

11.4.13 index_type

+

11.4.14 index_type

The index_type specifier specifies the native database type that should be used for an ordered container's @@ -8973,7 +9165,7 @@ class person }; -

11.4.14 key_type

+

11.4.15 key_type

The key_type specifier specifies the native database type that should be used for a map container's @@ -8993,7 +9185,7 @@ class person }; -

11.4.15 value_type

+

11.4.16 value_type

The value_type specifier specifies the native database type that should be used for a container's @@ -9014,11 +9206,11 @@ class person

The value_null and value_not_null - (Section 11.4.16, + (Section 11.4.17, "value_null/value_not_null") specifiers can be used to control the NULL semantics of a value column.

-

11.4.16 value_null/value_not_null

+

11.4.17 value_null/value_not_null

The value_null and value_not_null specifiers specify that a container's element value for a data member can or @@ -9051,7 +9243,7 @@ class account Multiset Containers") the element value is automatically treated as not allowing a NULL value.

-

11.4.17 id_options

+

11.4.18 id_options

The id_options specifier specifies additional column definition options that should be used for a container's @@ -9075,7 +9267,7 @@ class person of the options specifier (Section 11.4.6, "options").

-

11.4.18 index_options

+

11.4.19 index_options

The index_options specifier specifies additional column definition options that should be used for a container's @@ -9096,7 +9288,7 @@ class person of the options specifier (Section 11.4.6, "options").

-

11.4.19 key_options

+

11.4.20 key_options

The key_options specifier specifies additional column definition options that should be used for a container's @@ -9117,7 +9309,7 @@ class person of the options specifier (Section 11.4.6, "options").

-

11.4.20 value_options

+

11.4.21 value_options

The value_options specifier specifies additional column definition options that should be used for a container's @@ -9138,7 +9330,7 @@ class person of the options specifier (Section 11.4.6, "options").

-

11.4.21 id_column

+

11.4.22 id_column

The id_column specifier specifies the column name that should be used to store the object id in a @@ -9162,7 +9354,7 @@ class person

If the column name is not specified, then object_id is used by default.

-

11.4.22 index_column

+

11.4.23 index_column

The index_column specifier specifies the column name that should be used to store the element index in an @@ -9186,7 +9378,7 @@ class person

If the column name is not specified, then index is used by default.

-

11.4.23 key_column

+

11.4.24 key_column

The key_column specifier specifies the column name that should be used to store the key in a map @@ -9210,7 +9402,7 @@ class person

If the column name is not specified, then key is used by default.

-

11.4.24 value_column

+

11.4.25 value_column

The value_column specifier specifies the column name that should be used to store the element value in a -- cgit v1.1