Re: [gnome-db] libgda-4.0 changes

["Vivien Malerba" <vmalerba gmail com>]

On Fri, Apr 11, 2008 at 12:33 AM, Daniel Espinosa <esodan gmail com> wrote:
> 2008/4/9, Murray Cumming <murrayc murrayc com>:
>
>
> > On Wed, 2008-04-09 at 09:03 +0200, Vivien Malerba wrote:
>  >  > On Tue, Apr 8, 2008 at 9:10 PM, Murray Cumming <murrayc murrayc com> wrote:
>  >  > > The libgda-4.0 API reference is now online, and it contains information
>  >  > >  about the changes between libgda-3.0 and libgda-4.0:
>  >  > >  http://library.gnome.org/devel/libgda-4.0/unstable/migration-2.html
>  >  > >
>  >  > >  I have some comments from my initial tests:
>  >  > >
>  >  > >  1.
>  >  > >  Creating and executing SQL statements was never easy but it is now even
>  >  > >  more awkward than before because you must create a GdaSqlParser and use
>  >  > >  it, and check for an error when doing that:
>  >  > >
>  >  > >  libgda-3.0:
>  >  > >
>  >  > >   GdaCommand* command = gda_command_new("SELECT * FROM album",
>  >  > >     GDA_COMMAND_TYPE_SQL, GDA_COMMAND_OPTION_STOP_ON_ERRORS);
>  >  > >   GdaDataModel* model =
>  >  > >     gda_connection_execute_select_command(connection, command, NULL /*
>  >  > >  params */, &error);
>  >  > >
>  >  > >
>  >  > >  libgda-4.0:
>  >  > >
>  >  > >   GdaSqlParser* parser = gda_connection_create_parser(connection);
>  >  > >   error = NULL;
>  >  > >   GdaStatement* statement = gda_sql_parser_parse_string(parser,
>  >  > >     "SELECT * FROM album",
>  >  > >     NULL /* remain */, &error);
>  >  > >   g_object_unref(parser);
>  >  > >
>  >  > >   if(error)
>  >  > >   {
>  >  > >     printf("GError from gda_sql_parser_parse_string(): %s\n",
>  >  > >  error->message);
>  >  > >     g_clear_error(&error);
>  >  > >     return EXIT_FAILURE;
>  >  > >   }
>  >  > >
>  >  > >   GdaDataModel* model =
>  >  > >     gda_connection_statement_execute_select(connection, statement,
>  >  > >  NULL /* params */, &error);
>  >  > >
>  >  >
>  >  > The reason you need to create an SQL parser is that the parser can
>  >  > keep track of some specific SQL dialects such as MySQL "delimiter"
>  >  > command which allows one to change the ";" to mark the end of a
>  >  > command with something else. If you've got a general parser then you
>  >  > will inevitably run into trouble when for instance parsing some SQL in
>  >  > a file and parsing your own SQL commands...
>  >  >
>  >  > However, in the general case you can still use
>  >  > gda_execute_select_command() or gda_execute_non_select_command() and
>  >  > the code above is reduced to one line.
>  >
>  >
>  > Oh, I didn't know about those functions. I see they are listed here:
>  >  http://library.gnome.org/devel/libgda-4.0/3.99/libgda-40-Convenient-functions.html
>  >  (That should really say "convenience" functions.)
>
>  I found, in the dictionary, "Convenient" for: "useful, easy or quick
>  to do; not causing problems"
>
>  and
>
>  "Convenience" for: " the quality of being useful, easy or suitable for"
>
>  My first efort was to do quickly task as easy as possible; I'm not
>  english speaker then just select the best one.
>
>
>  >
>  >  They should really be gda_connection_* functions, I think.
>  >
>
>  May be, but just point that most of the "Convenient" functions use
>  some "primary" parameters like gda_prepare_drop_table that needs a
>  GdaConnection object but you can't for now (see bug #525877), use
>  gda_perform_drop_table with out before call gda_prepare* function
>  becouse its implementation.
>
>  I think that most of this functions could move to other places, but
>  the point here is to have all this functions together becouse its
>  porpouse is do task quickly and easy as possible. May be we can write
>  a section "Gda Easy" in order to describe all this functions and how
>  you can take advantage of them, even if they are in diferent parts of
>  the documentation.
>

Convenient/convenience functions are clearly "wrap it all in one
function call" functions (bindings should probably don't care about
them), which is why they are not mixed with the objects to which they
relate most (mainly GdaConnection), and they are in a specific source
file.

What probably needs to be done is mention the convenience function in
the object's API (as I've done in SVN for
gda_connection_statement_execute_select() for example, and provide
some examples so that one can know these functions exist.

>
>  >
>  >  > >  2.
>  >  > >  The list of removed objects and functions needs information for eacho
>  >  > >  one about what should be used now:
>  >  > >  http://library.gnome.org/devel/libgda-4.0/unstable/ch07s05.html#id2561757
>  >  >
>  >  > Yes...
>  >  >
>  >  > >
>  >  > >  3.
>  >  > >  The
>  >  > >  GdaParameterList to GdaSet
>  >  > >  and GdaParameter to GdaHolder
>  >  > >  rename seems arbitary.
>  >  > >
>  >  > >  I guess that GdaSet should really be GdaValueSet or GdaValueList. Is it
>  >  > >  used for anything other than executing statements?
>  >  >
>  >  > It is difficult to find good object names. GdaValueSet was pretty high
>  >  > on my list, however one would expect a GdaValueSet to contain GdaValue
>  >  > objects which IMO is too close to the GValue and would have caused
>  >  > misunderstandings.
>  >  >
>  >  > Also GdaSet/GdaHolder are used in data model iterators, and also in
>  >  > some places to pass and unlimited list of named values.
>  >  >
>  >  > >
>  >  > >  GdaHolder is a particularly obscure name. If not GdaParameter then maybe
>  >  > >  GdaNamedValue?
>  >  >
>  >  > Renaming GdaSet to GdaValueSet and GdaHolder to GdaNamedValue would
>  >  > not be difficult, I can do it if you think they are better names.
>  >
>  >
>  > I do personally, but let's see what other people suggest first.
>  >
>  >
>
>  GdaHolder have a GValue plus aditional information, then it could be
>  called GdaParameter, becouse this will be used as _parameter_ in a
>  query.
>
>  GdaSet holds GdaHolders plus informations about its sources and groups
>  of holders for each source, its not just a list of holders and, if I
>  understand, you can have one GdaSet to hold groups of parameters for
>  different queries. The documentation must be improved to describe this
>  "uses" and internal structure. Becouse this Values will be used as
>  parameters may be GdaSet couldbe GdaParamenterSet.

GdaSet is currently used mainly to specify values for statement's
variables, but also to pass options to functions, and it's the base of
the GdaDataModelIter object, so talking about GdaParameter (this was
the name of the object in V3) is IMO too restrictive. Also GdaSet is a
very short name which is nice in source code.

I agree that GdaHolder could benefit from being renamed to
GdaNamedValue or something more explicit.

Vivien