GNOME.org
 

[libgda] Updated GdaData documentation. Added API to DbTable interface.

commit dd36e57ef1ddf363d1533e340fc0ee8984699634
Author: Daniel Espinosa <despinosa src gnome org>
Date:   Wed Mar 28 15:12:09 2012 -0600

    Updated GdaData documentation. Added API to DbTable interface.
    
    * Updated documentation for Record, Table and diagrams
    * Added set_field() and get_field() methods to DbTable interface

 doc/mallard/gda-data/Record-Class.page    |   25 ++++-
 doc/mallard/gda-data/Table-Class.page     |  145 +++++++++++++++++++++++++++++
 doc/mallard/gda-data/classes-uml.png      |  Bin 26915 -> 23714 bytes
 doc/mallard/gda-data/interfaces-uml.png   |  Bin 35653 -> 35294 bytes
 doc/mallard/gda-data/record-class-uml.png |  Bin 12398 -> 16252 bytes
 doc/mallard/gda-data/table-class-uml.png  |  Bin 0 -> 25406 bytes
 libgda/data/DbTable.vala                  |    3 +
 7 files changed, 169 insertions(+), 4 deletions(-)
---
diff --git a/doc/mallard/gda-data/Record-Class.page b/doc/mallard/gda-data/Record-Class.page
index a508ee6..c2cbd92 100644
--- a/doc/mallard/gda-data/Record-Class.page
+++ b/doc/mallard/gda-data/Record-Class.page
@@ -20,7 +20,7 @@
   <code>Record</code> class is an implementation of <code>DbRecord</code> interface. It uses GDA to get access to a database's row in a table.
   </p>
   <p>
-  In order to load data, you need to set a table and a key. Then <code>update()</code> method execute a SELECT command using the key to find the required row in the table.
+  In order to load data, you need to set a <code>Gda.Connection</code>, a table and a key. Then <code>update()</code> method execute a SELECT command using the key to find the required row in the table.
   </p>
   <section id="record-uml">
   <title>Record class UML definition</title>
@@ -49,10 +49,10 @@
   <p>In the above code, connection is opened before to be set to <code>Record.connection</code> property. You need to setup a <code>Table</code> class to set to <code>Record.table</code> property, but just set <code>Table.name</code> property to the table's name is required. Use <code>Record.set_key_value()</code> method to set the value to the column used in the table as the primary key and to allow <code>update()</code> method to find the correct row (the WHERE clause in SELECT statement), if more than one key exists you must set it; you must know the column and type of value to set.
   </p>
   </section>
-  <section id="record-save">
+  <section id="record-append">
   <title>Using a Record class to add a new row in a table</title>
   <listing>
-  <desc>This record setup a row to be added to a database's table</desc>
+  <desc>This code set up a row to be added to a database's table</desc>
   <code mime="text/x-c++src">
   var r = new Record ();
   var t = new Table ();
@@ -61,7 +61,7 @@
   r.connection = connection;
   r.set_field_value ("name", "Clausse Rayman");
   r.set_field_value ("company", "Packing Sources, Ltd.");
-  r.save ();
+  r.append ();
   </code>
   </listing>
   <p>
@@ -71,6 +71,23 @@
   <code>Record.set_field_value()</code> doesn't know if the columns and type is correct, just store the value to used in an INSERT statement; if key is set by database engine it will be added automatically, if not you must set it in order to execute <code>save()</code> with no errors.
   </p>
   </section>
+  <section>
+  <title>Update data in a row</title>
+  <p>
+  Once you have set a key and a table to a <code>Record</code> object, you can call <code>Record.set_field_value()</code> to change row's column's values, once done, you can call <code>Record.save()</code> to call an UPDATE command and update database's row/column values.
+  </p>
+  <listing>
+  <title>Updating columns' values</title>
+  <desc>This code sets a key and a table to find a row and set a column's value, then call save() to update data in the database</desc>
+  <code>
+  var r = new Record ();
+  r.connection = connection;
+  r.set_key_value ("id", 1);
+  r.set_field_value ("name", "Jack Swan");
+  r.save ();
+  </code>
+  </listing>
+  </section>
   <section id="record-subclass">
   <title>Subclassing Record class</title>
   <p>
