GdaMetaStruct

GdaMetaStruct — In memory representation of some database objects

Synopsis

                    GdaMetaStruct;
enum                GdaMetaStructFeature;
enum                GdaMetaStructError;
enum                GdaMetaDbObjectType;
                    GdaMetaDbObject;
#define             GDA_META_DB_OBJECT                  (x)
#define             GDA_META_TABLE                      (dbobj)
#define             GDA_META_VIEW                       (dbobj)
                    GdaMetaTable;
                    GdaMetaView;
                    GdaMetaTableColumn;
#define             GDA_META_TABLE_COLUMN               (x)
const GValue*       gda_meta_table_column_get_attribute (GdaMetaTableColumn *tcol,
                                                         const gchar *att_name);
void                gda_meta_table_column_set_attribute (GdaMetaTableColumn *tcol,
                                                         const gchar *att_name,
                                                         const GValue *value);
void                gda_meta_table_column_foreach_attribute
                                                        (GdaMetaTableColumn *tcol,
                                                         GdaAttributesManagerFunc func,
                                                         gpointer data);
                    GdaMetaTableForeignKey;
#define             GDA_META_TABLE_FOREIGN_KEY          (x)
#define             GDA_META_STRUCT_ERROR
GdaMetaStruct*      gda_meta_struct_new                 (GdaMetaStore *store,
                                                         GdaMetaStructFeature features);
GdaMetaDbObject*    gda_meta_struct_complement          (GdaMetaStruct *mstruct,
                                                         GdaMetaDbObjectType type,
                                                         const GValue *catalog,
                                                         const GValue *schema,
                                                         const GValue *name,
                                                         GError **error);
gboolean            gda_meta_struct_complement_schema   (GdaMetaStruct *mstruct,
                                                         const GValue *catalog,
                                                         const GValue *schema,
                                                         GError **error);
gboolean            gda_meta_struct_complement_default  (GdaMetaStruct *mstruct,
                                                         GError **error);
gboolean            gda_meta_struct_complement_depend   (GdaMetaStruct *mstruct,
                                                         GdaMetaDbObject *dbo,
                                                         GError **error);
enum                GdaMetaSortType;
gboolean            gda_meta_struct_sort_db_objects     (GdaMetaStruct *mstruct,
                                                         GdaMetaSortType sort_type,
                                                         GError **error);
GSList*             gda_meta_struct_get_all_db_objects  (GdaMetaStruct *mstruct);
GdaMetaDbObject*    gda_meta_struct_get_db_object       (GdaMetaStruct *mstruct,
                                                         const GValue *catalog,
                                                         const GValue *schema,
                                                         const GValue *name);
GdaMetaTableColumn* gda_meta_struct_get_table_column    (GdaMetaStruct *mstruct,
                                                         GdaMetaTable *table,
                                                         const GValue *col_name);
enum                GdaMetaGraphInfo;
gchar*              gda_meta_struct_dump_as_graph       (GdaMetaStruct *mstruct,
                                                         GdaMetaGraphInfo info,
                                                         GError **error);

Object Hierarchy

  GObject
   +----GdaMetaStruct

Properties

  "features"                 guint                 : Read / Write / Construct Only
  "meta-store"               GdaMetaStore*         : Read / Write / Construct Only

Description

The GdaMetaStruct object reads data from a GdaMetaStore object and creates an easy to use in memory representation for some database objects. For example one can easily analyse the columns of a table (or its foreign keys) using a GdaMetaStruct.

When created, the new GdaMetaStruct object is empty (it does not have any information about any database object). Information about database objects is computed upon request using the gda_meta_struct_complement() method. Information about individual database objects is represented by GdaMetaDbObject structures, which can be obtained using gda_meta_struct_get_db_object() or gda_meta_struct_get_all_db_objects().

Note that the GdaMetaDbObject structures may change or may be removed or replaced by others, so it not advised to keep pointers to these structures: pointers to these structures should be considered valid as long as gda_meta_struct_complement() and other similar functions have not been called.

In the following code sample, one prints the columns names and types of a table:

GdaMetaStruct *mstruct;
GdaMetaDbObject *dbo;
GValue *catalog, *schema, *name;

/* Define name (and optionnally catalog and schema) */
[...]

mstruct = gda_meta_struct_new ();
gda_meta_struct_complement (mstruct, store, GDA_META_DB_TABLE, catalog, schema, name, NULL);
dbo = gda_meta_struct_get_db_object (mstruct, catalog, schema, name);
if (!dbo)
        g_print ("Table not found\n");
else {
        GSList *list;
        for (list = GDA_META_TABLE (dbo)->columns; list; list = list->next) {
                GdaMetaTableColumn *tcol = GDA_META_TABLE_COLUMN (list->data);
                g_print ("COLUMN: %s (%s)\n", tcol->column_name, tcol->column_type);
        }
}
gda_meta_struct_free (mstruct);
  

