gnue/docbook/GNUeModuleGuide/chapters businesso...

[Neil Tiffin]

CVSROOT:        /home/cvs
Module name:    gnue
Changes by:     Neil Tiffin <address@hidden>    01/05/31 10:25:01

Modified files:
        docbook/GNUeModuleGuide/chapters: businessobjects.sgml 

Log message:
        Add usage and examples to LIST and REFERENCE keywords.  Add Reinhards 
note about deprecating the explicit use of REFERENCE and LIST.

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gnue/docbook/GNUeModuleGuide/chapters/businessobjects.sgml.diff?cvsroot=OldCVS&tr1=1.18&tr2=1.19&r1=text&r2=text

Patches:
Index: gnue/docbook/GNUeModuleGuide/chapters/businessobjects.sgml
diff -u gnue/docbook/GNUeModuleGuide/chapters/businessobjects.sgml:1.18 
gnue/docbook/GNUeModuleGuide/chapters/businessobjects.sgml:1.19
--- gnue/docbook/GNUeModuleGuide/chapters/businessobjects.sgml:1.18     Sun May 
27 19:22:17 2001
+++ gnue/docbook/GNUeModuleGuide/chapters/businessobjects.sgml  Thu May 31 
10:25:01 2001
@@ -7,7 +7,7 @@
                        Introduction 
                </title>
                <para>
-                       This chapter is $Id: businessobjects.sgml,v 1.18 
2001/05/28 02:22:17 ntiffin Exp $. 
+                       This chapter is $Id: businessobjects.sgml,v 1.19 
2001/05/31 17:25:01 ntiffin Exp $. 
                </para>
                <para>
                Quick links to the various sections.
@@ -37,7 +37,7 @@
                                Comments about what should be changed in this 
document (and what is even missing) are very appreciated, because every comment 
possibly reflects on future versions of this document and therefore will make 
the final document better. Please direct your comments to Neil Tiffin 
(address@hidden).
                        </para>
                        <para>
-This chapter was originally written by Neil Tiffin (address@hidden) and comes 
from documents and code originally written by Andrew Murie (address@hidden) and 
coding standard from Reinhard M&uuml;ller(address@hidden). 
+This chapter was originally written by Neil Tiffin (address@hidden) and comes 
from documents and code originally written by Andrew Murie (address@hidden) and 
coding standard from Reinhard M&uuml;ller(address@hidden). Some examples 
contributed by Stanley A. Klein.
                        </para>
                        <para>
                                GNUe business objects are defined in GNUe Class 
Files (GCD). These files have the extension ".gcd". This chapter discusses the 
format of GCD files. Business objects are processed by the GEAS server. If you 
are using GNUe Forms in 2-tier mode then things work a little differently.
@@ -216,6 +216,11 @@
     module_name::class_name
 
 </programlisting>
+<para>
+       In each class GEAS automatically includes a unique 128 bit object
+identifier called objectid, which is stored as a char<32>.  So in the
+previous example, the first field is module_name::class_name.objectid.
+</para>
                </sect2>
                <sect2 id=extend>
                        <title id=extend.title>
@@ -256,12 +261,12 @@
 
   EXTEND base::item
   {
-       int   quantity_on_hand;
+    int   quantity_on_hand;
   };
     
 </programlisting>
 <para>
-Note that the extend defintion exists outside of any module definition even if 
it is defined inside a module definition.  This is really produces the same 
results as if it had been originally defined as:
+Note that the extend defintion exists outside of any module definition even if 
it is defined inside a module definition.  This produces the same results as if 
it had been originally defined as:
 </para>
 <programlisting>
 
@@ -568,6 +573,20 @@
                        <title id=lookup.title>
                                LOOKUP
                        </title>
+<note><title>Use of LOOKUP, REFERENCE, and LIST</title>
+<para>
+       We are not really happy with the LOOKUP, REFERENCE and LIST keywords. 
They make it possible to link tables together with a field that is not the 
primary key, even with a field that is not guaranteed to have an unique value.
+</para>
+<para>
+       What we would rather like it if geas made it possible to define any 
field of an object explicitely as the primary key of the table, and that all 
references would use _that_ field for the foreign key. Only if no field was 
explicitely defined as primary key, geas would create the implicite objectid.  
But that's way ahead.
+</para>
+<para>
+       Meanwhile we expect that the usage of the LOOKUP, REFERENCE and LIST 
syntax will be depreciated.
+</para>
+<para>
+       Apart from that, we will in most cases use the objectid as the primary 
key; we have discussed that in detail some time ago and widely agreed on not 
having user-visible primary keys.
+</para>
+</note>
 <para>
        The lookup type is used to lookup a field from another class. A LOOKUP
 can be defined where a field is defined in the class definition.
@@ -593,13 +612,28 @@
        if src_class.src_fld equal comp_field then
            src_class.src_data is copied into new_fld_name
 </programlisting>
