List:MySQL++« Previous MessageNext Message »
From:Warren Young Date:July 5 2005 11:24am
Subject:BETA RELEASE: v2.0.0-beta1
View as plain text  
This is the first (and maybe only?) beta version for v2.0.0, which has 
been "cooking" for about a month now.  The API and ABI should be stable 
now, but there are no guarantees.  It generates libraries called v2.0.0, 
but we may release other libraries with that same name but different 
interfaces.

The purpose of this release is for people who care about MySQL++ to try 
building their existing programs against it.  Try to break it, and see 
what's needed to prevent it from breaking your program.

MySQL++ v2.0.0 will remain in this beta status as long as there are 
known outstanding problems that require library changes.  Conversely, if 
nobody complains about it, we will release v2.0.0 as-is after some 
period.  Once v2.0 is released, there will be a strong incentive to keep 
the library's current ABI fixed, and only add features and fix internal 
bugs.  If you don't like the current ABI, speak now or hold your peace 
until v3.0...which could be years away.

THIS IS NOT A DROP-IN REPLACEMENT FOR MySQL++ v1.7!

At minimum, you will have to recompile your program against this 
library.  Depending on the library features your program uses, you may 
also have to make code changes.  Please see the "Incompatible Library 
Changes" chapter of the user manual for a guide to migrating your code 
to this new version:

	http://tangentsoft.net/mysql++/doc/userman/html/breakages.html

That page documents the most important changes in the library, without 
much in the way of defense.  It's just there to help you understand the 
new release, and get your program ported over.

