|
|
|
|
Libgda being a data oriented library, data handling is a central point of the library:
individual values are encapsulated within a GValue container (from GLIB)
value holders which are each a specification for a value: a type, a name, a description, a default value, etc. Value holders are encapsulated within a GdaHolder container object.
Note that it is possible to set a hint to make a value holder have its value constrained by the values contained in a column of a GdaDataModel.
lists of value holders which are encapsulated within a GdaSet container object.
The GdaSet object also makes some computations to group value holders which are constrained by values in the same GdaDataModel (it makes it easy to use value holders which are not really independent).
arrays of values organized in rows and columns. All the data in the same column have the same type, and all the data in each row have the same semantic meaning. Libgda uses the GdaDataModel objects to actually hold the data (note that this is actually an interface which has several implementations depending on the real data organization in the data model).
Note that depending on the real implementation, access to the data can be random or done using an iterator, and that the data model can be read-only or modifiable.
The GdaDataModelIter object is used to iterate through the rows of a GdaDataModel.
Libgda allows the programmer to specify some rules of his own to control data changes (for example business rules). This section details the various control points, how to implement them, and how or when they are invoked.
The GdaHolder object holds a single value (as a GValue). When that value is to be modified, using for example gda_holder_set_value(), then the proposed new value's validation process is executed:
it is determined if the proposed new value is of the correct type and if it respects the holder's policy (for example a NULL value won't be accepted if the holder can't be NULL). If the proposed value does not respect the policy, then the value change will be rejected
the "validate-change" signal is emitted. If any handler for this signal returns a pointer to a filled GError structure, then the signal's propagation is stopped and the value change will be rejected.
An example illustrating how to use the "validate-change" signal is:
static GError *
my_validate_change_cb (GdaHolder *h, const GValue *value, gpointer data)
{
GError *error = NULL;
/* for example check that value is inferior to 5 and not NULL */
if (gda_value_is_null (value))
g_set_error (&error, YOUR_DOMAIN, YOUR_CODE, "NULL values are not allowed!");
else if (g_value_get_int (value) >= 5)
g_set_error (&error, YOUR_DOMAIN, YOUR_CODE, "Value sould be inferior to 5");
return error;
}
{
GdaHolder *holder;
GError *error = NULL;
[...]
g_signal_connect (G_OBJECT (holder), "validate-change",
G_CALLBACK (my_validate_change_cb), NULL);
if (! gda_holder_set_value (holder, value, &error)) {
g_print ("Error: %s\n", error->message);
g_error_free (error);
[...]
}
}
The GdaSet object is an ordered list (or vector) of values, each represented by a GdaHolder object. One can place controls at two key events:
When any value of a GdaHolder changes, where the "validate-holder-change" signal is emitted. If any handler for this signal returns a pointer to a filled GError structure, then the signal's propagation is stopped and the value change will be rejected. This key event allows one to control each holder's value change as they occur.
When the gda_set_is_valid() method is called, the "validate-set" signal is emitted. If any handler for this signal returns a pointer to a filled GError structure, then the signal's propagation is stopped and the calling method will return the generated error. This key event allows one to control the validity of a set of values altogether (for example before writing to a table).
The GdaDataProxy data model allows one to store temporary modifications to a data model, and then apply (write to the proxied data model) those modifications row by row. Before applying any row modification, the GdaDataProxy data model emits the "validate-row-changes" signal, and if handler for this signal returns a pointer to a filled GError structure, then the signal's propagation is stopped and the row's modifications are not applied.
