1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Data handling: GNOME Data Access 5 manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="GNOME Data Access 5 manual">
<link rel="up" href="part_libgda_api.html" title="Part II. API reference">
<link rel="prev" href="GdaLdapConnection.html" title="GdaLdapConnection">
<link rel="next" href="libgda-5.0-Gda-Value.html" title="A single Value">
<meta name="generator" content="GTK-Doc V1.32 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="part_libgda_api.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="GdaLdapConnection.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="libgda-5.0-Gda-Value.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="data_models"></a>Data handling</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt>
<span class="refentrytitle"><a href="libgda-5.0-Gda-Value.html">A single Value</a></span><span class="refpurpose"> — Assorted functions for dealing with <span class="type">GValue</span> values</span>
</dt>
<dt><span class="sect1"><a href="data_models.html#data-validation">Custom data validation</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="data_models.html#data-validation-GdaHolder">GdaHolder controls</a></span></dt>
<dt><span class="sect2"><a href="data_models.html#data-validation-GdaSet">GdaSet controls</a></span></dt>
<dt><span class="sect2"><a href="data_models.html#data-validation-GdaDataProxy">GdaDataProxy controls</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="data-select.html">Advanced GdaDataSelect usage</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="data-select.html#data-select-rerun">Automatic re-run of the SELECT statement</a></span></dt>
<dt><span class="sect2"><a href="data-select.html#data-select-empty-rs">Invalid parameters</a></span></dt>
</dl></dd>
<dt>
<span class="refentrytitle"><a href="GdaBlobOp.html">Blobs</a></span><span class="refpurpose"> — Binary data and BLOBs handling</span>
</dt>
<dt>
<span class="refentrytitle"><a href="GdaDataModel.html">GdaDataModel</a></span><span class="refpurpose"> — Data model interface</span>
</dt>
<dt>
<span class="refentrytitle"><a href="GdaDataSelect.html">GdaDataSelect</a></span><span class="refpurpose"> — Base class for data models returned by the execution of a SELECT statement</span>
</dt>
<dt>
<span class="refentrytitle"><a href="GdaColumn.html">GdaDataModel columns</a></span><span class="refpurpose"> — Management of <span class="type">GdaDataModel</span> column attributes</span>
</dt>
<dt>
<span class="refentrytitle"><a href="GdaDataModelIter.html">GdaDataModelIter</a></span><span class="refpurpose"> — Data model iterator</span>
</dt>
<dt>
<span class="refentrytitle"><a href="GdaDataModelImport.html">GdaDataModelImport</a></span><span class="refpurpose"> — Importing data from a string or a file</span>
</dt>
<dt>
<span class="refentrytitle"><a href="libgda-5.0-GdaDataPivot.html">GdaDataPivot</a></span><span class="refpurpose"> — A data model for data summarisation</span>
</dt>
<dt>
<span class="refentrytitle"><a href="GdaDataAccessWrapper.html">GdaDataAccessWrapper</a></span><span class="refpurpose"> — Offers a random access on top of a cursor-only access data model</span>
</dt>
<dt>
<span class="refentrytitle"><a href="GdaDataModelArray.html">GdaDataModelArray</a></span><span class="refpurpose"> — An implementation of <span class="type">GdaDataModel</span> based on a <span class="type">GArray</span></span>
</dt>
<dt>
<span class="refentrytitle"><a href="GdaRow.html">GdaRow</a></span><span class="refpurpose"> — Individual row of a <span class="type">GdaDataModelArray</span> object</span>
</dt>
<dt>
<span class="refentrytitle"><a href="GdaDataModelLdap.html">GdaDataModelLdap</a></span><span class="refpurpose"> — GdaDataModel to extract LDAP information</span>
</dt>
<dt>
<span class="refentrytitle"><a href="libgda-5.0-GdaDataModelBdb.html">GdaDataModelBdb</a></span><span class="refpurpose"> — GdaDataModel to access Berkeley DB database contents</span>
</dt>
<dt>
<span class="refentrytitle"><a href="GdaDataModelDir.html">GdaDataModelDir</a></span><span class="refpurpose"> — GdaDataModel to list files in filesystem</span>
</dt>
<dt>
<span class="refentrytitle"><a href="GdaDataProxy.html">GdaDataProxy</a></span><span class="refpurpose"> — Proxy to hold modifications for any <span class="type">GdaDataModel</span>, providing the <span class="type">GdaDataModel</span> interface itself</span>
</dt>
<dt>
<span class="refentrytitle"><a href="libgda-5.0-GdaDataComparator.html">GdaDataComparator</a></span><span class="refpurpose"> — Simple data model's contents comparison</span>
</dt>
<dt><span class="sect1"><a href="gda-data-model-writing.html">Implementing your own data model</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="gda-data-model-writing.html#gda-data-model-writing-virtual-methods">Virtual methods</a></span></dt>
<dt><span class="sect2"><a href="gda-data-model-writing.html#gda-data-model-writing-signalling">Signalling changes</a></span></dt>
</dl></dd>
</dl></div>
<p>
<span class="application">Libgda</span> being a data oriented library, data handling is a central point of the library:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>individual values are encapsulated within a <a href="/usr/share/gtk-doc/html/gobject/gobject-Generic-values.html#GValue-struct">GValue</a>
container (from GLIB)</p></li>
<li class="listitem">
<p>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
<a class="link" href="GdaHolder.html" title="GdaHolder">GdaHolder</a> container object.</p>
<p>
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 <a class="link" href="GdaDataModel.html" title="GdaDataModel">GdaDataModel</a>.
</p>
</li>
<li class="listitem">
<p>lists of value holders which are encapsulated within a
<a class="link" href="GdaSet.html" title="GdaSet">GdaSet</a> container object.</p>
<p>
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).
</p>
</li>
<li class="listitem">
<p>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.
<span class="application">Libgda</span> uses the <a class="link" href="GdaDataModel.html" title="GdaDataModel">GdaDataModel</a>
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).</p>
<p>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.</p>
</li>
<li class="listitem"><p>The <a class="link" href="GdaDataModelIter.html" title="GdaDataModelIter">GdaDataModelIter</a> object is used to
iterate through the rows of a <a class="link" href="GdaDataModel.html" title="GdaDataModel">GdaDataModel</a>.</p></li>
</ul></div>
<p>
</p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="data-validation"></a>Custom data validation</h2></div></div></div>
<p>
<span class="application">Libgda</span> 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.
</p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="data-validation-GdaHolder"></a>GdaHolder controls</h3></div></div></div>
<p>
The <a class="link" href="GdaHolder.html" title="GdaHolder">GdaHolder</a> object holds a single value
(as a <a href="/usr/share/gtk-doc/html/gobject/gobject-Generic-values.html#GValue-struct">GValue</a>). When that value is to be modified, using for example
<a class="link" href="GdaHolder.html#gda-holder-set-value" title="gda_holder_set_value ()">gda_holder_set_value()</a>,
then the proposed new value's validation process is executed:
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem"><p>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</p></li>
<li class="listitem"><p>the <a class="link" href="GdaHolder.html#GdaHolder-validate-change" title="The “validate-change” signal">"validate-change"</a> signal is
emitted. If any handler for this signal returns a pointer to a filled <a href="/usr/share/gtk-doc/html/glib/glib-Error-Reporting.html#GError">GError</a>
structure, then the signal's propagation is stopped and the value change will be rejected.</p></li>
</ol></div>
<p>
</p>
<p>
An example illustrating how to use the <a class="link" href="GdaHolder.html#GdaHolder-validate-change" title="The “validate-change” signal">"validate-change"</a> signal
is:
</p>
<pre class="programlisting">
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);
[...]
}
}
</pre>
<p>
</p>
<p>
</p>
<div class="mediaobject"><img src="data_validation_holder.png" width="354" alt="GdaHolder's value change control"></div>
<p>
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="data-validation-GdaSet"></a>GdaSet controls</h3></div></div></div>
<p>
The <a class="link" href="GdaSet.html" title="GdaSet">GdaSet</a> object is an ordered list (or vector) of values,
each represented by a <a class="link" href="GdaHolder.html" title="GdaHolder">GdaHolder</a> object. One can place controls
at two key events:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>
When any value of a <a class="link" href="GdaHolder.html" title="GdaHolder">GdaHolder</a> changes, where
the <a class="link" href="GdaSet.html#GdaSet-validate-holder-change" title="The “validate-holder-change” signal">"validate-holder-change"</a> signal is
emitted. If any handler for this signal returns a pointer to a filled <a href="/usr/share/gtk-doc/html/glib/glib-Error-Reporting.html#GError">GError</a>
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.
</p></li>
<li class="listitem"><p>
When the <a class="link" href="GdaSet.html#gda-set-is-valid" title="gda_set_is_valid ()">gda_set_is_valid()</a> method is called,
the <a class="link" href="GdaSet.html#GdaSet-validate-set" title="The “validate-set” signal">"validate-set"</a> signal is
emitted. If any handler for this signal returns a pointer to a filled <a href="/usr/share/gtk-doc/html/glib/glib-Error-Reporting.html#GError">GError</a>
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).
</p></li>
</ul></div>
<p>
</p>
<p>
</p>
<div class="mediaobject"><img src="data_validation_set.png" width="638" alt="GdaSet's changes controls"></div>
<p>
</p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="data-validation-GdaDataProxy"></a>GdaDataProxy controls</h3></div></div></div>
<p>
The <a class="link" href="GdaDataProxy.html" title="GdaDataProxy">GdaDataProxy</a> 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 <a class="link" href="GdaDataProxy.html" title="GdaDataProxy">GdaDataProxy</a> data model emits
the <a class="link" href="GdaDataProxy.html#GdaDataProxy-validate-row-changes" title="The “validate-row-changes” signal">"validate-row-changes"</a> signal, and
if handler for this signal returns a pointer to a filled <a href="/usr/share/gtk-doc/html/glib/glib-Error-Reporting.html#GError">GError</a>
structure, then the signal's propagation is stopped and the row's modifications are not applied.
</p>
<p>
</p>
<div class="mediaobject"><img src="data_validation_proxy.png" width="354" alt="GdaDataProxy's changes controls"></div>
<p>
</p>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.32</div>
</body>
</html>
|