For the full details and justifications, here's the ChangeLog so far:

     o The library's shared object file name (soname) scheme has
       changed.  (This mainly affects POSIX systems.)

       The soname for the last 1.7.x releases of MySQL++ was
       libmysqlpp.so.4, meaning the fourth version of the library's
       application binary interface (ABI).  (The first ABI version
       in this scheme was that provided by 1.7.9.)  MySQL++
       2.0.0's soname is libmysqlpp.so.2.0.0.  Since the dynamic
       linker setup on some systems will create a symlink to
       that file called libmysqlpp.so.2, it's possible that this
       library could be confused with that for MySQL++ 1.7.19
       through .21, which also used this number.  Do not install
       this library on a system which still has binaries linked
       against that version of the library!

       The new scheme is {ABI}.{feature}.{bug fix}.  That is,
       the first number changes whenever we break the library's
       binary interface; the second changes when adding features
       that do not break the ABI; and the last changes when the
       release contains only internal bug fixes.  This means
       that we will probably end up with MySQL++ 3.0 and 4.0 at
       some point, so there will be further soname conflicts.
       Hopefully we can put these ABI changes off long enough
       to avoid any real problems.

     o Linux binary RPMs will henceforth include only the
       libmysqlpp.so.X.Y.Z file, and create any short names
       required, to allow multiple versions to be installed at
       once.  Currently, you cannot install two MySQL++ library
       RPMs at once, because they both have /usr/lib/libmysqlpp.so.X,
       for instance.

     o Connection::create_db() and drop_db() now return true on
       success, not false.

     o Connection::create_db(), drop_db() and select_db() now
       take their arguments by const reference.

     o Connection::create_db() and drop_db() use Query::exec()
       now, for efficiency, rather than Query::execute().

     o Removed Connection::infoo().  Apparently just there to
       save you from a typo when calling the info() method, since
       it was a mere alias.

     o Renamed Connection::real_connect() to connect(), gave
       several more of its parameters defaults, and removed old
       connect() function.  Then changed user manual and examples
       to use new APIs.

     o Renamed Connection::read_option() to set_option() and
       made it return true/false on success instead of zero/nonzero.

     o Removed query-building functions (exec*(), store*(),
       use()) from class Connection, and moved all the implementation
       code to class Query.  Query no longer delegates the final
       step of sending the query to the database server to
       Connection().

     o Extracted exception disabling mechanism out of the many
       classes that had the feature into a new OptionalExceptions
       base class, which all classes having this feature now
       derive from.  Also, removed all per-method exception
       handling flags.  Finally, added NoExceptions class.  With
       all of these changes, there is now a common way to disable
       exceptions with fine granularity on all objects that
       support the feature.

     o All custom MySQL++ exceptions now derive from the new
       Exceptions class.  This regularizes the exception interface
       and allows you to use a single catch() block if you want.

     o The "throw exceptions" flag is passed from parent to child
       in all situations now.  (Or if not, please report it as
       a bug.) This fulfills a promise made in the v1.7.9 user
       manual, with the cost being that some programs will see
       new exceptions thrown that they're not expecting.

     o Added a bunch of new exception types: ConnectionFailed,
       DBSelectionFailed, EndOfResults, and ObjectNotInitialized.
       Some of these replace the use of BadQuery, which in v1.7.x
       was a kind of generic exception, thrown when something
       more specific wasn't available.  Beware, this means that
       programs may start crashing after recompiling them under
       v2.0 due to uncaught exceptions, if they were only trying
       to catch BadQuery.

       There are additional instances where the library will
       throw new exceptions.  One is when calling a method that
       forces the internals to use an out-of-bounds index on a
       vector; previously, this would just make the program
       likely to crash.  Another is that the library uses the
       BadFieldName exception -- created in v1.7.30 -- in more
       apropos situations.

     o Renamed SQLQueryNEParms to BadParamCount, to match naming
       style of other concrete exception types.

     o Extracted lock()/unlock() functions from Connection and
       Query classes into a new Lockable interface class.

     o Removed ResUse::eof().  It's based on a deprecated MySQL
       C API feature, and it isn't needed anyway.

     o Returned Row subscripting to something more like the
       v1.7.9 scheme: operator[] takes a string for looking up
       a field by name, and lookup_by_name() has been removed.
       The problem that lead to needing this change now means
       that we cannot have indexing by integer through operator[],
       so Row now has an at() member, by analogy with the STL
       sequence containers.

     o Collapsed two of the Row::value_list*() overloads into
       two other similar functions using default parameters.
       This changes the API, but the removed functions aren't
       used within the library, and I doubt they are used outside,
       either.

     o Merged RowTemplate into Row.

     o Merged SQLQuery class into Query class.

     o Query is now derived from std::ostream instead of
       std::stringstream, and we manage our own internal string
       buffer.

     o Moved Extracted SQLParseElement and SQLQueryParms into
       their own module, qparms.

     o Collapsed mysql_* date and time base classes' methods and
       data into the subclasses.  Also, DateTime no longer derives
       from Date and Time; you could get away with that in the
       old hierarchy, but now it creates an inheritance diamond,
       and allows unsupported concepts like comparing a Time to
       a DateTime.

     o Removed "field name" form of Row::field_list().  It was
       pretty much redundant -- if you have the field names, why
       do you need a list of field names?

     o ColData can convert itself to bool now.  Thanks for this
       patch go to Byrial Jensen.

     o Removed simp_list_b type; wasn't being used, and doesn't
       look to be useful for end-user code.

     o Several methods that used to take objects by value now
       do so by const reference, for efficiency.

     o Several variable and function renamings so that MySQL++
       isn't needlessly tied to MySQL.  Even if we never make
       the library work with other database servers, there's
       little point in tying this library to MySQL blindly.

     o Renamed all private data members of MySQL++ classes to
       have trailing underscores.

     o 'private' section follows 'public' section in all classes
       now.

     o Removed mysql++.hh and sqlplus.hh backwards-compatibility
       headers.

     o Added copy ctors to Date/Time classes so that they will
       work in SSQLS under GCC 4.0.0.  Without these, the compiler
       couldn't make the conversion from raw MySQL row data.

     o Fixed a bunch of GCC 4.0 pedantic warnings: added virtual
       dtors to all base classes, calling base class ctors from
       leaf classes, etc.

     o All warnings fixed under VC++ at warning level 3.  (Mostly
       harmless signedness and integer conversion stuff.)

     o Updated LGPL license/copyright comments at the top of
       several files to use FSF's new physical address.

     o Relicensed user manual under a close variant of the Linux
       Documentation Project License, as it's designed for
       documentation, which the LGPL is not.  Permission for
       this received from Kevin Atkinson and MySQL AB.

     o Added ABI and API breakages chapter to user manual.  It
       is basically a subset of this ChangeLog, focusing only
       on the information an end-user needs to know when migrating
       between versions.

     o Reworked user manual's DocBook code quite a bit after
       reading Bob Stayton's book "DocBook XSL" 3/e.  Better
       handling of stylesheets, taking advantage of some superior
       DocBook features, prettier output (especially the HTML
       version), etc.

     o Basically rewrote doc/userman/README to make it clearer
       how to get started contributing to the user manual.  It's
       basically a "getting started with DocBook" guide now!

     o Lots of small text improvements to user and reference
       manuals.  Aside from the obvious tracking of library
       changes, made a bunch of minor style and clarity improvements.

     o Standardized exception handling code in the examples that
       use it.

     o Using new "no exceptions" feature of library in simple1
       example, so it is now truly simple.

     o Added new simple2 and usequery examples, to demonstrate
       the proper way to handle a "use" query, with exceptions
       disabled, and not, respectively.  Added them to the user
       manual, in the appropriate place.

     o Refactored the "print stock table" example functions
       again, to make code using them clearer.

     o UTF-8 to UCS-2 handling in examples is now automatic on
       Windows.

     o Removed unneeded debug code from in Windows Unicode output
       code in examples.  (Shouldn't have made it into a release
       at all.)

     o resetdb example is now clearer, and more robust in the
       face of database errors.

     o Simplified connect_to_db() in examples' util module.

As always, it is available at http://tangentsoft.net/mysql++/
Thread
BETA RELEASE: v2.0.0-beta1Warren Young5 Jul
  • Re: BETA RELEASE: v2.0.0-beta1Chris Frey6 Jul
    • Re: BETA RELEASE: v2.0.0-beta1Warren Young6 Jul
Re: BETA RELEASE: v2.0.0-beta1Ibrahim Mubarak13 Jul