Gnome::Gda::MetaStore Class Reference

Dictionary object. More...

Inheritance diagram for Gnome::Gda::MetaStore:
[legend]
Collaboration diagram for Gnome::Gda::MetaStore:
[legend]

## Public Member Functions

| MetaStore (MetaStore&& src) noexcept
MetaStore& | operator= (MetaStore&& src) noexcept
virtual | ~MetaStore () noexcept
GdaMetaStore* | gobj ()
| Provides access to the underlying C GObject. More...
const GdaMetaStore* | gobj () const
| Provides access to the underlying C GObject. More...
GdaMetaStore* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
int | get_version () const
| Get store's internal schema's version. More...
Glib::RefPtr< DataModel > | extract (const Glib::ustring& sql)
| Extracts some data stored in store using a custom SELECT query. More...
bool | modify (const Glib::ustring& sql, const Glib::RefPtr< DataModel >& data_model, const Glib::ustring& condition)
| Propagates an update to store, the update's contents is represented by new_data, this function is primarily reserved to database providers. More...
bool | modify_with_context (MetaContext* context, const Glib::RefPtr< DataModel >& new_data)
| Propagates an update to store, the update's contents is represented by new_data, this function is primarily reserved to database providers. More...
Glib::RefPtr< DataModel > | create_modify_data_model (const Glib::ustring& table_name)
| Creates a new Gda::DataModelArray data model which can be used, after being correctly filled, with the gda_meta_store_modify*() methods. More...
void | set_identifiers_style (SqlIdentifierStyle style)
| Specifies how store must handle SQL identifiers it has to store. More...
Glib::RefPtr< MetaStruct > | schema_get_structure ()
| Creates a new Gda::MetaStruct object representing store's internal database structure. More...
std::vector< Glib::ustring > | schema_get_all_tables ()
| Get an ordered list of the tables store knows about. More...
std::vector< Glib::ustring > | schema_get_depend_tables (const Glib::ustring& table_name)
| Get an ordered list of the tables store knows about on which the table_name table depends (recursively). More...
bool | get_attribute_value (const Glib::ustring& att_name, Glib::ustring& att_value)
| The Gda::MetaStore object maintains a list of (name,value) attributes (attributes names starting with a '_' character are for internal use only and cannot be altered). More...
bool | set_attribute_value (const Glib::ustring& att_name, const Glib::ustring& att_value)
| Set the value of the attribute named att_name to att_value; see get_attribute_value() for more information. More...
bool | schema_add_custom_object (const Glib::ustring& xml_description)
| The internal database used by store can be 'augmented' with some user-defined database objects (such as tables or views). More...
bool | schema_remove_custom_object (const Glib::ustring& obj_name)
| Removes the custom database object named obj_name. More...
Glib::RefPtr< Connection > | get_internal_connection ()
| Get a pointer to the Gda::Connection object internally used by store to store its contents. More...
Glib::RefPtr< const Connection > | get_internal_connection () const
| Get a pointer to the Gda::Connection object internally used by store to store its contents. More...
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Connection > > | property_cnc () const
| Connection object internally used. More...
Glib::SignalProxy0< void > | signal_meta_reset ()
Public Member Functions inherited from Glib::Object
| Object (const Object &)=delete
Object & | operator= (const Object &)=delete
| Object (Object &&src) noexcept
Object & | operator= (Object &&src) noexcept
void * | get_data (const QueryQuark &key)
void | set_data (const Quark &key, void *data)
void | set_data (const Quark &key, void *data, DestroyNotify notify)
void | remove_data (const QueryQuark &quark)
void * | steal_data (const QueryQuark &quark)
Glib::RefPtr< Glib::Object > | wrap (GObject *object, bool take_copy=false)
Public Member Functions inherited from Glib::ObjectBase
| ObjectBase (const ObjectBase &)=delete
ObjectBase & | operator= (const ObjectBase &)=delete
void | set_property_value (const Glib::ustring &property_name, const Glib::ValueBase &value)
void | get_property_value (const Glib::ustring &property_name, Glib::ValueBase &value) const
void | set_property (const Glib::ustring &property_name, const PropertyType &value)
void | get_property (const Glib::ustring &property_name, PropertyType &value) const
void | connect_property_changed (const Glib::ustring &property_name, const sigc::slot< void > &slot)
sigc::connection | connect_property_changed_with_return (const Glib::ustring &property_name, const sigc::slot< void > &slot)
void | freeze_notify ()
void | thaw_notify ()
virtual void | reference () const
virtual void | unreference () const
GObject * | gobj ()
const GObject * | gobj () const
GObject * | gobj_copy () const
Public Member Functions inherited from sigc::trackable
| trackable ()
| trackable (const trackable &src)
| trackable (trackable &&src) noexcept
| ~trackable ()
void | add_destroy_notify_callback (void *data, func_destroy_notify func) const
void | notify_callbacks ()
trackable & | operator= (const trackable &src)
trackable & | operator= (trackable &&src) noexcept
void | remove_destroy_notify_callback (void *data) const

