# Virtual methods for providers

Database providers usually (that is except for virtual providers explained later) subclass the GdaServerProvider class and implement at least the mandatory virtual methods.

Virtual providers are database providers when the database engine accessed does not support SQL (or supports it poorly), such as Berkeley databases or MDB (or even LDAP). These provider's implementation's design is to create GdaDataModel data model objects and make each of them appear as a named table once the connection is opened. For example the MDB provider creates a read-only data model for each table in an MDB file and make it appear using the original table name used in MS Access (the tables cannot be modified but it is possible to use all SQLite's SQL to make SELECT queries).

Virtual providers inherit the GdaVproviderDataModel class and not the GdaServerProvider as "normal" providers do, and the number of virtual methods to implement is very limited: only the get_name(), get_version(), get_server_version(), open_connection() and get_database() should be implemented, optionnally the close_connection() can also be implemented.

## Synchronous / asynchronous mode

All the provider's commands are executed in a synchronous mode (the caller is blocked until the provider's method terminates). However some virtual methods have the a task_id parameter, an async_cb or exec_cb callback function pointer and a cb_data parameter which can be set when an asynchronous mode is required; asynchronous mode is requested if and only if the async_cb or exec_cb parmeter is not NULL.

When an asynchronous mode is requested, the method should return TRUE if it returns a boolean or NULL if it returns a pointer and set a task identifier into the task_id parameter if not NULL. The task identifier is passed again when the async_cb or exec_cb callback functions are called by the provider when the execution is finished.

When the provider's method terminates, it then should call the function passed as async_cb with the cb_data as last parameters.

## Multi threaded environment

Each database provider should be usable in a multi threaded environment, even if they impose some restrictions as to how they can be used in such an environment. The &LIBGDA;'s framework provides some locking mechanism which is:

- if multi threading cannot be supported at all (for example if the client library internally used by the provider does not support it), then the provider's class implementation should set the class's limiting_thread attribute to: the GDA_SERVER_PROVIDER_UNDEFINED_LIMITING_THREAD constant. This constant will be resolved at run time as the thread which creates the 1st connection using that provider.

- if multi threading is supported but any connection (or related object) can only be used by the thread in which it was created, then for each opened connection, the "thread-owner" connection's property must be set to the current thread (and other related objects must be locked in a similar way)

- if no locking is done, then the provider is assumed to support full multi threading access, in this case make sure to set class's limiting_thread attribute to the NULL constant.

Note that the default provider's class value for the limiting_thread is safely set to the GDA_SERVER_PROVIDER_UNDEFINED_LIMITING_THREAD constant.

## Methods - provider's information

### get_name() - mandatory

This method returns the name of the provider; it should only contain alphanumeric characters.

### get_version() - mandatory

This method returns the version of the provider (providers built as part of &LIBGDA; have the same version as &LIBGDA;).

### get_server_version() - mandatory

This method returns the version of the database server to which a connection is opened

### supports_feature()

This method allows one to ask the provider if some specific features are available

## Methods - connection management

### open_connection() - mandatory

This method actually opens a connection to the database.

Any data specific to the connection (such as a database handle created by the database API when opening the connection) must be stored in a private structure (which should be defined in the `gda-<providername>.h` file as a <Providername>ConnectionData); this private structure's adress should be "attached" to the GdaConnection object using the gda_connection_internal_set_provider_data().

### close_connection() - mandatory

This method actually closes a connection previously opened by the open_connection() virtual method. This method is not mandatory for virtual providers.

The connection specific data for the database API can be retrieved using the gda_connection_internal_get_provider_data() method.

### get_database()

This method returns the name of the database to which a connection is opened.

## Methods - DDL queries

This group of virtual methods is composed of virtual methods which make it possible to handle DDL (data definition) queries to be executed using descriptions of the data required for each kind of DDL query, rather than using SQL directly (because DDL SQL is usually very database specific and must thus be adapted when migrating to another database type). For more information, see the global introduction to DDL queries.

Implementing these methods is not mandatory, and virtual provider's implementation should not implement them.

### supports_operation()

This virtual method tells if a particular DDL query type is supported (DDL query types are identified as GdaServerOperationType enums).

### create_operation()

This virtual method is used to create and initialize a GdaServerOperation object.

### render_operation()

This virtual method uses the information stored in a GdaServerOperation object to create the SQL statement(s) which would be executed if the operation was performed.

Note: more than one SQL statement may be returned by this method

Note: some operations don't return any SQL at all, if the operation can only be done using an API (and not through SQL)

### perform_operation()

This virtual method "performs" (execute) a GdaServerOperation object.

## Methods - transactions management

When a connection has been opened and no transaction has been started, then the provider should execute queries in auto commit mode.

### begin_transaction()

This method starts a new transaction.

### commit_transaction()

This method commits the current transaction.

### rollback_transaction()

This method cancels the current transaction.

### add_savepoint()

This method adds a save point to the current transaction, which allows for partial rollbacks within transactions.

