Skip to content

Commit 9d54fa8

Browse files
rsomla1rsomla1
committed
Merge branch 'wl15590-doxygen-update' into release-8.4.0
2 parents eeb596e + fe861fa commit 9d54fa8

File tree

10 files changed

+606
-459
lines changed

10 files changed

+606
-459
lines changed

‎doc/devapi_ref.txt

Lines changed: 133 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -1,143 +1,185 @@
1-
Connector/C++ 8 X DevAPI Reference {#devapi_ref}
2-
====================================
1+
Connector/C++ X DevAPI Example {#devapi_example}
2+
================================================
33

4-
Connector/C++ 8 implements the X DevAPI, as described in
5-
the [X DevAPI User Guide]
6-
(http://dev.mysql.com/doc/x-devapi-userguide/en/index.html).
7-
The X DevAPI allows one to work with MySQL Servers implementing a document store
8-
via the X Plugin. One can also execute plain SQL queries using this API.
4+
Connector/C++ implements the X DevAPI, as described in
5+
the [X DevAPI User Guide](http://dev.mysql.com/doc/x-devapi-userguide/en/index.html).
6+
The X DevAPI allows one to work with the document store of MySQL Server 8 or later, communicating over the X protocol. It is also possible to execute plain SQL queries using this API.
97

108
To get started, check out some of the main X DevAPI classes:
119

12-
- To access data first create a @link mysqlx::abi2::r0::Session `Session`@endlink
13-
object. Keep in mind that @link mysqlx::abi2::r0::Session `Session`@endlink is
14-
not thread safe!
10+
- To access data first create a `mysqlx::Session` object. Keep in mind that
11+
`mysqlx::Session` is not thread safe!
1512

1613
- To manipulate data stored in a document collection or a table, create
17-
a @link mysqlx::abi2::r0::Collection `Collection`@endlink or a @link mysqlx::abi2::r0::Table
18-
`Table`@endlink object using methods `getCollection()` or `getTable()` of
19-
a @link mysqlx::abi2::r0::Schema `Schema`@endlink object obtained from the session.
20-
21-
- Queries and other statements are created using methods of the `Collection`
22-
or `Table` class, such as `find()`. They are executed with method `execute()`.
23-
24-
- Results of a query are examined using @link mysqlx::abi2::r0::DocResult
25-
`DocResult`@endlink or @link mysqlx::abi2::r0::RowResult `RowResult`@endlink instances
26-
returned from `execute()` method. Method `fetchOne()` fetches the next item
27-
(a document or a row) from the result until there are no more items left.
28-
Method `fetchAll()` can fetch all items at once and store them in an STL
29-
container.
30-
31-
- Documents and rows from query results are represented by @link mysqlx::abi2::r0::DbDoc
32-
`DbDoc`@endlink and @link mysqlx::abi2::r0::Row `Row`@endlink instances, respectively.
14+
a `mysqlx::Collection` or a `mysqlx::Table` object using methods
15+
[`getCollection()`](@ref mysqlx::abi2::r0::Schema::getCollection)
16+
or [`getTable()`](@ref mysqlx::abi2::r0::Schema::getTable) of
17+
a `mysqlx::Schema` object obtained from the session.
18+
19+
- Queries and other statements are created using methods of
20+
the `mysqlx::Collection` or `mysqlx::Table` class, such as
21+
[`find()`](@ref mysqlx::abi2::r0::Collection::find). They
22+
are executed with
23+
the [`execute()`](@ref mysqlx::abi2::r0::CollectionFind::execute) method.
24+
25+
- Results of a query are examined using `mysqlx::DocResult`
26+
or `mysqlx::RowResult` instances returned from `execute()` method. Method
27+
[`fetchOne()`](@ref mysqlx::abi2::r0::DocResult::fetchOne) fetches the next
28+
item (a document or a row) from the result until there are no more items
29+
left. Method [`fetchAll()`](@ref mysqlx::abi2::r0::DocResult::fetchAll) can
30+
fetch all items at once and store them in an STL container.
31+
32+
- Documents and rows from query results are represented by `mysqlx::DbDoc` and
33+
`mysqlx::Row` instances, respectively.
3334

3435
A more complete example of code that access MySQL Document Store using
35-
the X DevAPI is presented below. See also the [list of X DevAPI classes]
36-
(@ref devapi).
36+
the X DevAPI is presented below. See also
37+
the [list of X DevAPI classes](@ref devapi).
3738

3839

3940
### Sample code which uses Connector/C++ with X DevAPI ###
4041

41-
The following Connector/C++ application connects to a MySQL Server with
42-
X Plugin, creates a document collection, adds a few documents to it, queries
42+
The following Connector/C++ application connects to a MySQL Server over
43+
X protocol, creates a document collection, adds a few documents to it, queries
4344
the collection and displays the result. The sample code can be found in file
4445
`testapp/devapi_test.cc` in the source distribution of Connector/C++ 8.
4546
See @ref usage for instructions on how to build the sample code.
4647

4748
@dontinclude devapi_test.cc
4849

49-
Code which uses X DevAPI should include the `mysql_devapi.h` header. The API
50+
Code which uses X DevAPI should include the `<mysqlx/xdevapi.h>` header. The API
5051
is declared within the `mysqlx` namespace:
5152

5253
@skip #include <mysqlx/xdevapi.h>
5354
@until using namespace
5455

55-
To create an @link mysqlx::abi2::r0::Session `Session` @endlink object, specify DNS name
56-
of a MySQL Server, the port on which the plugin listens (default port is 33060)
57-
and user credentials:
56+
To create a `mysqlx::Session` object pass a connection string in URI format
57+
such as `"mysqlx://mike:s3cr3t!@localhost:13009"`. It specifies the host and
58+
port of the MySQL Server (port can be skipped in which case the default port
59+
will be used) and the MySQL account credentials.
5860

5961
@skipline main
6062
@until Session
6163

62-
Another way of specifying session parameters is by means of a `mysqlx`
63-
connection string like `"mysqlx://mike:s3cr3t!@localhost:13009"`. Once created,
64-
the session is ready to be used. If the session can not be established,
65-
the `Session` constructor throws an error.
66-
67-
To manipulate documents in a collection, create a @link mysqlx::abi2::r0::Collection
68-
`Collection`@endlink object, first asking session for that collection's
69-
@link mysqlx::abi2::r0::Schema `Schema`@endlink:
70-
71-
@skipline cout
64+
If the session could not be established the `mysqlx::Session` constructor
65+
throws an error derived from `mysqlx::Error` class (which also derives from
66+
`std::exception`). Otherwise the session is ready to be used once created.
67+
68+
@note
69+
There are alternative ways of specifying session options, for example:
70+
~~~~~~
71+
Session s1("mysqlx://mike:s3cr3t!@localhost:13009");
72+
Session s2("localhost", 13009, "mike", "s3cr3t!");
73+
Session s3(13009, "mike", "s3cr3t!"); // session on localhost
74+
Session s4(
75+
SessionOption::USER, "mike",
76+
SessionOption::PWD, "s3cr3t!",
77+
SessionOption::HOST, "localhost",
78+
SessionOption::PORT, 13009
79+
);
80+
~~~~~~
81+
In general the `mysqlx::Session` constructor uses its arguments to create
82+
a `mysqlx::SessionSettings` instance -- see documentation of that class for
83+
possible arguments to the constructor. Enumeration `mysqlx::SessionOption`
84+
defines all session options recognized by the connector.
85+
86+
87+
Next a `test` schema is created and a `c1` collection within that schema. They
88+
are represented by `mysqlx::Schema` and `mysqlx::Collection` objects,
89+
respectively:
90+
91+
@skipline "Session accepted
7292
@until Collection
7393

74-
The `true` parameter to @link mysqlx::abi2::r0::Schema::createCollection
75-
`createCollection()`@endlink method specifies that collection should be re-used
76-
if it already exists. Without this parameter an attempt to create an already
77-
existing collection produces an error. It is also possible to create
78-
a `Collection` object directly, without creating the `Schema` instance:
94+
The `true` parameter
95+
to the [`Session::createSchema()`](@ref mysqlx::abi2::r0::Session::createSchema)/[`Schema::createCollection()`](@ref mysqlx::abi2::r0::Schema::createCollection)
96+
method specifies that the schema/collection should be re-used if it already
97+
exists (rather than throwing an error which is the default behavior).
98+
99+
@note
100+
It is also possible to create a `mysqlx::Collection` object directly, without
101+
explicitly creating a `mysqlx::Schema` instance:
79102
~~~~~~~~
80-
Collection coll = sess.getSchema("test").getCollection("c1",true)
103+
Collection coll = sess.getSchema("test").createCollection("c1",true)
81104
~~~~~~~~
82105

83106
Before adding documents to the collection, all the existing documents are
84-
removed first using the @link mysqlx::abi2::r0::Collection::remove `Collection::remove()`@endlink
85-
method (expression "true" selects all documents in the collection):
107+
removed first using
108+
the [`Collection::remove()`](@ref mysqlx::abi2::r0::Collection::remove)
109+
method. The argument to this method is an expression which selects documents
110+
to be removed, in this case expression `"true"` selects all documents:
86111

87112
@skipline remove("true")
88113

89114
Note that the `remove()` method returns an operation that must
90115
be explicitly executed to take effect. When executed, operation returns
91116
a result (ignored here; the results are used later).
92117

93-
To insert documents use the @link mysqlx::abi2::r0::Collection::add
94-
`Collection::add()`@endlink method. Documents are described by JSON strings
95-
using the same syntax as MySQL Server. Note that double quotes are required
96-
around field names and they must be escaped inside C strings, unless the new
97-
C++11 `R"(...)"` string literal syntax is used as in the example below:
118+
To insert documents use
119+
the [`Collection::add()`](@ref mysqlx::abi2::r0::Collection::add) method.
120+
Documents are described by JSON strings. Note that double quotes are required
121+
around field names and they must be escaped inside C strings unless
122+
the `R"(...)"` raw string literal syntax is used as in the example below.
123+
Note also how internal code block is used to delete the result when it is no longer needed:
98124

99125
@skipline {
100126
@until cout
101127
@until cout
102128
@until cout
103129
@until cout
130+
@until cout
131+
@until cout
104132
@until }
105133

106134
Result of the `add()` operation is stored in the `add` variable to be able
107-
to read identifiers of the documents that were added. These identifiers are
108-
generated by the connector, unless an added document contains an `"_id"` field
109-
which specifies its identifier. Note how internal code block is used to delete
110-
the result when it is no longer needed.
111-
112-
@note It is possible to chain several `add()` calls as follows:
113-
`coll.add(doc1).add(doc2)...add(docN).execute()`. It is also possible to pass
114-
several documents to a single `add()` call:
115-
`coll.add(doc1, ..., docN).execute()`. Another option is to pass
116-
to `Collection::add()` an STL container with several documents.
117-
118-
To query documents of a collection use the @link mysqlx::abi2::r0::Collection::find
119-
`Collection::find()`@endlink method:
120-
121-
@skipline coll.find(
135+
to read identifiers of the inserted documents that were assigned by the server.
136+
They are returned by the `getGeneratedIds()` method of the `mysqlx::Result`
137+
class.
138+
139+
@note
140+
Server does not generate identifiers for documents which have an `"_id"` field
141+
-- in that case the value of the `"_id"` field is used as document's
142+
identifier. These explicit identifiers are not reported by `getGeneratedIds()`
143+
method.
144+
145+
@note
146+
It is possible to chain several `add()` calls as follows:
147+
`coll.add(doc1).add(doc2)...add(docN).execute()`. It is also possible to pass
148+
several documents to a single `add()` call:
149+
`coll.add(doc1, ..., docN).execute()`. Another option is to pass
150+
to `Collection::add()` an STL container with several documents.
151+
152+
To query documents of a collection use
153+
the [`Collection::find()`](@ref mysqlx::abi2::r0::Collection::find) method
154+
which takes a Boolean expression that selects documents as its argument:
155+
156+
@skipline "Fetching documents
157+
@until coll.find(
122158

123159
The result of the `find()` operation is stored in a variable of type
124-
@link mysqlx::abi2::r0::DocResult `DocResult`@endlink which gives access to the returned
125-
documents that satisfy the selection criteria. These documents can be fetched
126-
one by one using the @link mysqlx::abi2::r0::DocResult::fetchOne
127-
`DocResult::fetchOne()`@endlink method, until it returns a null document that
128-
signals end of the sequence:
160+
`mysqlx::DocResult` which gives access to the returned documents that satisfy
161+
the selection criteria. These documents can be iterated using a range-for loop:
129162

130-
@skipline fetchOne()
163+
@skipline int i
131164
@until cout
132165

133-
Given a @link mysqlx::abi2::r0::DbDoc `DbDoc`@endlink object it is possible to iterate
166+
@note
167+
An alternative is to fetch documents one-by-one using
168+
the [`DocResult::fetchOne()`](@ref mysqlx::abi2::r0::DocResult::fetchOne)
169+
method, for example like this:
170+
~~~~~~~
171+
DbDoc doc = docs.fetchOne();
172+
173+
for (int i = 0; doc; ++i, doc = docs.fetchOne()) { ... }
174+
~~~~~~~
175+
176+
Given a `mysqlx::DbDoc` object it is possible to iterate
134177
over its fields as follows:
135178

136179
@skipline for
137180
@until }
138181

139-
Note how the @link mysqlx::abi2::r0::DbDoc::operator[] `operator[]`@endlink is used
140-
to access values of document fields:
182+
Note how `DbDoc::operator[]` is used to access values of document fields:
141183

142184
@skipline name
143185
@until cout
@@ -146,20 +188,20 @@ The value of a field is automatically converted to a corresponding C++ type.
146188
If the C++ type does not match the type of the field value, conversion error
147189
is thrown.
148190

149-
Fields which are sub-documents can be converted to the `DbDoc` type. The
150-
following code demonstrates how to process a `"date"` field which is
151-
a sub-document. Note how methods @link mysqlx::abi2::r0::DbDoc::hasField
152-
`DbDoc::hasField()`@endlink and @link mysqlx::abi2::r0::DbDoc::fieldType
153-
`DbDoc::fieldType()`@endlink are used to examine existence and type of a field
154-
within a document.
191+
Fields which are sub-documents can be converted to the `mysqlx::DbDoc` type. The
192+
following code demonstrates how to process the `"date"` field which is
193+
a sub-document. Methods
194+
[`DbDoc::hasField()`](@ref mysqlx::abi2::r0::DbDoc::hasField)
195+
and [`DbDoc::fieldType()`](@ref mysqlx::abi2::r0::DbDoc::fieldType)
196+
are used to examine existence and type of a field within a document.
155197

156198
@skipline if
157199
@until }
158200
@until }
159201

160-
In case of arrays, currently no conversion to C++ types is defined. However,
202+
In case of arrays currently no conversion to C++ types is defined. However,
161203
individual elements of an array value can be accessed using `operator[]` or
162-
they can be iterated using range for loop.
204+
they can be iterated using a range-for loop.
163205

164206
@skipline if
165207
@until }
@@ -213,9 +255,10 @@ doc#1: {"_id": "A0ABC08DAABAD1110C120800273BD115", "age": 2, "name": "bar", "toy
213255
Done!
214256
~~~~~~~
215257

258+
<!-- TODO: Include here the output from run of testapp that is automatically generated by build system -->
216259

217260
<!--
218-
Copyright (c) 2015, 2020, Oracle and/or its affiliates.
261+
Copyright (c) 2015, 2024, Oracle and/or its affiliates.
219262

220263
This program is free software; you can redistribute it and/or modify
221264
it under the terms of the GNU General Public License, version 2.0, as

‎doc/index.txt

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,27 @@
11
MySQL Connector/C++ Documentation {#mainpage}
2-
=================================
2+
==============================================
33

44
MySQL Connector/C++ is a library for applications written in C or C++ that
55
communicate with MySQL database servers. Version 8 of Connector/C++
66
implements three different APIs which can be used by applications:
77

8-
- The new [X DevAPI](@ref devapi_ref) for applications written in C++.
9-
- The new [X DevAPI for C](@ref xapi_ref) for applications written in plain C.
10-
- The [legacy JDBC4-based API](@ref jdbc_ref)
11-
also implemented in version 1.1 of the connector.
8+
- The [X DevAPI](@ref devapi_example) for applications written in C++.
129

13-
The new APIs give access to MySQL implementing a
14-
[document store](https://dev.mysql.com/doc/refman/en/document-store.html).
15-
Internally these APIs use the new X Protocol to communicate with the MySQL
16-
Server. Consequently, code written against these APIs can work only with MySQL
17-
Server 8 with the X Plugin enabled in it. Apart from accessing the document
18-
store, the new APIs allow executing traditional SQL queries as well.
10+
- The [X DevAPI for C](@ref xapi_example) for applications written
11+
in plain C.
1912

20-
Applications written against the JDBC4 based API of Connector/C++ 1.1 can be also
21-
compiled with Connector/C++ 8 which is backward compatible with the earlier
22-
version. Such code does not require the X Plugin and can communicate with older
23-
versions of the MySQL Server using the legacy protocol.
13+
- The [classic JDBC4-based API](@ref jdbc_example) that was also implemented
14+
in earlier versions of the connector.
2415

16+
X DevAPI and X DevAPI for C give access to MySQL implementing a
17+
[document store](https://dev.mysql.com/doc/refman/en/document-store.html).
18+
Internally these APIs use the X Protocol to communicate with the MySQL
19+
Server. Consequently, code written against these APIs can work only with MySQL
20+
Server 8 or later. Apart from accessing the document store, these APIs allow
21+
executing traditional SQL queries as well.
22+
The classic JDBC4-based API, on the other hand, uses the classic protocol and
23+
can communicate with older versions of the MySQL Server. It can work only with
24+
SQL queries and does not support CRUD operations over the document store.
2525
The API to be used is chosen by including appropriate set of headers, as
2626
explained in @ref usage.
2727

0 commit comments

Comments
 (0)