## Static Public Member Functions

static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...
static Glib::RefPtr< MetaStore > | create (const Glib::ustring& cnc_string)

## Protected Member Functions

| MetaStore (const Glib::ustring& cnc_string)
virtual void | on_meta_reset ()
| This is a default handler for the signal signal_meta_reset(). More...
Protected Member Functions inherited from Glib::Object
| Object ()
| Object (const Glib::ConstructParams &construct_params)
| Object (GObject *castitem)
virtual | ~Object () noexcept
Protected Member Functions inherited from Glib::ObjectBase
| ObjectBase ()
| ObjectBase (const char *custom_type_name)
| ObjectBase (const std::type_info &custom_type_info)
| ObjectBase (ObjectBase &&src) noexcept
ObjectBase & | operator= (ObjectBase &&src) noexcept
virtual | ~ObjectBase () noexcept=0
void | initialize (GObject *castitem)
void | initialize_move (GObject *castitem, Glib::ObjectBase *previous_wrapper)

## Related Functions

(Note that these are not member functions.)
Glib::RefPtr< Gnome::Gda::MetaStore > | wrap (GdaMetaStore* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## Additional Inherited Members

Public Types inherited from Glib::Object
typedef void(* | DestroyNotify) (gpointer data)
Public Types inherited from sigc::trackable
typedef internal::func_destroy_notify | func_destroy_notify

## Detailed Description

Dictionary object.

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 detailled 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.

## Constructor & Destructor Documentation

Gnome::Gda::MetaStore::MetaStore | ( | MetaStore&& | src | ) |

noexcept

virtual Gnome::Gda::MetaStore::~MetaStore | ( |  | ) |

virtual noexcept

Gnome::Gda::MetaStore::MetaStore | ( | const Glib::ustring & | cnc_string | ) |

explicit protected

## Member Function Documentation

static Glib::RefPtr<MetaStore> Gnome::Gda::MetaStore::create | ( | const Glib::ustring & | cnc_string | ) |

static

Glib::RefPtr<DataModel> Gnome::Gda::MetaStore::create_modify_data_model | ( | const Glib::ustring & | table_name | ) |

Creates a new Gda::DataModelArray data model which can be used, after being correctly filled, with the gda_meta_store_modify*() methods.

- To be used by provider's implementation

Parameters

  table_name | The name of a table present in store.

Returns
  A new Gda::DataModel.

Glib::RefPtr<DataModel> Gnome::Gda::MetaStore::extract | ( | const Glib::ustring & | sql | ) |

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 sql_identifier_quote().

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

Parameters

  select_sql | A SELECT statement.
  error | A place to store errors, or `0`.
  Varargs | A list of (variable name (gchar *), GValue *value) terminated with `0`, representing values for all the variables mentioned in select_sql. If there is no variable then this part can be omitted.

Returns
  A new Gda::DataModel, or `0` if an error occurred.

bool Gnome::Gda::MetaStore::get_attribute_value | ( | const Glib::ustring & | att_name,
|  | Glib::ustring & | att_value
| ) |  |

The Gda::MetaStore 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 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 `0` and error will contain the GDA_META_STORE_ATTRIBUTE_NOT_FOUND_ERROR error code, and `false` is returned.

Parameters

  att_name | Name of the attribute to get.
  att_value | The place to store the attribute value.

Returns
  `true` if no error occurred.

Glib::RefPtr<Connection> Gnome::Gda::MetaStore::get_internal_connection | ( |  | ) |

Get a pointer to the Gda::Connection 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 Glib::object_ref()). Do not close the connection.

Returns
  A Gda::Connection, or `0`.

Glib::RefPtr<const Connection> Gnome::Gda::MetaStore::get_internal_connection | ( |  | ) | const

Get a pointer to the Gda::Connection 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 Glib::object_ref()). Do not close the connection.

Returns
  A Gda::Connection, or `0`.

static GType Gnome::Gda::MetaStore::get_type | ( |  | ) |

static

Get the GType for this class, for use with the underlying GObject type system.

int Gnome::Gda::MetaStore::get_version | ( |  | ) | const

Get store's internal schema's version.

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

GdaMetaStore* Gnome::Gda::MetaStore::gobj | ( |  | ) |

inline

Provides access to the underlying C GObject.

const GdaMetaStore* Gnome::Gda::MetaStore::gobj | ( |  | ) | const

inline

Provides access to the underlying C GObject.

GdaMetaStore* Gnome::Gda::MetaStore::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

bool Gnome::Gda::MetaStore::modify | ( | const Glib::ustring & | sql,
|  | const Glib::RefPtr< DataModel >& | data_model,
|  | const Glib::ustring & | condition
| ) |  |

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 primary key of the "_tables" table of store, namely "table_catalog", "table_schema" and "table_name".

