MySQL Connector/C++

Not all objects implementing an interface support all of its methods. To avoid runtime errors (like "unimplemented feature"), you can implement the Capability_info interface to check for feature support upfront.

Use the has_capability(Capability) method, which returns:

• YES: The capability is supported.
• NO: The capability is not supported (calling it will throw an error).
• UNKNOWN: Support status cannot be determined at this moment.

Note that a Data_source might return UNKNOWN, but a Session created from that source might return NO for the same capability.

// Checking capability on a data source
Data_source ds(...);
if (NO == ds.has_capability(PREPARED_STATEMENTS))
  throw "this code requires prepared statements";

// Checking capability on a session
Session s(ds, ...);
if (NO == s.has_capability(PREPARED_STATEMENTS))
  throw "this code requires prepared statements";

The Core Data Connector (CDK) follows several key architectural principles that influence how you write code with it:

• Data Source Abstraction: Different types of data sources are identified by specific classes. Implementation details like drivers and driver managers are hidden behind these abstractions.
• RAII (Resource Acquisition Is Initialization): Objects are designed to manage their own lifecycles. You should use stack-based allocation so that resources are automatically freed when objects go out of scope. Avoid manual management via smart pointers where possible.
• Exception-based Error Handling: Methods are assumed to succeed if they return normally. If an operation fails (e.g., a commit() fails), an exception is thrown.
• Visitor Pattern for Data Access: To avoid unnecessary internal buffering, the CDK uses the Visitor pattern (e.g., Row_processor and Cursor::next_row(Row_processor)) to process data.
• Asynchronous Operations: Methods can return objects representing ongoing operations that can be queried, waited for, or cancelled. The design allows integration with async-io frameworks like boost::asio.
• Ownership Model: Objects have strict ownership hierarchies. For example, a reply object belongs to a session; if the session is destroyed, the reply becomes invalid and using it will raise an exception.
• Direct Data Access: The CDK provides direct access to raw bytes. Metadata handling and type conversions are the responsibility of the application code.

// Recommended RAII pattern
{
  Session s(...);
  // ... use session
}
// 's' is automatically cleaned up here

The CDK does not assume how data types are represented. Instead, it provides a framework for converting between raw bytes and native C++ types using Type_info and Format_info.

Key Components

• Type_info: An implementation-defined enumeration (e.g., STRING, NUMBER) describing the type of a column.
• Format_info: Describes how a specific type is serialized (e.g., different character encodings for a STRING).
• Codec<T>: An encoder/decoder used to convert between raw bytes and native C++ types.
• Format<T>: An object used to examine the properties of a representation format (e.g., checking the character encoding name).

Using Codecs and Formats

To convert data, you first verify the format is applicable to the type, then instantiate a Codec or Format object.

Format_info fi;
assert(fi.for_type(STRING));

// Create a codec for a specific type
Codec<STRING> codec(fi);

// Create a format object to inspect details
Format<STRING> fmt(fi);
cout << "character encoding: " << fmt.cs_name();

When performing a rcv_Rows or rcv_CursorRows operation, the protocol uses a Row_processor to stream result set rows to the application. The lifecycle follows a nested loop pattern:

1. Message Level: message_begin is called before any rows in a message, followed by message_end after all rows and the done callback.
2. Row Level: For each row, row_begin(row_count_t row) is called, followed by column processing, and finally row_end(row_count_t row).
3. Column Level: For each field in a row, the processor receives either col_null(col_count_t pos) (if the value is NULL) or a sequence of col_begin, col_data, and col_end (if the value contains data).

Control Flow via Return Values:

• row_begin returning false: The current row is skipped; row_end is still called, but no column callbacks occur.
• row_end returning false: The entire row sequence is interrupted. To process the remaining rows, you must create a new asynchronous operation.
• col_data returning 0: The remaining data for that specific field is discarded, and col_end is called immediately.

// Conceptual flow of Row_processor callbacks
// message_begin()
//   row_begin(0)
//     col_begin(0) -> col_data(...) -> col_end(0, len)
//     col_null(1)
//   row_end(0)
//   done(eod, more)
// message_end()

The CDK is organized into two main layers: the Core CDK API (high-level) and Protocol-level objects (low-level).

Core CDK API (Session-level)

These objects are used for standard data manipulation:

• data source: Represents the transactional data store.
• options: Describes settings for a data store session.
• session: The primary interface for accessing and manipulating data.
• result: Describes the outcome of a session operation.
• cursor: Used to iterate over rows in a result set.
• row processor: An interface used with a cursor to process rows without buffering.
• session listener: An object registered with a session to receive event notifications.

Protocol-level Objects

These handle the physical transport and communication:

• endpoint: Represents a connection endpoint (e.g., TCP/IP).
• connection options: Describes connection characteristics.
• connection: Represents the physical connection to an endpoint.
• protocol: Handles sending and receiving protocol messages over a connection.
• message processor: Processes messages received by a protocol object.

To use expressions in CRUD requests, you must implement the api::Expression interface. The process method of your expression object must accept an api::Expression::Processor and use it to visit the expression's syntax tree.

The Protocol implementation uses this visitor pattern to build the actual wire messages. You are responsible for ensuring that the process method correctly calls the appropriate processor methods to describe the intended expression.

Example: Implementing an Operator

If your expression represents an operation like foo > 7, your process implementation should call ep.op(">", args) where args is an Expr_list containing the operands.

// Example of how a processor visits an expression tree
void MyExpression::process(api::Expression::Processor *ep) {
    // If this expression is an operator like '>', we call ep.op
    // and pass an Expr_list containing the arguments.
    ep->op(">", args);
}

// Inside the processor's op callback, you can traverse arguments:
// args.get_expr(0).process(this);
// args.get_expr(1).process(this);