+
                </sect2>
                <sect2 id=reference>
                        <title id=reference.title>
                                REFERENCE
                        </title>
+<note><title>Use of LOOKUP, REFERENCE, and LIST</title>
+<para>
+       We are not really happy with the LOOKUP, REFERENCE and LIST keywords. 
They make it possible to link tables together with a field that is not the 
primary key, even with a field that is not guaranteed to have an unique value.
+</para>
+<para>
+       What we would rather like it if geas made it possible to define any 
field of an object explicitely as the primary key of the table, and that all 
references would use _that_ field for the foreign key. Only if no field was 
explicitely defined as primary key, geas would create the implicite objectid.  
But that's way ahead.
+</para>
+<para>
+       Meanwhile we expect that the usage of the LOOKUP, REFERENCE and LIST 
syntax will be depreciated.
+</para>
 <para>
-       The reference type is used to get a complete instance of a class 
object. A
+       Apart from that, we will in most cases use the objectid as the primary 
key; we have discussed that in detail some time ago and widely agreed on not 
having user-visible primary keys.
+</para>
+</note>
+<para>
+       The explicit reference type is used to get a complete instance of a 
class object. A
 REFERENCE can be defined where a field is in the class definition.  Its
 syntax is nearly the same as LOOKUP.
 </para>
@@ -615,9 +649,8 @@
     new_fld_name - is the new field name for reference in the class. It
          does not result in a table column in the database.
     
-    src_class - is the name of the source class used to find the lookup
-         data.  If this class is in a different module then is requires
-         a fully qualified name.
+    src_class - is the fully qualified name of the source class used to 
+         find the lookup data.
          
     src_field - is the field in the src_class used for comparison.
     
@@ -633,6 +666,33 @@
 </para>
 
 <para>
+       In the following example, order2 represents an explicit REFERENCE and 
order1 represents an implicit REFERENCE.  Each field references the specific 
instance of the order:master object from the order::detail object.  In the case 
of the implicit REFERENCE (order1) the reference is make by using the objectid 
of order::master.  In the case of the explicit REFERENCE (order2) the field 
order_number is used to relate the objects. 
+</para>
+<programlisting>
+<![CDATA[
+MODULE order
+{
+  class master
+  {
+    int     order_number;
+    char    stuff<20>;
+    int     more_stuff;
+    char    the_last_stuff<20>; 
+  };
+
+class detail
+  {
+    int       order_number;
+    REFERENCE        order2 : order::master(order_number) = this.order_number;
+    order::master [] order1;
+    int       detail_stuff;
+    char      last_detail_stuff;
+  };
+};
+]]>
+
+</programlisting>
+<para>
        REFERENCE is used to implement many to one relationships.
        A short hand way to create a REFERENCE is to use the following syntax:
 </para>
@@ -665,6 +725,20 @@
                                LIST
                        </title>
 
+<note><title>Use of LOOKUP, REFERENCE, and LIST</title>
+<para>
+       We are not really happy with the LOOKUP, REFERENCE and LIST keywords. 
They make it possible to link tables together with a field that is not the 
primary key, even with a field that is not guaranteed to have an unique value.
+</para>
+<para>
+       What we would rather like it if geas made it possible to define any 
field of an object explicitely as the primary key of the table, and that all 
references would use _that_ field for the foreign key. Only if no field was 
explicitely defined as primary key, geas would create the implicite objectid.  
But that's way ahead.
+</para>
+<para>
+       Meanwhile we expect that the usage of the LOOKUP, REFERENCE and LIST 
syntax will be depreciated.
+</para>
+<para>
+       Apart from that, we will in most cases use the objectid as the primary 
key; we have discussed that in detail some time ago and widely agreed on not 
having user-visible primary keys.
+</para>
+</note>
 <para>
        The LIST type is used to get multiple instances of a class object. A
 LIST can be defined where a field is defined in the class definition.  Its
@@ -718,6 +792,31 @@
 container.getReference(fieldname) from the client code and let GEAS handle
 the reference automatically.
 </para>
+<para>
+       In the following example, detail1 represents an explicit LIST and 
detail2 represents an implicit LIST.  Each field references the specific 
instances of the order:detail objects from the order::master object.  In the 
case of the implicit LIST reference (detail2) the reference is make by using 
the objectid's of order::detail.  In the case of the explicit LIST reference 
(detail1) the field order_number is used to relate the objects. 
+</para>
+
+<programlisting>
+<![CDATA[
+MODULE order
+{
+  class master
+  {
+    int               order_number;
+    LIST              detail1 : order::detail(order_number) = 
this.order_number;
+    order::detail  [] detail2;
+  }; 
+
+class detail
+  {
+    int       order_number;
+    int       detail_stuff;
+    char      last_detail_stuff;
+  };
+};
+]]>
+
+</programlisting>
 
                </sect2>
                <sect2 id=method>