GNOME.org
 

libgda r3322 - in trunk: . doc/C doc/C/tmpl libgda samples samples/BDB samples/DirDataModel samples/MetaStore

Author: vivien
Date: Sat Feb 14 20:07:21 2009
New Revision: 3322
URL: http://svn.gnome.org/viewvc/libgda?rev=3322&view=rev

Log:
2009-02-14  Vivien Malerba <malerba gnome-db org>

	* samples/:
	  - added a new MetaStore example to show some examples of the
	    gda_connection_update_meta_store() function
	  - corrected some examples to compile correctly
	* doc/C:
	* libgda/gda-connection.c: improved documentation


Added:
   trunk/samples/MetaStore/
   trunk/samples/MetaStore/Makefile
   trunk/samples/MetaStore/README
   trunk/samples/MetaStore/example.c
Modified:
   trunk/ChangeLog
   trunk/doc/C/howto.xml
   trunk/doc/C/libgda-4.0-sections.txt
   trunk/doc/C/tmpl/gda-meta-store.sgml
   trunk/doc/C/tmpl/provider-support.sgml
   trunk/libgda/gda-connection.c
   trunk/samples/BDB/access-raw.c
   trunk/samples/DirDataModel/find-duplicates.c
   trunk/samples/Makefile
   trunk/samples/README

Modified: trunk/doc/C/howto.xml
==============================================================================
--- trunk/doc/C/howto.xml	(original)
+++ trunk/doc/C/howto.xml	Sat Feb 14 20:07:21 2009
@@ -415,6 +415,40 @@
     </para>
   </sect1>
 
+  <sect1 id="howto-meta2">
+    <title>Update the meta data about a table</title>
+    <para>
+      For a general overview of the mete data problem, see the
+      <link inkend="howto-meta1">Get information about a table's columns</link> section. Updating the meta data
+      can be done by calling 
+      <link linkend="gda-connection-update-meta-store">gda_connection_update_meta_store()</link> with a %NULL
+      "context" argument, but this
+      call updates the whole meta data which will always do the job, but sometimes one knows that only a
+      part of the meta data need to be updated. Here is an example of how to use a specific
+      <link linkend="GdaMetaContext">GdaMetaContext</link> argument.
+    </para>
+    <para>
+      Specifically the following code
+      updates the meta data regarding the "customers" table:
+      <programlisting><![CDATA[
+GdaConnection *connection=...
+GError *error = NULL;
+GdaMetaContext mcontext = {"_tables", 1, NULL, NULL};
+gboolean result;
+mcontext.column_names = g_new (gchar *, 1);
+mcontext.column_names[0] = "table_name";
+mcontext.column_values = g_new (GValue *, 1);
+g_value_set_string ((mcontext.column_values[0] = gda_value_new (G_TYPE_STRING)), "customers");
+result = gda_connection_update_meta_store (connection, &mcontext, &error);
+gda_value_free (mcontext.column_values[0]);
+if (!result) {
+    /* handle the error */
+    g_error_free (error);
+}]]>
+      </programlisting>
+    </para>
+  </sect1>
+
   <sect1>
     <title>Validate a DML statement</title>
     <para>

Modified: trunk/doc/C/libgda-4.0-sections.txt
==============================================================================
--- trunk/doc/C/libgda-4.0-sections.txt	(original)
+++ trunk/doc/C/libgda-4.0-sections.txt	Sat Feb 14 20:07:21 2009
@@ -1293,8 +1293,6 @@
 gda_meta_store_new_with_file
 gda_meta_store_get_version
 gda_meta_store_extract
-gda_meta_store_modify
-gda_meta_store_modify_with_context
 gda_meta_store_schema_get_structure
 gda_meta_store_get_attribute_value
 gda_meta_store_set_attribute_value
@@ -1448,6 +1446,9 @@
 gda_connection_internal_savepoint_removed
 gda_connection_internal_change_transaction_state
 <SUBSECTION>
+gda_meta_store_modify
+gda_meta_store_modify_with_context
+<SUBSECTION>
 gda_compute_dml_statements
 gda_compute_select_statement_from_update
 gda_compute_unique_table_row_condition

Modified: trunk/doc/C/tmpl/gda-meta-store.sgml
==============================================================================
--- trunk/doc/C/tmpl/gda-meta-store.sgml	(original)
+++ trunk/doc/C/tmpl/gda-meta-store.sgml	Sat Feb 14 20:07:21 2009
@@ -164,32 +164,6 @@
 @Returns: 
 
 
