Updated documentation for the legacy C++ JDBC4 API

Author: Bogdan Degtyariov

doc/building.txt

@@ -6,16 +6,15 @@ Prerequisites
 To build Connector/C++, the following tools and libraries are required:
 
 - A C++ compiler that supports C++11. In case of gcc it must be at least
-  version 4.8. These compilers have been tested: gcc 4.8.4, clang 7.3.0,
-  MS Visual Studio 2015.
+  version 4.8. These compilers have been tested: gcc 4.8.4, 4.8.5, 4.9.2, 5.4.0,
+  6.3.0, 6.3.1, 7.1.1, 7.2.0, 7.2.1, clang 9.0.0, MS Visual Studio 2015.
 
-- CMake 2.8.11 or later.
+- CMake 2.8.12 or later.
 
 - OpenSSL version 1.0.x if connector is built with OpenSSL.
 
 @note: On some platforms Boost libraries are needed to build the connector.
-       Boost version 1.55 or higher is required (for MS Visual Studio 
-       version 1.59 or higher).
+       Boost version 1.59.
 
 Build configuration
 -------------------
@@ -44,6 +43,27 @@ By default a shared library is built. To build a static library, use the option:
 
 - `-DBUILD_STATIC=yes`
 
+Building of the legacy C++ JDBC4 library
+----------------------------------------
+Connector/C++ supports the legacy C++ JDBC4 API, which is placed inside a
+separate library `libmysqlcppconn` or `mysqlcppconn` depending on the Operating
+System.
+
+In order to enable building of the legacy C++ JDBC4 library the Connector/C++
+needs to be built with the following options:
+
+- `WITH_JDBC` to enable the legacy C++ JDBC4 API. Usage of this option in cmake
+  command looks like this: `-DWITH_JDBC=yes`. By default this option is not
+  enabled and the legacty C++ JDBC4 functionality is not built.
+
+- `MYSQL_DIR` to allow using server libraries such as libmysqlclient if it is
+  not installed at the default location.
+  The command line should look like: `-DMYSQL_DIR=<path_to_mysql_server_dir>`
+
+- `WITH_BOOST` to point to boost location if it is different from the default.
+  The command line should look like: `-DMYSQL_DIR=<path_to_mysql_server_dir>`
+
+
 Configuring SSL libraries
 -------------------------
 Connector/C++ can be built with different SSL libraries.
@@ -84,10 +104,18 @@ It is also possible to omit the `--config CCC` option in which case the default
 After a successful build, the build location should contain
 the Connector/C++ shared library:
 
-- `libmysqlcppconn8.so.1.0` on Unix
-- `libmysqlcppconn8.1.0.dylib` on OS X
+- `libmysqlcppconn8.so.1` on Unix
+- `libmysqlcppconn8.1.dylib` on OS X
 - `CCC/mysqlcppconn8-vsXX.dll` on Windows, where `-vs12` or `-vs14` prefix
   depends on the MSVC version used to build the connector
+  
+If Connector/C++ is built to support the legacy C++ JDBC4 API (WITH_JDBC option
+enabled) the build library directory will have another shared library:
+
+- `libmysqlcppconn.so.7` on Unix
+- `libmysqlcppconn.7.dylib` on OS X
+- `CCC/mysqlcppconn-7-vsXX.dll` on Windows, where `-vs12` or `-vs14` prefix
+  depends on the MSVC version used to build the connector
 
 On Unix and OS X also appropriate symbolic links are created. On Windows the
 import library for the DLL is created at `CCC/mysqlcppconn8.lib` (the `CCC/`
@@ -96,8 +124,15 @@ subdirectory is named the same as the build configuration used).
 In the case of a static library build, the output library names are:
 
 - `libmysqlcppconn8-static.a` on Unix and OS X
-- `CCC/mysqlcppconn8-static.lib` on Windows
+- `CCC/mysqlcppconn8-static.lib` and `CCC/mysqlcppconn8-static-mt.lib`
+  on Windows
+
+If Connector/C++ is built to support the legacy C++ JDBC4 API (WITH_JDBC option
+enabled) the build library directory will have another static library:
 