### rollback_savepoint()

This method rolls back to a previously defined save point within the current transaction.

### delete_savepoint()

This method deletes a previously defined save point within the current transaction, it does not affect the transaction but it simply won't be possible to roll back to the savepoint afterwards.

## Methods - DML queries

This group of virtual methods is related to executing SQL queries of any kind. &LIBGDA; imposes that SQL statements be converted to one or more GdaStatement object(s), each GdaStatement object containing exactly one SQL statement (usually terminated by a semi colon). Each GdaStatement can then be prepared and/or executed individually.

Creating a GdaStatement object from some SQL is the job of a GdaSqlParser object.

### create_parser()

This method instantiates a GdaSqlParser object which is adapted to the database's specific SQL dialect. If the provider does not implement its own parser, then this method should not be implemented.

### statement_to_sql()

This method converts a GdaStatement object to its SQL representation. It should be implemented only if the default rendering is incorrect (to support some SQL specific dialect). The rendering process is decomposed into several rendering methods, and it is possible to override only some of the methods (see the PostgreSQL's implementation as an example).

### statement_prepare()

This method requests that a GdaStatement object be prepared for a future execution. It is called when gda_connection_statement_prepare() is called.

### statement_execute() - mandatory

This method actually executes a query represented by a GdaStatement object. See gda_connection_statement_execute() for more information, note that this method is also always the one called when any of the gda_connection_statement_execute*() methods are called.

A non NULL exec_cb parameter specifies that the user requests an asynchronous execution: the function has to return the NULL value immediately (it must not be blocking), and the task_id parameter must be set to contain a provider specific task ID. The exec_cb parameter points to a callback function (specified by the GdaConnection) which the provider has to call once the statement has been executed, using the same task ID which was defined when the statement_execute() function was called, and the cb_data specified when the statement_execute() function was called.

Note that if an asynchronous execution is requested, then the stmt, params, col_types, last_inserted_row, and cb_data parameters are supposed to exist and not be altered during the time the statement is executed (the GdaConnection ensures this) which means it's not necessary to make copies of them during the execution.

### handle_async()

This method is called by gda_connection_async_fetch_result().

This method, if implemented, is called to give the database provider a chance to execute some code in case an asynchronous statement's execution has been requested. Often providers will send some data over the network to the database server when the statement_execute() is called, and implement this virtual function as a way to get some data from the database server to see if the execution is terminated.

This function must return FALSE in case an error occurs, and TRUE if no error occurred (even if nothing was to be done).

## Methods - data representation

This group of virtual methods is related to converting some data between the three representations which are the SQL representation (to be directly included in a SQL statement), the human readable representation, and the GValue representation. For each type of data (identified as a GType type) which the provider can handle, a GdaDataHandler object is responsible of the conversions.

### get_data_handler()

This method returns a GdaDataHandler for the requested data type. It should only instantiate each GdaDataHandler once and reuse it if the same request happens (the returned object will not be modified).

This method is called by both gda_server_provider_get_data_handler_g_type() and gda_server_provider_get_data_handler_dbms() methods.

### get_def_dbms_type()

This method returns the name of the most common (database specific) data type which has the requested type.

### escape_string()

This method adds escape characters to a string, to be able to safely add it into an SQL statement.

### unescape_string()

This method does the reverse of the escape_string() method.

## Methods - metadata

The GdaServerProviderMeta structure defines all the methods which database providers must implement for the meta data extraction feature to work. Each method is used internally by the GdaConnection object when one calls the gda_connection_update_meta_store() method (where the connection object itself computes the list and order of methods to call). Each method must update the contents of one table in the connection's associated metadata (in its associated GdaMetaStore object), each has the same "base" arguments and some have extra arguments further specifying what needs to be updated.

For each table to update, there are two methods, which differ in their name only by the fact that one is starting with an underscore '_'. The method starting with an underscore must update the whole contents of the meta data table, and the other one must accept some more parameters to refine what gets updated. There are exception to this rule (such as the "tables_views()" method which must update both the "_tables" and "_views" tables, or the for the tables which have no foreign key (no dependency) to any other table).

Also, by convetion, the arguments can't be NULL unless the argument name has the "_n" suffix. For example the signature of the "tables_views()" method has the following signature (as defined in the `gda-server-provider.h` file)

    gboolean (*tables_views) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
                              GdaMetaContext *, GError **,
                              const GValue *table_catalog, const GValue *table_schema,
                              const GValue *table_name_n);

which means that the table_catalog and table_schema arguments can't be NULL, whereas the table_name can be NULL (and in this case the "tables_views()" method must update the "_tables" and "_views" tables regarding all the tables which are in the specified catalog and schema.

Make sure you read the information about the meta data's database structure in the Database structure, and specifically the data types section and the SQL identifiers section.

### Important note about SQL identifiers

As mentioned in the SQL identifiers section, any SQL identifier in the meta store is represented either:

- between double quotes if the SQL identifier is case sensitive

