GdaMetaStore

GdaMetaStore — Dictionary object

Synopsis




                    GdaMetaStore;
enum                GdaMetaStoreError;
                    GdaMetaStoreChange;
enum                GdaMetaStoreChangeType;
                    GdaMetaContext;
GdaMetaStore*       gda_meta_store_new                  (const gchar *cnc_string);
GdaMetaStore*       gda_meta_store_new_with_file        (const gchar *file_name);
gint                gda_meta_store_get_version          (GdaMetaStore *store);
GdaDataModel*       gda_meta_store_extract              (GdaMetaStore *store,
                                                         const gchar *select_sql,
                                                         GError **error,
                                                         ...);
gboolean            gda_meta_store_modify               (GdaMetaStore *store,
                                                         const gchar *table_name,
                                                         GdaDataModel *new_data,
                                                         const gchar *condition,
                                                         GError **error,
                                                         ...);
gboolean            gda_meta_store_modify_with_context  (GdaMetaStore *store,
                                                         GdaMetaContext *context,
                                                         GdaDataModel *new_data,
                                                         GError **error);
GdaMetaStruct*      gda_meta_store_schema_get_structure (GdaMetaStore *store,
                                                         GError **error);
gboolean            gda_meta_store_get_attribute_value  (GdaMetaStore *store,
                                                         const gchar *att_name,
                                                         gchar **att_value,
                                                         GError **error);
gboolean            gda_meta_store_set_attribute_value  (GdaMetaStore *store,
                                                         const gchar *att_name,
                                                         const gchar *att_value,
                                                         GError **error);
gboolean            gda_meta_store_schema_add_custom_object
                                                        (GdaMetaStore *store,
                                                         const gchar *xml_description,
                                                         GError **error);
GdaConnection*      gda_meta_store_get_internal_connection
                                                        (GdaMetaStore *store);

Object Hierarchy


  GObject
   +----GdaMetaStore

Properties


  "catalog"                  gchararray            : Write / Construct Only
  "cnc"                      GdaConnection         : Read / Write / Construct Only
  "cnc-string"               gchararray            : Write / Construct Only
  "schema"                   gchararray            : Write / Construct Only

Signals


  "meta-changed"                                   : Run First
  "meta-reset"                                     : Run First
  "suggest-update"                                 : Run Last

Description

Previous versions of libgda relied on an XML based file to store dictionary information, such as the database's schema (tables, views, etc) and various other information. The problems were that it was difficult for an application to integrate its own data into the dictionary and that there were some performances problems as the XML file needed to be parsed (and converted into its own in-memory structure) before any data could be read out of it.

The new dictionary now relies on a database structure to store its data. The actual database can be a single file (using an SQLite database), an entirely in memory database (also using an SQLite database), or a more conventional backend such as a PostgreSQL database for a shared dictionary on a server.

libgda imposes its own structure (based on objects such as tables and views which name starts with an underscore '_'), but a user can also add its own tables or other database objects. The following diagram shows the tables defined by libgda for its internal needs:

Dictioanry's tables and views initially defined by libgda

Details

GdaMetaStore

typedef struct _GdaMetaStore GdaMetaStore;


enum GdaMetaStoreError

typedef enum {
	GDA_META_STORE_INCORRECT_SCHEMA,
	GDA_META_STORE_UNSUPPORTED_PROVIDER,
	GDA_META_STORE_INTERNAL_ERROR,
	GDA_META_STORE_META_CONTEXT_ERROR,
	GDA_META_STORE_MODIFY_CONTENTS_ERROR,
	GDA_META_STORE_EXTRACT_SQL_ERROR,
	GDA_META_STORE_ATTRIBUTE_NOT_FOUND_ERROR,
	GDA_META_STORE_ATTRIBUTE_ERROR,
	GDA_META_STORE_SCHEMA_OBJECT_NOT_FOUND_ERROR,
	GDA_META_STORE_SCHEMA_OBJECT_CONFLICT_ERROR,
	GDA_META_STORE_SCHEMA_OBJECT_DESCR_ERROR,
	GDA_META_STORE_TRANSACTION_ALREADY_STARTED_ERROR
} GdaMetaStoreError;


