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);
gchar *             gda_meta_store_sql_identifier_quote (const gchar *id,
                                                         GdaConnection *cnc);
GdaDataModel *      gda_meta_store_extract              (GdaMetaStore *store,
                                                         const gchar *select_sql,
                                                         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"                  gchar*                : Write / Construct Only
  "cnc"                      GdaConnection*        : Read / Write / Construct Only
  "cnc-string"               gchar*                : Write / Construct Only
  "schema"                   gchar*                : 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 (see the database schema section for a detailed description). 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.

The GdaMetaStore object is thread safe.

Details

GdaMetaStore

typedef struct _GdaMetaStore GdaMetaStore;


enum GdaMetaStoreError

typedef enum {
	GDA_META_STORE_INCORRECT_SCHEMA_ERROR,
	GDA_META_STORE_UNSUPPORTED_PROVIDER_ERROR,
	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;

The GdaMetaContext represents a meta data modification context: the how when used with gda_meta_store_modify_with_context(), and the what when used with gda_connection_update_meta_store().

gchar *table_name;

the name of the table in the GdaMetaStore's internal database

gint size;

the size of the column_names and column_values arrays

gchar **column_names;

an array of column names (columns of the table_name table)

GValue **column_values;

an array of values, one for each column named in column_names

gda_meta_store_new ()

GdaMetaStore *      gda_meta_store_new                  (const gchar *cnc_string);

Create a new GdaMetaStore object.

cnc_string :

a connection string, or NULL for an in-memory internal database

Returns :

the newly created object, or NULL if an error occurred. [transfer full]

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. [transfer full]

gda_meta_store_get_version ()

gint                gda_meta_store_get_version          (GdaMetaStore *store);

Get store's internal schema's version

store :

a GdaMetaStore object

Returns :

the version (incremented each time the schema changes, backward compatible)

gda_meta_store_sql_identifier_quote ()

gchar *             gda_meta_store_sql_identifier_quote (const gchar *id,
                                                         GdaConnection *cnc);

Use this method to get a correctly quoted (if necessary) SQL identifier which can be used to retrieve or filter information in a GdaMetaStore which stores meta data about cnc.

The returned SQL identifier can be used in conjunction with gda_connection_update_meta_store(), gda_connection_get_meta_store_data(), gda_connection_get_meta_store_data_v() and gda_meta_store_extract().

id :

an SQL identifier

cnc :

a GdaConnection

Returns :

a new string, to free with g_free() once not needed anymore. [transfer full]

Since 4.0.3


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. If the select_sql filter involves SQL identifiers (such as table or column names), then the values should have been adapted using gda_meta_store_sql_identifier_quote().

For more information about SQL identifiers are represented in store, see the meta data section about SQL identifiers.

store :

a GdaMetaStore object

select_sql :

a SELECT statement

error :

a place to store errors, or NULL. [allow-none]

... :

a list of (variable name (gchar *), GValue *value) terminated with NULL, representing values for all the variables mentioned in select_sql. If there is no variable then this part can be omitted.

Returns :

a new GdaDataModel, or NULL if an error occurred. [transfer full]

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 internal database structure.

store :

a GdaMetaStore object

error :

a place to store errors, or NULL. [allow-none]

Returns :

a new GdaMetaStruct object, or NULL if an error occurred. [transfer full]

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 internal 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 for 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. [out]

error :

a place to store errors, or NULL. [allow-none]

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. [allow-none]

error :

a place to store errors, or NULL. [allow-none]

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

The xml_description defines the table of view's definition, for example:

<table name="mytable">
    <column name="id" pkey="TRUE"/>
    <column name="value"/>
</table>

The partial DTD for this XML description of the object to add is the following (the top node must be a <table> or a <view>):

<!ELEMENT table (column*,check*,fkey*,unique*)>
<!ATTLIST table
          name NMTOKEN #REQUIRED>

<!ELEMENT column EMPTY>
<!ATTLIST column
          name NMTOKEN #REQUIRED
          type CDATA #IMPLIED
          pkey (TRUE|FALSE) #IMPLIED
          autoinc (TRUE|FALSE) #IMPLIED
          nullok (TRUE|FALSE) #IMPLIED>

<!ELEMENT check (#PCDATA)>

<!ELEMENT fkey (part+)>
<!ATTLIST fkey
          ref_table NMTOKEN #REQUIRED>

<!ELEMENT part EMPTY>
<!ATTLIST part
          column NMTOKEN #IMPLIED
          ref_column NMTOKEN #IMPLIED>

<!ELEMENT unique (column*)>

<!ELEMENT view (definition)>
<!ATTLIST view
          name NMTOKEN #REQUIRED
          descr CDATA #IMPLIED>

<!ELEMENT definition (#PCDATA)>

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. [allow-none]

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. The returned object is not owned by the caller (if you need to keep it, then use g_object_ref()). Do not close the connection.

store :

a GdaMetaStore object

Returns :

a GdaConnection, or NULL. [transfer none]

Property Details

The "catalog" property

  "catalog"                  gchar*                : Write / Construct Only

Catalog in which the database objects will be created.

Default value: NULL


The "cnc" property

  "cnc"                      GdaConnection*        : Read / Write / Construct Only

Connection object internally used.


The "cnc-string" property

  "cnc-string"               gchar*                : Write / Construct Only

Connection string for the internal connection to use.

Default value: NULL


The "schema" property

  "schema"                   gchar*                : Write / Construct Only

Schema in which the database objects will be created.

Default value: NULL

Signal Details

The "meta-changed" signal

void                user_function                      (GdaMetaStore *store,
                                                        GdaSList     *changes,
                                                        gpointer      user_data)      : Run First

This signal is emitted when the store's contents have changed (the changes are in the changes list)

store :

the GdaMetaStore instance that emitted the signal

changes :

a list of changes made, as a GSList of pointers to GdaMetaStoreChange (which must not be modified)

user_data :

user data set when the signal handler was connected.

The "meta-reset" signal

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

This signal is emitted when the store's contents have been reset completely and when no detailed changes are available

store :

the GdaMetaStore instance that emitted the signal

user_data :

user data set when the signal handler was connected.

The "suggest-update" signal

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

This signal is emitted when the contents of a table should be updated (data to update or insert only; deleting data is done automatically). This signal is used for internal purposes by the GdaConnection object.

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