+- `libmysqlcppconn-static.a` on Unix and OS X
+- `CCC/mysqlcppconn-static.lib` and `CCC/mysqlcppconn-static-mt.lib`
+  on Windows
 
 ### Testing
 
@@ -130,8 +165,8 @@ $ cmake -DWITH_CONCPP=<Connector/C++ install location> <source location>/testapp
 $ cmake --build . --config CCC
 ~~~~~~~
 
-This should create the `devapi_test` and `xapi_test` executables in the `run/`
-subdirectory of the build location.
+This should create the `devapi_test`, `xapi_test` and `jdbc_test` executables
+in the `run/` subdirectory of the build location.
 
 @note
   On Windows, if the connector was built with the static runtime by specifying
@@ -142,6 +177,9 @@ subdirectory of the build location.
   The 32/64-bit Windows `cmake` generator (`"Visual Studio 14 2015 Win64"` vs
   `"Visual Studio 14 2015"`) used to build test applications must match
   the one used to build the connector.
+  
+@note in order to build `jdbc_test` the Connector/C++ has to be built
+  with WITH_JDBC, MYSQL_DIR and WITH_BOOST options.
 
 Before running test programs, ensure that a MySQL Server instance is running
 with X Plugin loaded into it. The easiest way of arranging this is to use
@@ -167,24 +205,17 @@ the standard 33060 one.
 Now one can start one of the test programs and see the output similar to the
 one presented below. The `devapi_test` program accepts port number as the first
 argument, with the default value 33060. Thus, if the server was started
-as described above, run the test program as follows:
+as described above, run the test program with the following URL as a parameter:
 
 ~~~~~~~
-$ run/devapi_test 13009
+$ run/devapi_test mysqlx://[email protected]:13009
 ~~~~~~~
 
 The program uses the `root` user account without any password and assumes
 that there is a `test` schema in the server (these assumptions hold for
 a server started using `mysql-test-run.pl`). Different user credentials can
 be passed as the second and the third argument of `devapi_test` invocation.
 
-For the `xapi_test` program, connection details can be given in form of an URL,
-as shown below:
-
-~~~~~~~
-$ run/xapi_test mysqlx://[email protected]:13009
-~~~~~~~
-
 If everything goes well, `devapi_test` should produce output similar to this:
 
 ~~~~~~~
@@ -222,6 +253,20 @@ doc#1: {"_id": "A0ABC08DAABAD1110C120800273BD115", "age": 2, "name": "bar", "toy
 Done!
 ~~~~~~~
 
+For the `xapi_test` program, connection details can be given in form of an URL,
+as shown below:
+
+~~~~~~~
+$ run/xapi_test mysqlx://[email protected]:13009
+~~~~~~~
+
+For the `jdbc_test` program the command line would look as this:
+
+~~~~~~~
+$ run/jdbc_test tcp://127.0.0.1:13009 root
+~~~~~~~
+
+
 Windows Notes
 -------------
 Connector/C++ uses C++11 language and for that reason it is not possible
@@ -256,7 +301,7 @@ the compiler and the linker invocations. Another option is to set the required
 deployment target and then the compiler defaults are changed accordingly.
 To define the deployment target, set the environment variable
 `MACOSX_DEPLOYMENT_TARGET` to the requested OS X version. Binary distributions
-of Connector/C++ are built with `MACOSX_DEPLOYMENT_TARGET` set to `10.9`.
+of Connector/C++ are built with `MACOSX_DEPLOYMENT_TARGET` set to `10.12`.
 
 Building Connector/C++ with `gcc` or its `libstdc++` runtime has not been
 tested and there is no support in the build system for using an alternative

doc/devapi_ref.txt

@@ -47,7 +47,7 @@ See @ref usage for instructions on how to build the sample code.
 Code which uses X DevAPI should include the `mysql_devapi.h` header. The API
 is declared within the `mysqlx` namespace:
 
-@skip #include <mysql_devapi.h>
+@skip #include <mysqlx/xdevapi.h>
 @until using namespace
 
 To create an @link mysqlx::Session `Session` @endlink object, specify DNS name

doc/index.txt