GdaMetaStoreChange

typedef struct {
	/* change general information */
	GdaMetaStoreChangeType  c_type;
	gchar                  *table_name;
	GHashTable             *keys; /* key = ('+' or '-') and a column position in @table (string) starting at 0, 
	                               * value = a GValue pointer */
} GdaMetaStoreChange;


enum GdaMetaStoreChangeType

typedef enum {
	GDA_META_STORE_ADD,
	GDA_META_STORE_REMOVE,
	GDA_META_STORE_MODIFY,
} GdaMetaStoreChangeType;


GdaMetaContext

typedef struct {
	gchar                  *table_name;
	gint                    size;
	gchar                 **column_names;
	GValue                **column_values;
} GdaMetaContext;


gda_meta_store_new ()

GdaMetaStore*       gda_meta_store_new                  (const gchar *cnc_string);

Create a new GdaMetaStore object.

cnc_string :
Returns : the newly created object, or NULL if an error occurred

gda_meta_store_new_with_file ()

GdaMetaStore*       gda_meta_store_new_with_file        (const gchar *file_name);

Create a new GdaMetaStore object using file_name as its internal database

file_name : a file name
Returns : the newly created object, or NULL if an error occurred

gda_meta_store_get_version ()

gint                gda_meta_store_get_version          (GdaMetaStore *store);

Get store's internal schema's version

Retunrs: the version (1 at the moment)

store : a GdaMetaStore object
Returns :

gda_meta_store_extract ()

GdaDataModel*       gda_meta_store_extract              (GdaMetaStore *store,
                                                         const gchar *select_sql,
                                                         GError **error,
                                                         ...);

Extracts some data stored in store using a custom SELECT query.

store : a GdaMetaStore object
select_sql : a SELECT statement
error : a place to store errors, or NULL
... : a list of (variable name (gchar *), GValue *value) terminated with NULL, representing values for all the variables mentionned in select_sql. If there is no variable then this part can be omitted.
Returns : a new GdaDataModel, or NULL if an error occurred

gda_meta_store_modify ()

gboolean            gda_meta_store_modify               (GdaMetaStore *store,
                                                         const gchar *table_name,
                                                         GdaDataModel *new_data,
                                                         const gchar *condition,
                                                         GError **error,
                                                         ...);

Propagates an update to store, the update's contents is represented by new_data, this function is primarily reserved to database providers.

For example tell store to update its list of tables, new_data should contain the same columns as the "_tables" table of store, and contain one row per table in the store; there should not be any more argument after the error argument.

Now, to update only one table, the new_data data model should have one row for the table to update (or no row at all if the table does not exist anymore), and have values for the promary key of the "_tables" table of store, namely "table_catalog", "table_schema" and "table_name".

store : a GdaMetaStore object
table_name : the name of the table to modify within store
new_data : a GdaDataModel containing the new data to set in table_name, or NULL (treated as a data model with no row at all)
condition : SQL expression (which may contain variables) defining the rows which are being obsoleted by new_data, or NULL
error : a place to store errors, or NULL
... : a list of (variable name (gchar *), GValue *value) terminated with NULL, representing values for all the variables mentionned in condition.
Returns : TRUE if no error occurred

gda_meta_store_modify_with_context ()

gboolean            gda_meta_store_modify_with_context  (GdaMetaStore *store,
                                                         GdaMetaContext *context,
                                                         GdaDataModel *new_data,
                                                         GError **error);

Propagates an update to store, the update's contents is represented by new_data, this function is primarily reserved to database providers.

store : a GdaMetaStore object
context : a GdaMetaContext context describing what to modify in store
new_data : a GdaDataModel containing the new data to set in table_name, or NULL (treated as a data model with no row at all)
error : a place to store errors, or NULL
Returns : TRUE if no error occurred

gda_meta_store_schema_get_structure ()

GdaMetaStruct*      gda_meta_store_schema_get_structure (GdaMetaStore *store,
                                                         GError **error);

Creates a new GdaMetaStruct object representing store's interal database structure.