If now the database object type is not known, one can use the following code:

GdaMetaStruct *mstruct;
GdaMetaDbObject *dbo;
GValue *catalog, *schema, *name;

/* Define name (and optionnally catalog and schema) */
[...]

mstruct = gda_meta_struct_new ();
gda_meta_struct_complement (mstruct, store, GDA_META_DB_UNKNOWN, catalog, schema, name, NULL);
dbo = gda_meta_struct_get_db_object (mstruct, catalog, schema, name);
if (!dbo)
        g_print ("Object not found\n");
else {
        if ((dbo->obj_type == GDA_META_DB_TABLE) || (dbo->obj_type == GDA_META_DB_VIEW)) {
                if (dbo->obj_type == GDA_META_DB_TABLE)
                        g_print ("Is a table\n");
                else if (dbo->obj_type == GDA_META_DB_VIEW) {
                        g_print ("Is a view, definition is:\n");
                        g_print ("%s\n", GDA_META_VIEW (dbo)->view_def);
                }

                GSList *list;
                for (list = GDA_META_TABLE (dbo)->columns; list; list = list->next) {
                        GdaMetaTableColumn *tcol = GDA_META_TABLE_COLUMN (list->data);
                        g_print ("COLUMN: %s (%s)\n", tcol->column_name, tcol->column_type);
                }
        }
        else 
                g_print ("Not a table or a view\n");
}
gda_meta_struct_free (mstruct);
  

Details

GdaMetaStruct

typedef struct _GdaMetaStruct GdaMetaStruct;


enum GdaMetaStructFeature

typedef enum {
	GDA_META_STRUCT_FEATURE_NONE              = 0,
	GDA_META_STRUCT_FEATURE_FOREIGN_KEYS      = 1 << 0,
	GDA_META_STRUCT_FEATURE_VIEW_DEPENDENCIES = 1 << 1,

	GDA_META_STRUCT_FEATURE_ALL               = GDA_META_STRUCT_FEATURE_FOREIGN_KEYS |
	                                            GDA_META_STRUCT_FEATURE_VIEW_DEPENDENCIES
} GdaMetaStructFeature;


enum GdaMetaStructError

typedef enum {
	GDA_META_STRUCT_UNKNOWN_OBJECT_ERROR,
        GDA_META_STRUCT_DUPLICATE_OBJECT_ERROR,
        GDA_META_STRUCT_INCOHERENCE_ERROR
} GdaMetaStructError;


enum GdaMetaDbObjectType

typedef enum {
	GDA_META_DB_UNKNOWN,
	GDA_META_DB_TABLE,
	GDA_META_DB_VIEW
} GdaMetaDbObjectType;


GdaMetaDbObject

typedef struct {
	union {
		GdaMetaTable    meta_table;
		GdaMetaView     meta_view;
	}                       extra;
	GdaMetaDbObjectType     obj_type;
	gboolean                outdated;
	gchar                  *obj_catalog;
	gchar                  *obj_schema;
	gchar                  *obj_name;
	gchar                  *obj_short_name;
	gchar                  *obj_full_name;
	gchar                  *obj_owner;

	GSList                 *depend_list; /* list of GdaMetaDbObject pointers on which this object depends */
} GdaMetaDbObject;

Struture to hold information about each database object (tables, views, triggers, ...)

Note: obj_catalog, obj_schema, obj_name, obj_short_name and obj_full_name are case sensitive: one must call gda_sql_identifier_needs_quotes() to know if is it is necessary to surround by double quotes before using in an SQL statement


GDA_META_DB_OBJECT()

#define GDA_META_DB_OBJECT(x) ((GdaMetaDbObject*)(x))

x :

GDA_META_TABLE()

#define GDA_META_TABLE(dbobj) (&((dbobj)->extra.meta_table))

dbobj :

GDA_META_VIEW()

#define GDA_META_VIEW(dbobj) (&((dbobj)->extra.meta_view))

dbobj :

GdaMetaTable

typedef struct {
	GSList       *columns; /* list of GdaMetaTableColumn */
	
	/* PK fields index */
	gint         *pk_cols_array;
	gint          pk_cols_nb;

	/* Foreign keys */
	GSList       *reverse_fk_list; /* list of GdaMetaTableForeignKey where @depend_on == this GdaMetaDbObject */
	GSList       *fk_list; /* list of GdaMetaTableForeignKey where @meta_table == this GdaMetaDbObject */
} GdaMetaTable;


GdaMetaView

typedef struct {
	GdaMetaTable  table;
	gchar        *view_def;
	gboolean      is_updatable;
} GdaMetaView;


GdaMetaTableColumn