-<!-- ##### FUNCTION gda_meta_store_modify ##### -->
-<para>
-
-</para>
-
- store: 
- table_name: 
- new_data: 
- condition: 
- error: 
- Varargs: 
- Returns: 
-
-
-<!-- ##### FUNCTION gda_meta_store_modify_with_context ##### -->
-<para>
-
-</para>
-
- store: 
- context: 
- new_data: 
- error: 
- Returns: 
-
-
 <!-- ##### FUNCTION gda_meta_store_schema_get_structure ##### -->
 <para>
 

Modified: trunk/doc/C/tmpl/provider-support.sgml
==============================================================================
--- trunk/doc/C/tmpl/provider-support.sgml	(original)
+++ trunk/doc/C/tmpl/provider-support.sgml	Sat Feb 14 20:07:21 2009
@@ -323,6 +323,32 @@
 @newstate: 
 
 
+<!-- ##### FUNCTION gda_meta_store_modify ##### -->
+<para>
+
+</para>
+
+ store: 
+ table_name: 
+ new_data: 
+ condition: 
+ error: 
+ Varargs: 
+ Returns: 
+
+
+<!-- ##### FUNCTION gda_meta_store_modify_with_context ##### -->
+<para>
+
+</para>
+
+ store: 
+ context: 
+ new_data: 
+ error: 
+ Returns: 
+
+
 <!-- ##### FUNCTION gda_compute_dml_statements ##### -->
 <para>
 

Modified: trunk/libgda/gda-connection.c
==============================================================================
--- trunk/libgda/gda-connection.c	(original)
+++ trunk/libgda/gda-connection.c	Sat Feb 14 20:07:21 2009
@@ -2939,7 +2939,36 @@
  * @error: a place to store errors, or %NULL
  *
  * Updates @cnc's associated #GdaMetaStore. If @context is not %NULL, then only the parts described by
- * @context will be updated, and if it is %NULL, then the complete meta store will be updated.
+ * @context will be updated, and if it is %NULL, then the complete meta store will be updated. Detailled
+ * explanations follow:
+ *
+ * In order to keep the meta store's contents in a consistent state, the update process involves updating
+ * the contents of all the tables related to one where the contents change. For example the "_columns"
+ * table (which lists all the columns of a table) depends on the "_tables" table (which lists all the tables
+ * in a schema), so if a row is added, removed or modified in the "_tables", then the "_columns" table's contents
+ * needs to be updated as well regarding that row.
+ *
+ * If @context is %NULL, then the update process will simply overwrite any data that was present in all the
+ * meta store's tables with new (up to date) data even if nothing has changed, without having to build the
+ * tables' dependency tree. This is the recommended way of proceeding when dealing with a meta store which
+ * might be outdated.
+ *
+ * On the other hand, if @context is not %NULL, then a tree of the dependencies has to be built (depending on
+ * @context) and only some parts of the meta store are updated following that dependencies tree. Specifying a
+ * context may be usefull for example in the following situations:
+ * <itemizedlist>
+ *   <listitem><para>One knows that a database object has changed (for example a table created), and
+ *                   may use the @context to request that only the information about that table be updated
+ *             </para></listitem>
+ *   <listitem><para>One is only interrested in the list of views, and may request that only the information
+ *                   about views may be updated</para></listitem>
+ * </itemizedlist>
+ *
+ * Note however that usually <emphasis>more</emphasis> information will be updated than strictly requested by
+ * the @context argument.
+ *
+ * For more information, see the <link linkend="information_schema">Database structure</link> section, and
+ * the <link linkend="howto-meta2">Update the meta data about a table</link> howto.
  *
  * Returns: TRUE if no error occurred
  */

Modified: trunk/samples/BDB/access-raw.c
==============================================================================
--- trunk/samples/BDB/access-raw.c	(original)
+++ trunk/samples/BDB/access-raw.c	Sat Feb 14 20:07:21 2009
@@ -34,7 +34,7 @@
 		c_value= gda_data_model_get_value_at (model, 0, i, &error);
 		if (!c_value) {
 			g_print ("Could not get value from data model: %s\n",
-				 error && error->message ? error->messag : "No detail");
+				 error && error->message ? error->message : "No detail");
 			exit (1);
 		}
 		bin = gda_value_get_binary (c_value);
@@ -44,7 +44,7 @@
 		c_value= gda_data_model_get_value_at (model, 1, i, &error);
 		if (!c_value) {
 			g_print ("Could not get value from data model: %s\n",
-				 error && error->message ? error->messag : "No detail");
+				 error && error->message ? error->message : "No detail");
 			exit (1);
 		}
 		bin = gda_value_get_binary (c_value);