Parameters

  table_name | The name of the table to modify within store.
  new_data | A Gda::DataModel containing the new data to set in table_name, or `0` (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 `0`.
  error | A place to store errors, or `0`.
  Varargs | A list of (variable name (gchar *), GValue *value) terminated with `0`, representing values for all the variables mentioned in condition.

Returns
  `true` if no error occurred.

bool Gnome::Gda::MetaStore::modify_with_context | ( | MetaContext * | context,
|  | const Glib::RefPtr< DataModel >& | new_data
| ) |  |

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

Parameters

  context | A Gda::MetaContext context describing what to modify in store.
  new_data | A Gda::DataModel containing the new data to set in table_name, or `0` (treated as a data model with no row at all).

Returns
  `true` if no error occurred.

virtual void Gnome::Gda::MetaStore::on_meta_reset | ( |  | ) |

protected virtual

This is a default handler for the signal signal_meta_reset().

MetaStore& Gnome::Gda::MetaStore::operator= | ( | MetaStore&& | src | ) |

noexcept

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Connection> > Gnome::Gda::MetaStore::property_cnc | ( |  | ) | const

Connection object internally used.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

bool Gnome::Gda::MetaStore::schema_add_custom_object | ( | const Glib::ustring & | xml_description | ) |

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: <![CDATA[

<column name="value">

]]>

The partial DTD for this XML description of the object to add is the following (the top node must be a

a <view>): <![CDATA[<!ELEMENT table (column*,check*,fkey*,unique*)> <!ATTLIST table name NMTOKEN R::EQUIRED>

<!ELEMENT column EMPTY> <!ATTLIST column name NMTOKEN R::EQUIRED type CDATA I::MPLIED pkey (`true`|`false`) I::MPLIED autoinc (`true`|`false`) I::MPLIED nullok (`true`|`false`) I::MPLIED>

<!ELEMENT check (P::CDATA)>

<!ELEMENT fkey (part+)> <!ATTLIST fkey ref_table NMTOKEN R::EQUIRED>

<!ELEMENT part EMPTY> <!ATTLIST part column NMTOKEN I::MPLIED ref_column NMTOKEN I::MPLIED>

<!ELEMENT unique (column*)>

<!ELEMENT view (definition)> <!ATTLIST view name NMTOKEN R::EQUIRED descr CDATA I::MPLIED>

<!ELEMENT definition (P::CDATA)>]]>

Parameters

  xml_description | An XML description of the table or view to add to store.

Returns
  `true` if the new object has sucessfully been added.

std::vector<Glib::ustring> Gnome::Gda::MetaStore::schema_get_all_tables | ( |  | ) |

Get an ordered list of the tables store knows about.

The tables are ordered in a way that tables dependencies are respected: if table B has a foreign key on table A, then table A will be listed before table B in the returned list.

Returns
  A new list of tables names (as gchar*), the list must be freed when no longer needed, but the strings present in the list must not be modified.

std::vector<Glib::ustring> Gnome::Gda::MetaStore::schema_get_depend_tables | ( | const Glib::ustring & | table_name | ) |

Get an ordered list of the tables store knows about on which the table_name table depends (recursively).

The tables are ordered in a way that tables dependencies are respected: if table B has a foreign key on table A, then table A will be listed before table B in the returned list.

Parameters

  table_name | The name of the table for which all the dependencies must be listed.

Returns
  A new list of tables names (as gchar*), the list must be freed when no longer needed, but the strings present in the list must not be modified.

Glib::RefPtr<MetaStruct> Gnome::Gda::MetaStore::schema_get_structure | ( |  | ) |

Creates a new Gda::MetaStruct object representing store's internal database structure.

Returns
  A new Gda::MetaStruct object, or `0` if an error occurred.

bool Gnome::Gda::MetaStore::schema_remove_custom_object | ( | const Glib::ustring & | obj_name | ) |

Removes the custom database object named obj_name.

Parameters

  obj_name | Name of the custom object to remove.

Returns
  `true` if the custom object has sucessfully been removed.

bool Gnome::Gda::MetaStore::set_attribute_value | ( | const Glib::ustring & | att_name,
|  | const Glib::ustring & | att_value
| ) |  |

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

Parameters

  att_name | Name of the attribute to set.
  att_value | Value of the attribute to set, or `0` to unset the attribute.

Returns
  `true` if no error occurred.

void Gnome::Gda::MetaStore::set_identifiers_style | ( | SqlIdentifierStyle | style | ) |

Specifies how store must handle SQL identifiers it has to store.

This method is mainly used by database providers.

Since libgdamm 4.2:

Parameters

  style | A style.

Glib::SignalProxy0< void > Gnome::Gda::MetaStore::signal_meta_reset | ( |  | ) |

Slot Prototype:
  `void on_my_meta_reset()`

## Friends And Related Function Documentation

Glib::RefPtr< Gnome::Gda::MetaStore > wrap | ( | GdaMetaStore * | object,
|  | bool | take_copy = `false`
| ) |  |

related

A Glib::wrap() method for this object.

Parameters

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns
  A C++ instance that wraps this C instance.

The documentation for this class was generated from the following file:

- libgdamm/metastore.h