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
|
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"[
<!ENTITY LIBGDA "<application>Libgda</application>">
]>
<chapter id="migration-2" xmlns:xi="http://www.w3.org/2003/XInclude">
<title>Migration from 3.X versions</title>
<sect1><title>Overview</title>
<para>Version 4.0 of &LIBGDA; is a major rework of the library for the following benefits:
<itemizedlist>
<listitem><para>easier to understand and to use API, with less strange path usage (which were inherited
from modifications above modifications where no global coherence was addressed)</para></listitem>
<listitem><para>reduce the size of the library (now 1.3M compared to 1.7M once stripped) and the number of symbols
(845 compared to 1420) and have less complicated and thus more maintainable code (190 files compared to 250).
</para></listitem>
<listitem><para>removal of the GdaClient object from which connections were created: this object did not offer
any significant features and made the API more difficult to use</para></listitem>
<listitem><para>merge the GdaQuery and GdaCommand into only one object to represent statements</para></listitem>
<listitem><para>improve the quantity of information stored in the dictionary and make it easy to include some
application-specific data, while at the same time reduce the memory footprint of the dictionary</para></listitem>
<listitem><para>rework provider's code to make it more common and provide skeletal implementations to make it easy to write
new database providers</para></listitem>
<listitem><para>provide more efficient and complete SQL parsing (don't use Lex/Yacc anymore since there can be
difficult to track problems when several parsers are used at the same time)</para></listitem>
</itemizedlist>
</para>
</sect1>
<sect1><title>New unique parser</title>
<para>Previous &LIBGDA; versions had several builtin parsers relying on Lex/Yacc (or Flex/Bison) to analyze SQL with
the following limitations:
<itemizedlist>
<listitem><para>not all the SELECT, INSERT, DELETE and UPDATE constructions were recognized</para></listitem>
<listitem><para>the parsers were generic and could not be adapted to the different database's SQL dialects</para></listitem>
<listitem><para>there were some difficult to track problems when several parsers are used at the same time</para></listitem>
</itemizedlist>
</para>
<para>All the parsers have been removed in favor of a new parser <link linkend="GdaSqlParser">GdaSqlParser</link> object which
can be generic or specific to a database provider if the provider has specified it.</para>
<para>To create a generic <link linkend="GdaSqlParser">GdaSqlParser</link> object, one can use the
<link linkend="gda-sql-parser-new">gda_sql_parser_new()</link> method, and for a parser adapted to a specific
database's SQL dialect, use the <link linkend="gda-connection-create-parser">gda_connection_create_parser()</link> method.</para>
<para>The new parser uses <ulink url="http://www.hwaci.com/sw/lemon">LEMON</ulink> generated parsers.</para>
</sect1>
<sect1><title>GdaQuery and GdaCommand merge into GdaStatement</title>
<para>Previous &LIBGDA; versions proposed the GdaCommand and GdaQuery objects to execute SQL statements, with different
features (GdaCommand was more generic but did not allow parameters bindings while GdaQuery allowed parameters bindings but
could not execute some kind of problems)
</para>
<para>Both of these objects have been removed and replaced by a new <link linkend="GdaStatement">GdaStatement</link> object
which combines the features of both GdaCommand and GdaQuery. Most of the time <link linkend="GdaStatement">GdaStatement</link>
object are created by <link linkend="GdaSqlParser">GdaSqlParser</link> objects.
See this object's documentation for more information.</para>
</sect1>
<sect1 id="migration-2-dict"><title>Dictionary changes</title>
<para>The GdaDict object has been removed and the <link linkend="GdaMetaStore">GdaMetaStore</link> object introduced to
replace it, but with slightly different features.</para>
<para>The GdaDict object used an XML file to store its data which imposed parsing potentially big XML files and creating its own
internal structures from it (before discarding the XML tree) which was both CPU and memory intensive. Memory was
also wasted as most of the time not all the dictionary would be exploited. The new
<link linkend="GdaMetaStore">GdaMetaStore</link> object relies on a database (an SQLite file by default) to store its data
which solves the problems mentioned above.</para>
<para>It was difficult for applications to add their own data in the dictionary (the API existed but was difficult to understand
and use), this has been solved by allowing applications to create DBMS objects into the
<link linkend="GdaMetaStore">GdaMetaStore</link>'s associated database.</para>
<para>There was a <emphasis>strange</emphasis> relation between a GdaDict object and a
<link linkend="GdaConnection">GdaConnection</link> object as a connection <emphasis>needed to</emphasis> be assigned
to a GdaDict object; this is not the case as now each <link linkend="GdaConnection">GdaConnection</link> object builts
a <link linkend="GdaMetaStore">GdaMetaStore</link> when it needs it (providers implementations may benefit from it) and
the user can provide his own <link linkend="GdaMetaStore">GdaMetaStore</link> object when needed.</para>
</sect1>
<sect1 id="migration-2-exec"><title>Statement execution</title>
<para>
&LIBGDA; still offers several methods to execute a statement, depending on the type of statement to execute
(there is still of course the <link linkend="gda-connection-statement-execute">gda_connection_statement_execute()</link>
method which works for any type of statement), but the methods have been improved:
<itemizedlist>
<listitem><para>For SELECT statements, it is now possible to specify the way the resulting data model will
be accessed (random access or using a cursor) which enables applications to better manage memory
consumption.</para></listitem>
<listitem><para>For INSERT statements, it is possible to obtain a list of all the values inserted in the
table (not only the columns for which a value was specified)</para></listitem>
<listitem><para>The execution of a SELECT statement returns a <link linkend="GdaDataSelect">GdaDataSelect</link>
data model which can (after having provided some information) be modified using the traditional
<link linkend="GdaDataModel">GdaDataModel</link>'s data modification methods (modifications are
translated into INSERT, UPDATE or DELETE statements).</para></listitem>
</itemizedlist>
</para>
</sect1>
<sect1 id="migration-2-report"><title>Reports</title>
<para>
&LIBGDA;'s reports API has not changed, but the syntax of the XML nodes specific to &LIBGDA; (those nodes are
replaced by contents when the report is generated) has changed:
<itemizedlist>
<listitem><para>The parameter name to access a data model's column name by its name
is now <query_name>|@<column_name>
instead of <query_name>/@<column_name></para></listitem>
<listitem><para>The parameter name to access a data model's column name by its index
is now <query_name>|#<column_index>
instead of <query_name>/#<column_index></para></listitem>
<listitem><para>The parameter name to access the total number of rows of a data model is now
<query_name>|?nrows instead of <query_name>/%nrows</para></listitem>
</itemizedlist>
</para>
</sect1>
<sect1><title>Other changes</title>
<sect2><title>Multi threading environment</title>
<para>
Previous versions of &LIBGDA; only supported being used in a single thread at a time; this new version
still keeps this limitation except for objects which implement the <link linkend="GdaLockable">GdaLockable</link>
interface which can be used from any thread at the same time: the
<link linkend="GdaConnection">GdaConnection</link> and <link linkend="GdaSqlParser">GdaSqlParser</link>
objects implement that interface.
</para>
</sect2>
<sect2><title>Configuration management</title>
<para>
<itemizedlist>
<listitem><para>Data sources and installed providers are now handled using the
<link linkend="GdaConfig">GdaConfig</link> object, with the particularity that there can only be one
such object instantiated per program.</para></listitem>
<listitem><para>The GDA_DSN_LIST_IN_MEMORY environment variable which , if set, prevented &LIBGDA; from
writing the list of defined data sources to a file has been removed. To obtain the same result,
one must force the creation of the unique <link linkend="GdaConfig">GdaConfig</link> object with
the <link linkend="GdaConfig--user-file">user-file</link> property set to NULL.</para></listitem>
</itemizedlist>
</para>
</sect2>
<sect2><title>Database provider's changes</title>
<para>
<itemizedlist>
<listitem><para>BLOB handling in the PostgreSQL provider has changed and is now similar to JDBC and ODBC:
the provider does not handle orphaned BLOBs (which is a problem specific to PostgreSQL). See the section
about <link linkend="limitations_postgres">PostgreSQL's limitations</link> for more information.</para></listitem>
</itemizedlist>
</para>
</sect2>
<sect2><title>API changes</title>
<para>
<itemizedlist>
<listitem><para>Connections are now opened using
<link linkend="gda-connection-open-from-dsn">gda_connection_open_from_dsn ()</link> or
<link linkend="gda-connection-open-from-string">gda_connection_open_from_string () depending
on how the connection is defined</link></para></listitem>
<listitem><para>Upon opening a connection, the <parameter>username</parameter> and <parameter>password</parameter>
arguments have been replaced by a more flexible arguments passing mechanism where providers can specify
what authorization parameters they use</para></listitem>
<listitem><para>gda_server_provider_get_last_insert_id() has been removed in favor of the "last_insert_row" argument
of the <link linkend="gda-connection-statement-execute">gda_connection_statement_execute ()</link> and
<link linkend="gda-connection-statement-execute-non-select">gda_connection_statement_execute_non_select ()</link>
methods. If that argument is not NULL, then if the statement is an INSERT statement, the argument will
contain a list of values, one for each column of the modified table.</para></listitem>
<listitem><para>The GdaServerProviderInfo structure has been removed as it was useless, and the
gda_server_provider_get_info() has been replaced by a
<link linkend="gda-server-provider-get-name">gda_server_provider_get_name ()</link> method to access the
provider's name.</para></listitem>
<listitem><para><link linkend="gda-data-model-get-value-at">gda_data_model_get_value_at ()</link> now has an extra
<link linkend="GError">GError</link> argument to return an error if getting the value has failed</para></listitem>
<listitem><para>gda_data_model_get_column_index_by_name() has been replaced by
<link linkend="gda-data-model-get-column-index">gda_data_model_get_column_index()</link></para></listitem>
<listitem><para>gda_data_model_get_value_at_col_name() has been replaced by
<link linkend="gda-data-model-get-value-at-column">gda_data_model_get_value_at_column()</link></para></listitem>
</itemizedlist>
</para>
</sect2>
<sect2><title>List of removed objects and interfaces</title>
<para>
<itemizedlist>
<listitem><para>GdaClient</para></listitem>
<listitem><para>GdaRenderer, GdaXmlStorage, GdaEntity, GdaEntityField and GdaReferer interfaces</para></listitem>
<listitem><para>GdaDict, GdaDictType, GdaDictDatabase, GdaDictTable, GdaDictAggregate, GdaDictField,
GdaDictConstraint and GdaDictFunction dictionary related objects</para></listitem>
<listitem><para>GdaQuery, GdaQueryObject, GdaQueryFieldAgg, GdaQueryFieldAll, GdaQueryCondition, GdaQueryJoin,
GdaQueryFieldField, GdaQueryTarget, GdaQueryFieldFunc, GdaQueryFieldValue and GdaQueryField query related
objects</para></listitem>
<listitem><para>GdaCommand</para></listitem>
<listitem><para>GdaParameterList (replaced by <link linkend="GdaSet">GdaSet</link>),
GdaParameter (replaced by <link linkend="GdaHolder">GdaHolder</link>)</para></listitem>
<listitem><para>GdaObject, GdaObjectRef</para></listitem>
<listitem><para>GdaDataModelFilterSQL</para></listitem>
<listitem><para>GdaGraph, GdaGraphItem, GdaGraphQuery</para></listitem>
<listitem><para>GdaGraphviz</para></listitem>
<listitem><para>GdaDataModelQuery (features redundant with the
<link linkend="GdaDataSelect">GdaDataSelect</link> object) </para></listitem>
</itemizedlist>
</para>
</sect2>
<sect2><title>List of removed functions</title>
<para>
<itemizedlist>
<listitem><para>gda_delimiter_*()</para></listitem>
<listitem><para>gda_sql_transaction_parse*()</para></listitem>
<listitem><para>sql_*() (from the libsql library)</para></listitem>
<listitem><para>gda_server_provider_change_database()</para></listitem>
<listitem><para>gda_value_compare_ext()</para></listitem>
<listitem><para>gda_data_access_wrapper_row_exists()</para></listitem>
</itemizedlist>
</para>
</sect2>
</sect1>
</chapter>
|