@@ -3,17 +3,34 @@ MySQL Connector/C++ Documentation  {#mainpage}
 
 MySQL Connector/C++ is a library for applications written in C or C++ that want
 to communicate with MySQL database servers. Version 8.0 of Connector/C++
-implements new APIs which, on top of traditional SQL, give access
-to MySQL implementing a document store. For code written in C++ this is the new
-[X DevAPI] (@ref devapi), which is the common MySQL API to access
-MySQL Document Store, also implemented by other MySQL connectors. Code written
-in plain C can use the [XAPI] (@ref xapi) -- a new plain C API which offers
-functionality similar to X DevAPI.
+implements three different APIs which can be used by applications...
 
+- The new [X DevAPI] (@ref devapi) for applications written in C++.
+- The new [XAPI] (@ref xapi) for applications written in plain C.
+- The [legacy JDBC based API]
+  (https://dev.mysql.com/doc/connector-cpp/en/connector-cpp-reference.html),
+  also implemented in version 1.1 of the connector.
+
+The new APIs give access to MySQL implementing a [document store]
+(https://dev.mysql.com/doc/refman/8.0/en/document-store.html). Consequently,
+code written against these APIs can work only with a MySQL Server with the
+X Plugin enabled in it. This is supported by MySQL Server version 8 or 5.7.12+.
+Apart from accessing the document store, the new APIs allow executing
+traditional SQL queries as well.
+
+Application written against the JDBC based API of Connector/C++ 1.1 can be also
+compiled with Connector/C++ 8.0 which is backward compatible with the earlier
+version. Such code does not require the X Plugin and can communicate with older
+version of the MySQL Server.
+
+The API to be used is chosen by including appropriate set of headers, as
+explained in @ref usage.
+ 
 More information:
 
 - [Connector/C++ X DevAPI Reference] (@ref devapi_ref)
 - [Connector/C++ XAPI Reference] (@ref xapi_ref)
+- [Connector/C++ legacy C++ API based on JDBC4 Reference] (@ref jdbc_ref)
 - [How to build code that uses Connector/C++](@ref usage)
 - [Building Connector/C++] (@ref building)
 - [Indexing Document Collections] (@ref indexing)

doc/jdbc_ref.txt

@@ -0,0 +1,170 @@
+Connector/C++ 8.0 legacy C++ API based on JDBC4 Reference {#jdbc_ref}
+=======================================
+
+Connector/C++ 8.0 supports the legacy C++ API based on JDBC4 specification.
+
+This allows an easy migration to Connector/C++ version 8.0 for applications
+that use Connector/C++ version 1.1. 
+
+More detailed information about the legacy C++ API can be found in the
+[X MySQL Connector/C++ Developer Guide]
+(https://dev.mysql.com/doc/connector-cpp/en/)
+of MySQL online manual.
+
+Source distributions of Connector/C++ include an examples directory
+containing usage examples that explain how to use the following classes: 
+
+ - `Connection`
+
+ - `Driver`
+
+ - `PreparedStatement`
+
+ - `ResultSet`
+
+ - `ResultSetMetaData`
+
+ - `Statement`
+
+ The examples cover:
+
+ - Using the Driver class to connect to MySQL
+
+ - Creating tables, inserting rows, fetching rows using (simple) statements
+
+ - Creating tables, inserting rows, fetching rows using prepared statements
+
+ - Hints for working around prepared statement limitations
+
+ - Accessing result set metadata 
+
+### Sample code which uses Connector/C++ with legacy C++ API ###
+
+The following code demonstrates how to connect to MySQL Server using the
+legacy C++ API.
+
+@note
+  The connection is established over the legacy protocol and therefore
+  X Plugin is not needed and the server does not need to support X Protocol.
+  
+After the connection is established the code executes a simple SQL statement
+and reads the result from the server. The source file can be found in
+testapp/jdbc_test.cc in the source distribution of Connector/C++ 8.0.
+See @ref usage for instructions on how to build the sample code.
+
+Each program which is using the legacy C++ API has to do the following
+includes:
+
+@dontinclude jdbc_test.cc
+@skip #include <jdbc/mysql_connection.h>
+@until #include <jdbc/mysql_driver.h>
+
+These headers are needed for using the `ResultSet` and `Statement` classes:
+
+@skip #include <jdbc/cppconn/resultset.h>
+@until #include <jdbc/cppconn/statement.h>
+
+Define the credentials for connecting, process command line params and
+other housekeeping stuff:
+
+@skip #define DEFAULT_URI "tcp://127.0.0.1"
+@until try {
+
+To establish a connection to MySQL Server, retrieve an instance of
+`sql::Connection` from a `sql::mysql::MySQL_Driver` object.
+A `sql::mysql::MySQL_Driver` object is returned by
+`sql::mysql::get_mysql_driver_instance()`:
+
+@skip sql::Driver
+@until con(driver->connect(url, user, pass));
+
+Make sure that you free con, the `sql::Connection` object, as soon as you do
+not need it any more. But do not explicitly free driver, the connector object.
+Connector/C++ takes care of freeing that.
+
+@note `get_mysql_driver_instance()` calls `get_driver_instance()`, which is 
+not thread-safe. Either avoid invoking these methods from within multiple
+threads at once, or surround the calls with a mutex to prevent simultaneous
+execution in multiple threads. 
+
+ These methods can be used to check the connection state or reconnect:
+
+ - `sql::Connection::isValid()` checks whether the connection is alive
+
+ - `sql::Connection::reconnect()` reconnects if the connection has gone down 
+
+The `sql::Connection` is used to set the schema and create a statement:
+
+@skip con->setSchema(database);
+@until boost::scoped_ptr< sql::Statement > stmt(con->createStatement());
+
+To run simple queries, you can use the `sql::Statement::execute()`,
+`sql::Statement::executeQuery()`, and `sql::Statement::executeUpdate()` methods.
+Use the method `sql::Statement::execute()` if your query does not return
+a result set or if your query returns more than one result set:
+
+@skip boost::scoped_ptr< sql::ResultSet >
+@until res(stmt->executeQuery("SELECT 'Welcome to Connector/C++' AS _message"));
+
+@note The Statement and ResultSet objects are temporary, but they are
+dynamically allocated. Therefore we use boost::scoped_ptr<> to free memory
+when they are not needed anymore.
+
+The API for fetching result sets is identical for (simple) statements and
+prepared statements. If your query returns one result set, use
+`sql::Statement::executeQuery()` or `sql::PreparedStatement::executeQuery()`
+to run your query. Both methods return `sql::ResultSet` objects.
+By default, Connector/C++ buffers all result sets on the client to support
+cursors. 
+
+The code below walks through the entire result set row by row using
+`sql::ResultSet::next()` method, which returns `true` if the row was sucessfully
+read. Otherwise it returns `false`, which means we reached the end of the
+result set and there are no more rows to read.
+
+The actual data is obtained trhough the getXxxx() functions such as
+`getInt(), getString()`, etc. The columns can be indexed by numbers in the
+order they are given inside the result set starting from 1.
+Alternatively the column name can be used as a string index.
+
+@skip while
+@until }
+
+Error handling is done through the standard try/catch blocks:
+
+@skip catch
+@until }
+
+Here is the complete C++ code of the test sample for the legacy C++ API:
+
+@include jdbc_test.cc
+
+<!--
+  Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
+
+  This program is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License, version 2.0, as
+  published by the Free Software Foundation.
+
+  This program is also distributed with certain software (including
+  but not limited to OpenSSL) that is licensed under separate terms,
+  as designated in a particular file or component or in included license
+  documentation.  The authors of MySQL hereby grant you an
+  additional permission to link the program and your derivative works
+  with the separately licensed software that they have included with
+  MySQL.
+
+  Without limiting anything contained in the foregoing, this file,
+  which is part of MySQL Connector/C++, is also subject to the
+  Universal FOSS Exception, version 1.0, a copy of which can be found at
+  http://oss.oracle.com/licenses/universal-foss-exception.
+
+  This program is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the GNU General Public License, version 2.0, for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program; if not, write to the Free Software Foundation, Inc.,
+  51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
+-->