typedef struct {
	gchar        *column_name;
	gchar        *column_type;
	GType         gtype;
	gboolean      pkey;
	gboolean      nullok;
	gchar        *default_value;
} GdaMetaTableColumn;


GDA_META_TABLE_COLUMN()

#define GDA_META_TABLE_COLUMN(x) ((GdaMetaTableColumn*)(x))

x :

gda_meta_table_column_get_attribute ()

const GValue*       gda_meta_table_column_get_attribute (GdaMetaTableColumn *tcol,
                                                         const gchar *att_name);

Get the value associated to a named attribute.

Attributes can have any name, but Libgda proposes some default names, see this section.

tcol : a GdaMetaTableColumn
att_name :
Returns : a read-only GValue, or NULL if not attribute named attribute has been set for column

gda_meta_table_column_set_attribute ()

void                gda_meta_table_column_set_attribute (GdaMetaTableColumn *tcol,
                                                         const gchar *att_name,
                                                         const GValue *value);

Set the value associated to a named attribute.

Attributes can have any name, but Libgda proposes some default names, see this section. If there is already an attribute named attribute set, then its value is replaced with the new value, except if value is NULL, in which case the attribute is removed.

Warning: sttribute should be a static string (no copy of it is made), so the string should exist as long as the column object exists.

tcol : a GdaMetaTableColumn
att_name :
value : a GValue, or NULL

gda_meta_table_column_foreach_attribute ()

void                gda_meta_table_column_foreach_attribute
                                                        (GdaMetaTableColumn *tcol,
                                                         GdaAttributesManagerFunc func,
                                                         gpointer data);

Calls func for each attribute set to tcol

tcol :
func : a GdaAttributesManagerFunc function
data : user data to be passed as last argument of func each time it is called

GdaMetaTableForeignKey

typedef struct {
	GdaMetaDbObject  *meta_table;
	GdaMetaDbObject  *depend_on;

	gint              cols_nb;	
	gint             *fk_cols_array; /* FK fields index */
	gchar           **fk_names_array; /* FK fields names */
	gint             *ref_pk_cols_array; /* Ref PK fields index */
	gchar           **ref_pk_names_array; /* Ref PK fields names */
} GdaMetaTableForeignKey;


GDA_META_TABLE_FOREIGN_KEY()

#define GDA_META_TABLE_FOREIGN_KEY(x) ((GdaMetaTableForeignKey*)(x))

x :

GDA_META_STRUCT_ERROR

#define GDA_META_STRUCT_ERROR gda_meta_struct_error_quark ()


gda_meta_struct_new ()

GdaMetaStruct*      gda_meta_struct_new                 (GdaMetaStore *store,
                                                         GdaMetaStructFeature features);

Creates a new GdaMetaStruct object. The features specifies the extra features which will also be computed: the more features, the more time it takes to run. Features such as table's columns, each column's attributes, etc are not optional and will always be computed.

store : a GdaMetaStore from which the new GdaMetaStruct object will fetch information
features : the kind of extra information the new GdaMetaStruct object will compute
Returns : the newly created GdaMetaStruct object

gda_meta_struct_complement ()

GdaMetaDbObject*    gda_meta_struct_complement          (GdaMetaStruct *mstruct,
                                                         GdaMetaDbObjectType type,
                                                         const GValue *catalog,
                                                         const GValue *schema,
                                                         const GValue *name,
                                                         GError **error);

Creates a new GdaMetaDbObject structure in mstruct to represent the database object (of type type) which can be uniquely identified as catalog.schema.name.

If catalog is not NULL, then schema should not be NULL.

If catalog is NULL and schema is not NULL, then the database object will be the one which is "visible" by default (that is which can be accessed only by its short name name).

If both catalog and schema are NULL, then the database object will be the one which can be accessed by its schema.name name.

Important note: catalog, schema and name must respect the following convention:

  • be surrounded by double quotes for a case sensitive search

  • otherwise they will be converted to lower case for search

mstruct : a GdaMetaStruct object
type : the type of object to add (which can be GDA_META_DB_UNKNOWN)
catalog : the catalog the object belongs to (as a G_TYPE_STRING GValue), or NULL
schema : the schema the object belongs to (as a G_TYPE_STRING GValue), or NULL
name : the object's name (as a G_TYPE_STRING GValue), not NULL
error : a place to store errors, or NULL
Returns : the GdaMetaDbObject corresponding to the database object if no error occurred, or NULL

gda_meta_struct_complement_schema ()

gboolean            gda_meta_struct_complement_schema   (GdaMetaStruct *mstruct,
                                                         const GValue *catalog,
                                                         const GValue *schema,
                                                         GError **error);