@@ -71,7 +71,7 @@
 			gda_data_model_dump (model, stdout);
 
 			gchar *str = "AAA";
-			GValue *value = gda_value_new_binary (str, 4);
+			GValue *value = gda_value_new_binary ((guchar*) str, 4);
 			if (!gda_data_model_set_value_at (model, 1, 2, value, &error)) {
 				g_print ("Could not set value: %s\n", 
 					 error && error->message ? error->message : "no detail");

Modified: trunk/samples/DirDataModel/find-duplicates.c
==============================================================================
--- trunk/samples/DirDataModel/find-duplicates.c	(original)
+++ trunk/samples/DirDataModel/find-duplicates.c	Sat Feb 14 20:07:21 2009
@@ -138,13 +138,13 @@
 		
 		gda_statement_get_parameters (stmt, &plist, NULL);
 		param = gda_set_get_holder (plist, "dir_name");
-		gda_holder_set_value_str (param, NULL, dirname);
+		g_assert (gda_holder_set_value_str (param, NULL, dirname, NULL));
 		param = gda_set_get_holder (plist, "dir_name2");
-		gda_holder_set_value_str (param, NULL, dirname);
+		g_assert (gda_holder_set_value_str (param, NULL, dirname, NULL));
 		param = gda_set_get_holder (plist, "filename");
-		gda_holder_set_value_str (param, NULL, filename);
+		g_assert (gda_holder_set_value_str (param, NULL, filename, NULL));
 		param = gda_set_get_holder (plist, "filename2");
-		gda_holder_set_value_str (param, NULL, filename);
+		g_assert (gda_holder_set_value_str (param, NULL, filename, NULL));
 		g_object_unref (parser);
 
 		/* list files duplicates */

Modified: trunk/samples/Makefile
==============================================================================
--- trunk/samples/Makefile	(original)
+++ trunk/samples/Makefile	Sat Feb 14 20:07:21 2009
@@ -1,5 +1,5 @@
 SHELL= /bin/sh 
-SUBDIRS = BDB DDL DirDataModel F-Spot Report SimpleExample SqlParserConsole TableCopy Virtual XSLT
+SUBDIRS = BDB DDL DirDataModel F-Spot Report SimpleExample SqlParserConsole TableCopy Virtual XSLT MetaStore
 all:
 	for dir in ${SUBDIRS} ; do ( cd $$dir ; ${MAKE} ) ; done
 clean:

Added: trunk/samples/MetaStore/Makefile
==============================================================================
--- (empty file)
+++ trunk/samples/MetaStore/Makefile	Sat Feb 14 20:07:21 2009
@@ -0,0 +1,12 @@
+CFLAGS = -Wall -g -DGDA_DISABLE_DEPRECATED `pkg-config --cflags libgda-4.0`
+LDFLAGS = `pkg-config --libs libgda-4.0`
+
+all: example
+
+example: example.c
+	$(CC) -o example example.c $(CFLAGS) $(LDFLAGS)
+
+clean:
+	rm -f *~
+	rm -f *.o
+	rm -f example

Added: trunk/samples/MetaStore/README
==============================================================================
--- (empty file)
+++ trunk/samples/MetaStore/README	Sat Feb 14 20:07:21 2009
@@ -0,0 +1,46 @@
+Libgda simple example
+=====================
+
+Description:
+------------
+
+The example in this directory illustrate how to get meta data information (information about
+the database's objects), and specifically the columns of some tables.
+
+The following is done:
+* display columns of the 'customers' table, there should be none as the meta data has not been
+  yet updated
+* update the meta data for the 'customers' table, and show the columns now
+* update the meta data for all the tables, and this time show the columns of the 'products' table
+
+Compiling and running:
+----------------------
+
+To compile (make sure Libgda is installed prior to this):
+> make
+
+and to run:
+> ./example
+
+Output:
+-------
+Running should produce the following output:
+
+Initial metastore state
+No column...
+
+Partial metastore update for table 'customers'...
+Tables' columns:
+  id: gint
+  name: gchararray
+  default_served_by: gint
+  country: gchararray
+  city: gchararray
+
+Partial metastore update for all the tables...
+Tables' columns:
+  ref: gchararray
+  category: gint
+  name: gchararray
+  price: gdouble
+  wh_stored: gint

Added: trunk/samples/MetaStore/example.c
==============================================================================
--- (empty file)
+++ trunk/samples/MetaStore/example.c	Sat Feb 14 20:07:21 2009
@@ -0,0 +1,107 @@
+#include <libgda/libgda.h>
+
+static const gchar* TABLE_NAME = "customers";
+
+/*
+ * Display the contents of the 'data' data model
+ */
+static void
+list_table_columns (GdaDataModel* data)
+{
+	gint nrows;
+
+	nrows = gda_data_model_get_n_rows (data);
+	if (nrows == 0)
+		g_print ("No column...\n");
+	else {
+		gint i;
+		const GValue* col_name;
+		const GValue* col_type;
+
+		g_print ("Tables' columns:\n");
+		for (i = 0; i < nrows; ++ i) {
+			col_name = gda_data_model_get_value_at (data, 0, i, NULL);
+			g_assert (col_name);
+			
+			col_type = gda_data_model_get_value_at (data, 2, i, NULL);
+			g_assert (col_type);
+			
+			printf("  %s: %s\n", g_value_get_string (col_name), g_value_get_string (col_type));
+		}
+	}
+}
+
+int
+main (int argc, char *argv[])
+{
+	GdaConnection* connection;
+	GdaDataModel* data;
+	GError* error = NULL;
+	GValue *value;
+
+	gda_init();
+	error = NULL;
+
+	/* open connection to the SalesTest data source */
+	connection = gda_connection_open_from_dsn ("SalesTest", NULL, GDA_CONNECTION_OPTIONS_NONE, &error);
+	if (!connection) {
+		fprintf (stderr, "%s\n", error->message);
+		return -1;
+	}
+
+	/* Initial meta store, to show it has no information about the TABLE_NAME table */
+	g_print ("Initial metastore state\n");
+	g_value_set_string ((value = gda_value_new (G_TYPE_STRING)), TABLE_NAME);
+	data = gda_connection_get_meta_store_data (connection, GDA_CONNECTION_META_FIELDS, &error, 1, 
+						   "name", value,
+						   NULL);
+	if (!data)
+		return -1;
+	list_table_columns (data);
+	g_object_unref (data);
+
+	/* Request partial update for the table we are interrested in 
+	 * the GdaMetaContext specifies to update the "_tables" table, where the "table_name"
+	 * attribute is TABLE_NAME */
+	g_print ("\nPartial metastore update for table '%s'...\n", TABLE_NAME);
+	GdaMetaContext mcontext = {"_tables", 1, NULL, NULL};
+	mcontext.column_names = g_new (gchar *, 1);
+	mcontext.column_names[0] = "table_name";
+	mcontext.column_values = g_new (GValue *, 1);
+	g_value_set_string ((mcontext.column_values[0] = gda_value_new (G_TYPE_STRING)), TABLE_NAME);
+	if (!gda_connection_update_meta_store (connection, &mcontext, &error))
+		return -1;
+
+	/* Query the same information about the TABLE_NAME table's columns
+	 * this time there should be some information */
+	data = gda_connection_get_meta_store_data (connection, GDA_CONNECTION_META_FIELDS, &error, 1,
+						   "name", value,
+						   NULL);
+	if (!data)
+		return -1;
+	list_table_columns (data);
+	g_object_unref (data);
+
+	/*
+	 * Request partial update for all the tables in the database
+	 */
+	g_print ("\nPartial metastore update for all the tables...\n");
+	GdaMetaContext mcontext2 = {"_tables", 0, NULL, NULL};
+	if (!gda_connection_update_meta_store (connection, &mcontext2, &error))
+		return -1;
+
+	/*
+	 * Get columns of the 'products' table
+	 */
+	gda_value_free (value);
+	g_value_set_string ((value = gda_value_new (G_TYPE_STRING)), "products");
+	data = gda_connection_get_meta_store_data (connection, GDA_CONNECTION_META_FIELDS, &error, 1,
+						   "name", value,
+						   NULL);
+	if (!data)
+		return -1;
+	list_table_columns (data);
+	g_object_unref (data);
+
+	return 0;
+}

Modified: trunk/samples/README
==============================================================================
--- trunk/samples/README	(original)
+++ trunk/samples/README	Sat Feb 14 20:07:21 2009
@@ -16,5 +16,6 @@
 * in XSLT/: example using Libgda's extension to libxslt
 * in DDL/: example using the GdaServerOperation object to perform a CREATE TABLE query
 * in SqlParserConsole/: simple console to test how the GdaSqlParser object parses strings
+* in MetaStore/: simple example to show how to use and update a GdaMetaStore
 
 Good luck and happy hacking!
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]