From: Warren Young Date: July 5 2005 11:24am Subject: BETA RELEASE: v2.0.0-beta1 List-Archive: http://lists.mysql.com/plusplus/4591 Message-Id: <42CA6DF3.80005@etr-usa.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit 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++/