- all in lower case if the SQL identifier is not case sensitive

For database engines which internally store case insensitive SQL identifiers in lower case (such as PostgreSQL), the meta data reported by the database engine can be used almost AS IS, but for database engines which internally store case insensitive SQL identifiers in upper case (such as Oracle), the upper case needs to be converted to lower case. Also case sensitive SQL identifiers also need to be double quoted.

To minimize the work required to implement a database provider, &LIBGDA; allows the database provider to specifiy how case insensitive SQL identifiers are represented using gda_meta_store_set_identifiers_style() and the GdaMetaStore object will perform the work itself (the default being GDA_SQL_IDENTIFIERS_LOWER_CASE in GdaSqlIdentifierStyle.

Also note that the extra arguments for each virtual method listed below, when they are present and when they represent an SQL identifier, will be represented:

- for case insensitive SQL identifiers: using all lower or all upper case (depending on the setting set using gda_meta_store_set_identifiers_style()

- for case sensitive SQL identifiers: without the double quotes, but possibily with mixed or not lower and upper characters

### Reserved SQL keywords

Every database engine reserves some keywords for its own usage or because they are part of the SQL language. Reserved keywords can be used as SQL identifiers if they are put between double quotes.

As Each database engine has its own set of reserved keywords, the database provider has to tell the GdaMetaStore object what its keywords are, which is done using gda_meta_store_set_reserved_keywords_func() and passing a function which determines if a specific string is a reserved keyword. The usage of this function is similar to the usage of the gda_meta_store_set_identifiers_style() mentioned above.

Writing a function which tests if a string is a reserved keyword is a non complicated but error prone and not optimized, in the same way as writing a parser/lexer directly, so &LIBGDA; has a tool which generates a static hash table from a list of reserved keywords, which is in the `keywords.list` (several keywords can appear on the same line, separated by spaces or commas but the last line must remain empty).

### _info()

    gboolean (*_info) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
                       GdaMetaContext *, GError **);

This method must update the contents of the "_information_schema_catalog_name" table, which must contain exactly one row describing the catalog name for the connection.

### _btypes()

    gboolean (*_btypes) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
                         GdaMetaContext *, GError **);

This method must update the contents of the "_builtin_data_types" table which lists all the database's built in data types. There is no specific parameter.

### schemata() and _schemata()

    gboolean (*_schemata) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
                           GdaMetaContext *, GError **);
    gboolean (*schemata)  (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
                           GdaMetaContext *, GError **,
                           const GValue *catalog_name, const GValue *schema_name_n);

This method must update the contents of the "_schemata" table, which lists all the schemas (namespaces).

### tables_views() and _tables_views()

    gboolean (*_tables_views) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
                               GdaMetaContext *, GError **);
    gboolean (*tables_views)  (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
                               GdaMetaContext *, GError **,
                               const GValue *table_catalog, const GValue *table_schema,
                               const GValue *table_name_n);

This method must update the contents of the "_tables" and "_views" tables which list all the tables and views.

### columns() and _columns()

    gboolean (*_columns) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
                          GdaMetaContext *, GError **);
    gboolean (*columns)  (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
                          GdaMetaContext *, GError **,
                          const GValue *table_catalog, const GValue *table_schema,
                          const GValue *table_name);

This method must update the contents of the "_columns" table which lists all the columns of all the tables and views.

### constraints_tab() and _constraints_tab()

    gboolean (*_constraints_tab) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
                                  GdaMetaContext *, GError **);
    gboolean (*constraints_tab)  (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
                                  GdaMetaContext *, GError **,
                                  const GValue *table_catalog, const GValue *table_schema,
                                  const GValue *table_name, const GValue *constraint_name_n);

This method must update the contents of the "_table_constraints" table which lists all the constraints (primary key, foreign key, unique or check constraints) for each table.

### constraints_ref() and _constraints_ref()

    gboolean (*_constraints_ref) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
                                  GdaMetaContext *, GError **);
    gboolean (*constraints_ref)  (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
                                  GdaMetaContext *, GError **,
                                  const GValue *table_catalog, const GValue *table_schema,
                                  const GValue *table_name, const GValue *constraint_name);

This method must update the contents of the "_referential_constraints" table which lists all the referential constraints (which are also listed in the "_table_constraints" table).

### key_columns() and _key_columns()

    gboolean (*_key_columns) (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
                              GdaMetaContext *, GError **);
    gboolean (*key_columns)  (GdaServerProvider *, GdaConnection *, GdaMetaStore *,
                              GdaMetaContext *, GError **,
                              const GValue *table_catalog, const GValue *table_schema,
                              const GValue *table_name, const GValue *constraint_name);

This method must update the contents of the "_key_column_usage" table which lists all the columns involved in each table constraint (as listed in the "_table_constraints" table).

## Methods - misc.

### cancel()

This method cancels an asynchronous task.

### create_connection()

Reserved for internal implementation.

### is_busy()

This method tests if a connection is already busy in a, asynchronous task.