This method is similar to gda_meta_struct_complement() but creates GdaMetaDbObject for all the database object which are in the schema schema (and in the catalog catalog). If catalog is NULL, then any catalog will be used, and if schema is NULL then any schema will be used (if schema is NULL then catalog must also be NULL).

mstruct : a GdaMetaStruct object
catalog : name of a catalog, or NULL
schema : name of a schema, or NULL
error : a place to store errors, or NULL
Returns : TRUE if no error occurred

gda_meta_struct_complement_default ()

gboolean            gda_meta_struct_complement_default  (GdaMetaStruct *mstruct,
                                                         GError **error);

This method is similar to gda_meta_struct_complement() but creates GdaMetaDbObject for all the database object which are useable using only their short name (that is which do not need to be prefixed by the schema in which they are to be used).

mstruct : a GdaMetaStruct object
error : a place to store errors, or NULL
Returns : TRUE if no error occurred

gda_meta_struct_complement_depend ()

gboolean            gda_meta_struct_complement_depend   (GdaMetaStruct *mstruct,
                                                         GdaMetaDbObject *dbo,
                                                         GError **error);

This method is similar to gda_meta_struct_complement() but creates GdaMetaDbObject for all the dependencies of dbo.

mstruct : a GdaMetaStruct object
dbo : a GdaMetaDbObject part of mstruct
error : a place to store errors, or NULL
Returns : TRUE if no error occurred

enum GdaMetaSortType

typedef enum {
	GDA_META_SORT_ALHAPETICAL,
	GDA_META_SORT_DEPENDENCIES
} GdaMetaSortType;

GDA_META_SORT_ALHAPETICAL sort by alphabetical order on the schema name and on the object name
GDA_META_SORT_DEPENDENCIES sort such as that for any given GdaMetaDbObject in the list, all its dependencies are _before_ it in the list

gda_meta_struct_sort_db_objects ()

gboolean            gda_meta_struct_sort_db_objects     (GdaMetaStruct *mstruct,
                                                         GdaMetaSortType sort_type,
                                                         GError **error);

Reorders the list of database objects within mstruct in a way specified by sort_type.

mstruct : a GdaMetaStruct object
sort_type : the kind of sorting requested
error : a place to store errors, or NULL
Returns : TRUE if no error occurred

gda_meta_struct_get_all_db_objects ()

GSList*             gda_meta_struct_get_all_db_objects  (GdaMetaStruct *mstruct);

Get a list of all the GdaMetaDbObject structures representing database objects in mstruct. Note that no GdaMetaDbObject structure must not be modified.

mstruct : a GdaMetaStruct object
Returns : a new GSList list of pointers which must be destroyed after usage using g_slist_free().

gda_meta_struct_get_db_object ()

GdaMetaDbObject*    gda_meta_struct_get_db_object       (GdaMetaStruct *mstruct,
                                                         const GValue *catalog,
                                                         const GValue *schema,
                                                         const GValue *name);

Tries to locate the GdaMetaDbObject structure representing the database object named after catalog, schema and name.

If one or both of catalog and schema are NULL, and more than one database object matches the name, then the return value is also NULL.

mstruct : a GdaMetaStruct object
catalog : the catalog the object belongs to (as a G_TYPE_STRING GValue), or NULL
schema : the schema the object belongs to (as a G_TYPE_STRING GValue), or NULL
name : the object's name (as a G_TYPE_STRING GValue), not NULL
Returns : the GdaMetaDbObject or NULL if not found

gda_meta_struct_get_table_column ()

GdaMetaTableColumn* gda_meta_struct_get_table_column    (GdaMetaStruct *mstruct,
                                                         GdaMetaTable *table,
                                                         const GValue *col_name);

Tries to find the GdaMetaTableColumn representing the column named col_name in table.

mstruct : a GdaMetaStruct object
table : the GdaMetaTable structure to find the column for
col_name : the name of the column to find (as a G_TYPE_STRING GValue)
Returns : the GdaMetaTableColumn or NULL if not found

enum GdaMetaGraphInfo

typedef enum {
	GDA_META_GRAPH_COLUMNS = 1 << 0
} GdaMetaGraphInfo;


gda_meta_struct_dump_as_graph ()

gchar*              gda_meta_struct_dump_as_graph       (GdaMetaStruct *mstruct,
                                                         GdaMetaGraphInfo info,
                                                         GError **error);

Creates a new graph (in the GraphViz syntax) representation of mstruct.

mstruct : a GdaMetaStruct object
info : informs what kind of information to show in the resulting graph
error : a place to store errors, or NULL
Returns : a new string, or NULL if an error occurred.

Property Details

The "features" property

  "features"                 guint                 : Read / Write / Construct Only

Allowed values: <= G_MAXINT

Default value: 3


The "meta-store" property

  "meta-store"               GdaMetaStore*         : Read / Write / Construct Only

GdaMetaStore object to fetch information from.