store : a GdaMetaStore object
error : a place to store errors, or NULL
Returns : a new GdaMetaStruct object, or NULL if an error occurred

gda_meta_store_get_attribute_value ()

gboolean            gda_meta_store_get_attribute_value  (GdaMetaStore *store,
                                                         const gchar *att_name,
                                                         gchar **att_value,
                                                         GError **error);

The GdaMetaStore object maintains a list of (name,value) attributes (attributes names starting with a '_' character are for intarnal use only and cannot be altered). This method and the gda_meta_store_set_attribute_value() method allows the user to add, set or remove attributes specific to their usage.

This method allows to get the value of a attribute stored in store. The returned attribute value is placed at att_value, the caller is responsible to free that string.

If there is no attribute named att_name then att_value is set to NULL and error will contain the GDA_META_STORE_ATTRIBUTE_NOT_FOUND_ERROR error code, and FALSE is returned.

store : a GdaMetaStore object
att_name : name of the attribute to get
att_value : the place to store the attribute value
error : a place to store errors, or NULL
Returns : TRUE if no error occurred

gda_meta_store_set_attribute_value ()

gboolean            gda_meta_store_set_attribute_value  (GdaMetaStore *store,
                                                         const gchar *att_name,
                                                         const gchar *att_value,
                                                         GError **error);

Set the value of the attribute named att_name to att_value; see gda_meta_store_get_attribute_value() for more information.

store : a GdaMetaStore object
att_name : name of the attribute to set
att_value : value of the attribute to set, or NULL to unset the attribute
error : a place to store errors, or NULL
Returns : TRUE if no error occurred

gda_meta_store_schema_add_custom_object ()

gboolean            gda_meta_store_schema_add_custom_object
                                                        (GdaMetaStore *store,
                                                         const gchar *xml_description,
                                                         GError **error);

The internal database used by store can be 'augmented' with some user-defined database objects (such as tables or views). This method allows one to add a new database object.

If the internal database already contains the object, then:

  • if the object is equal to the provided description then TRUE is returned

  • if the object exists but differs from the provided description, then FALSE is returned, with the GDA_META_STORE_SCHEMA_OBJECT_CONFLICT_ERROR error code

store : a GdaMetaStore object
xml_description : an XML description of the table or view to add to store
error : a place to store errors, or NULL
Returns : TRUE if the new object has sucessfully been added

gda_meta_store_get_internal_connection ()

GdaConnection*      gda_meta_store_get_internal_connection
                                                        (GdaMetaStore *store);

Get a pointer to the GdaConnection object internally used by store to store its contents.

The returned connection can be used to access some other data than the one managed by store itself. Don not close the connection.

store : a GdaMetaStore object
Returns : a GdaConnection, or NULL

Property Details

The "catalog" property

  "catalog"                  gchararray            : Write / Construct Only

Default value: NULL


The "cnc" property

  "cnc"                      GdaConnection         : Read / Write / Construct Only


The "cnc-string" property

  "cnc-string"               gchararray            : Write / Construct Only

Default value: NULL


The "schema" property

  "schema"                   gchararray            : Write / Construct Only

Default value: NULL

Signal Details

The "meta-changed" signal

void                user_function                      (GdaMetaStore *gdametastore,
                                                        gpointer      arg1,
                                                        gpointer      user_data)         : Run First

gdametastore : the object which received the signal.
arg1 :
user_data : user data set when the signal handler was connected.

The "meta-reset" signal

void                user_function                      (GdaMetaStore *gdametastore,
                                                        gpointer      user_data)         : Run First

gdametastore : the object which received the signal.
user_data : user data set when the signal handler was connected.

The "suggest-update" signal

gpointer            user_function                      (GdaMetaStore *store,
                                                        gpointer      suggest,
                                                        gpointer      user_data)      : Run Last

This signal is emitted when the contents of a table should be updated (data updated or inserted; deleting data is done automatically).

store : the GdaMetaStore instance that emitted the signal
suggest : the suggested update, as a GdaMetaContext structure
user_data : user data set when the signal handler was connected.
Returns : a new GError error structure if there was an error when processing the signal, or NULL if signal propagation should continue