diff --git a/doc/mallard/gda-data/Table-Class.page b/doc/mallard/gda-data/Table-Class.page
new file mode 100644
index 0000000..d7f365c
--- /dev/null
+++ b/doc/mallard/gda-data/Table-Class.page
@@ -0,0 +1,145 @@
+<page xmlns="http://projectmallard.org/1.0/";
+	 type="topic" id="table-class">
+
+  <info>
+    <revision pkgversion="5.2" version="0.1" date="2012-03-28" status="incomplete" />
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>despinosa src gnome org</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+    <link type="topic" xref="classes" />
+  </info>
+
+  <title>
+    Table class
+  </title>
+  <p>
+  <code>Table</code> class is an implementation of <code>DbTable</code> interface. It uses GDA to get access to a database's table description.
+  </p>
+  <p>
+  In order to load data, you need to set a <code>Gda.Connection</code> and a table's name. Then <code>update()</code> method will introspect table information using GDA's MetaStore object and executing SELECT commands to retrive meta data to strore store it, you don't need to call update() again unless your table definition has changed.
+  </p>
+  <section id="table-uml">
+  <title>Table class UML definition</title>
+  <figure>
+  <title>UML definition</title>
+  <desc>This diagram describes Table class and its implementations.</desc>
+  <media type="image" mime="image/png" src="table-class-uml.png"/>
+</figure>
+  </section>
+  <section id="table-update">
+  <title>Using a Table class to access a table meta data</title>
+  <listing>
+  <desc>
+  This codes initiate a Table class, set a name and a connection in order to call update()
+  </desc>
+  <code mime="text/x-c++src">
+  var t = new Table ();
+  t.name = "customer";
+  t.connection = connection;
+  t.update ();
+  </code>
+  </listing>
+  <p>In the above code, connection is opened before to be set to <code>Table.connection</code> property. You need to set <code>Table.name</code> property. Internally <code>Gda.Connection.update_meta_store()</code> is called, this could take some time, then executes some SELECT commands to introspect table, columns description are stored in <code>DbFiledInfo</code> objects.
+  </p>
+  </section>
+  <section id="table-append">
+  <title>Using a Table class to add a new table</title>
+  <listing>
+  <desc>This setup a table to be added to a database's table</desc>
+  <code mime="text/x-c++src">
+  var t = new Table ();
+  t.name = "created_table";
+  t.connection = connection;
+  var field = new FieldInfo ();
+  // Setup column id
+  field.name = "id";
+  field.value_type = typeof (int);
+  field.attributes = DbFieldInfo.Attribute.PRIMARY_KEY | 
+                     DbFieldInfo.Attribute.AUTO_INCREMENT;
+  t.set_field (field);
+  
+  // Setup column name
+  var field1 = new FieldInfo ();
+  field1.name = "name";
+  field1.value_type = typeof (string);
+  field1.attributes = DbFieldInfo.Attribute.NONE;
+  t.set_field (field1);
+  
+  // Setup column company
+  var field2 = new FieldInfo ();
+  field2.name = "company";
+  field2.value_type = typeof (int);
+  field2.default_value = 1;
+  
+  // Setup column's foreign key
+  var fk = new DbFieldInfo.ForeignKey ();
+  var rt = new Table ();
+  rt.name = "company";
+  fk.reftable = rt;
+  fk.refcol.add ("id");
+  fk.update_rule = DbFieldInfo.ForeignKey.Rule.CASCADE;
+  fk.delete_rule = DbFieldInfo.ForeignKey.Rule.SET_DEFAULT;
+  field2.fkey = fk;
+  t.set_field (field2);
+  
+  // Append new table
+  t.append ();
+  </code>
+  </listing>
+  <p>
+  In the above code a new table will be added. Create a new <code>Table</code> object, set its name and connection, use <code>Table.set_field()</code> to set column definitions. You must create <code>DbFieldInfo</code> objects, setting its name, type and attributes is enough to be set in a table. If your column must be a PRIMARY KEY you must set <code>DbFieldInfo.attributes</code> to <code>DbFieldInfo.Attribute.PRIMARY_KEY</code>; if it is autoincrement key you must use <code>|</code> operator to add a <code>DbFieldInfo.Attribute.AUTO_INCREMENT</code> attribute.
+  </p>
+  <p>
+  If the column will refer to a column in other table as a foreign key you must set <code>DbFieldInfo.fkey</code>. ForeignKey object is used for column's foreign keys.
+  </p>
+  </section>
+  <section id="table-fields">
+  <title>Iterating through Fields definitions</title>
+  <p>
+  You can iterate over <code>Table</code>'s fields descriptions using Vala <code>foreach</code> statement, by using <code>Record.fields</code> property; it's a <code>Gee.Collection</code> of <code>DbFieldInfo</code> objects, then you can use:
+  </p>
+    <code mime="text/x-c++src">
+  foreach (DbFieldInfo f in table.fields) {
+    /* work with DbField object */
+  }
+  </code>
+  <p>
+  The same apply for all keys you set by using <code>Table.primary_keys</code> property.
+  </p>
+  </section>
+  <section>
+  <title>Access rows in a table</title>
+  <p>
+  All rows in a table can be accessed using <code>Table.records</code> property, as a <code>Gee.Collection</code> of <code>DbRecord</code> objects. Internally, when this property is accessed a "SELECT * FROM table" SQL command is executed, you can filter them using <code>Gee.Traversable.filter()</code> function.
+  </p>
+  <note style="tip">
+  <p>
+  <code>Table.records</code> is a <code>RecordCollection</code> object that implements <code>DbRecordCollection</code> and its pre-requisites: <code>Gee.Collection</code>, <code>Gee.Traversable</code> and <code>Gee.Iterable</code>
+  </p>
+  </note>
+  <note style="tip">
+  <p>
+  Future implementations will include a way to create powerful filter to be used when SQL command is executed to avoid load all rows and iterate all over them when using <code>Gee.Traversable.filter()</code>.
+  </p>
+  </note>
+  </section>
+  <section id="table-dependencies">
+  <title>Table's dependencies</title>
+  <section id="table-dependencies-depends">
+  <title>ForeignKeys</title>
+  <p>
+  When you call <code>Table.update()</code>, you can access to all <code>DbTable</code> objects referenced in foreign keys for each column in the table definition, using <code>Table.depends</code>, through a <code>Gee.Collection</code> of <code>DbTable</code> objects.
+  </p>
+  </section>
+  <section id="table-dependencies-referenced">
+  <title>Tables referencing your table</title>
+  <p>
+  Using <code>Table.referenced</code> property, you can access to a <code>Gee.Collection</code> of <code>DbTable</code> objects that depends on your table.
+  </p>
+  </section>
+  </section>
+</page>
diff --git a/doc/mallard/gda-data/classes-uml.png b/doc/mallard/gda-data/classes-uml.png
index 43f0820..526b49a 100644
Binary files a/doc/mallard/gda-data/classes-uml.png and b/doc/mallard/gda-data/classes-uml.png differ
diff --git a/doc/mallard/gda-data/interfaces-uml.png b/doc/mallard/gda-data/interfaces-uml.png
index 0eafede..05d95bc 100644
Binary files a/doc/mallard/gda-data/interfaces-uml.png and b/doc/mallard/gda-data/interfaces-uml.png differ
diff --git a/doc/mallard/gda-data/record-class-uml.png b/doc/mallard/gda-data/record-class-uml.png
index b577ae7..a2b0aa5 100644
Binary files a/doc/mallard/gda-data/record-class-uml.png and b/doc/mallard/gda-data/record-class-uml.png differ
diff --git a/doc/mallard/gda-data/table-class-uml.png b/doc/mallard/gda-data/table-class-uml.png
new file mode 100644
index 0000000..ca3f440
Binary files /dev/null and b/doc/mallard/gda-data/table-class-uml.png differ
diff --git a/libgda/data/DbTable.vala b/libgda/data/DbTable.vala
index a2f7153..a89d0ff 100644
--- a/libgda/data/DbTable.vala
+++ b/libgda/data/DbTable.vala
@@ -33,6 +33,9 @@ namespace GdaData
 		public abstract Collection<DbFieldInfo>     fields        { owned get; }
 		public abstract Collection<DbFieldInfo>     primary_keys  { owned get; }
 		
+		public abstract void         set_field (DbFieldInfo field) throws Error;
+		public abstract DbFieldInfo  get_field (string name) throws Error;
+		
 		public enum TableType {
 			NONE,
 			BASE_TABLE,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]