/*
 * Copyright (c) 2011-2014 The original author or authors
 * ------------------------------------------------------
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * and Apache License v2.0 which accompanies this distribution.
 *
 *     The Eclipse Public License is available at
 *     http://www.eclipse.org/legal/epl-v10.html
 *
 *     The Apache License v2.0 is available at
 *     http://www.opensource.org/licenses/apache2.0.php
 *
 * You may elect to redistribute this code under either of these licenses.
 */
/**
 * = Vert.x JDBC client
 *
 * This client allows you to interact with any JDBC compliant database using an asynchronous API from your Vert.x
 * application.
 *
 * The client API is represented with the interface {@link io.vertx.ext.jdbc.JDBCClient}.
 *
 * To use this project, add the following dependency to the _dependencies_ section of your build descriptor:
 *
 * * Maven (in your `pom.xml`):
 *
 * [source,xml,subs="+attributes"]
 * ----
 * <dependency>
 *   <groupId>${maven.groupId}</groupId>
 *   <artifactId>${maven.artifactId}</artifactId>
 *   <version>${maven.version}</version>
 * </dependency>
 * ----
 *
 * * Gradle (in your `build.gradle` file):
 *
 * [source,groovy,subs="+attributes"]
 * ----
 * compile '${maven.groupId}:${maven.artifactId}:${maven.version}'
 * ----
 *
 * == Creating a the client
 *
 * There are several ways to create a client. Let's go through them all.
 *
 * === Using default shared data source
 *
 * In most cases you will want to share a data source between different client instances.
 *
 * E.g. you scale your application by deploying multiple instances of your verticle and you want each verticle instance
 * to share the same datasource so you don't end up with multiple pools
 *
 * You do this as follows:
 *
 * [source,java]
 * ----
 * {@link examples.JDBCExamples#exampleCreateDefault}
 * ----
 *
 * The first call to {@link io.vertx.ext.jdbc.JDBCClient#createShared(io.vertx.core.Vertx, io.vertx.core.json.JsonObject)}
 * will actually create the data source, and the specified config will be used.
 *
 * Subsequent calls will return a new client instance that uses the same data source, so the configuration won't be used.
 *
 * === Specifying a data source name
 *
 * You can create a client specifying a data source name as follows
 *
 * [source,java]
 * ----
 * {@link examples.JDBCExamples#exampleCreateDataSourceName}
 * ----
 *
 * If different clients are created using the same Vert.x instance and specifying the same data source name, they will
 * share the same data source.
 *
 * The first call to {@link io.vertx.ext.jdbc.JDBCClient#createShared(io.vertx.core.Vertx, io.vertx.core.json.JsonObject)}
 * will actually create the data source, and the specified config will be used.
 *
 * Subsequent calls will return a new client instance that uses the same data source, so the configuration won't be used.
 *
 * Use this way of creating if you wish different groups of clients to have different data sources, e.g. they're
 * interacting with different databases.
 *
 * === Creating a client with a non shared data source
 *
 * In most cases you will want to share a data source between different client instances.
 * However, it's possible you want to create a client instance that doesn't share its data source with any other client.
 *
 * In that case you can use {@link io.vertx.ext.jdbc.JDBCClient#createNonShared(io.vertx.core.Vertx, io.vertx.core.json.JsonObject)}.
 *
 * [source,java]
 * ----
 * {@link examples.JDBCExamples#exampleCreateNonShared}
 * ----
 *
 * This is equivalent to calling {@link io.vertx.ext.jdbc.JDBCClient#createShared(io.vertx.core.Vertx, io.vertx.core.json.JsonObject, java.lang.String)}
 * with a unique data source name each time.
 *
 * === Specifying a data source
 *
 * If you already have a pre-existing data source, you can also create the client directly specifying that:
 *
 * [source,java]
 * ----
 * {@link examples.JDBCExamples#exampleCreateWithDataSource}
 * ----
 *
 * == Closing the client
 *
 * It's fine to keep hold of the client for a long time (e.g. the lifetime of your verticle), but once you're
 * done with it you should close it.
 *
 * Clients that share a data source with other client instances are reference counted. Once the last one that references
 * the same data source is closed, the data source will be closed.
 *
 * === Automatic clean-up in verticles
 *
 * If you're creating clients from inside verticles, the clients will be automatically closed when the verticle is undeployed.
 *
 * == Getting a connection
 *
 * Once you've created a client you use {@link io.vertx.ext.jdbc.JDBCClient#getConnection(io.vertx.core.Handler)} to get
 * a connection.
 *
 * This will return the connection in the handler when one is ready from the pool.
 *
 * [source,java]
 * ----
 * {@link examples.JDBCExamples#example4}
 * ----
 *
 * The connection is an instance of {@link io.vertx.ext.sql.SQLConnection} which is a common interface not only used by
 * the Vert.x JDBC Client.
 *
 * You can learn how to use it in the http://vertx.io/docs/vertx-sql-common/$lang/[common sql interface] documentation.
 *
 * == Configuration
 *
 * Configuration is passed to the client when creating or deploying it.
 *
 * The following configuration properties generally apply:
 *
 * `provider_class`:: The class name of the class actually used to manage the database connections. By default this is
 * `io.vertx.ext.jdbc.spi.impl.C3P0DataSourceProvider` but if you want to use a different provider you can override
 * this property and provide your implementation.
 * `row_stream_fetch_size`:: The size of `SQLRowStream` internal cache which used to better performance. By default
 * it equals to `128`
 *
 * Assuming the C3P0 implementation is being used (the default), the following extra configuration properties apply:
 *
 * `url`:: the JDBC connection URL for the database
 * `driver_class`:: the class of the JDBC driver
 * `user`:: the username for the database
 * `password`:: the password for the database
 * `max_pool_size`:: the maximum number of connections to pool - default is `15`
 * `initial_pool_size`:: the number of connections to initialise the pool with - default is `3`
 * `min_pool_size`:: the minimum number of connections to pool
 * `max_statements`:: the maximum number of prepared statements to cache - default is `0`.
 * `max_statements_per_connection`:: the maximum number of prepared statements to cache per connection - default is `0`.
 * `max_idle_time`:: number of seconds after which an idle connection will be closed - default is `0` (never expire).
 *
 * Other Connection Pool providers are:
 *
 * * BoneCP
 * * Hikari
 *
 * Similar to C3P0 they can be configured by passing the configuration values on the JSON config object. For the special
 * case where you do not want to deploy your app as a fat jar but run with a vert.x distribution, then it is recommented
 * to use BoneCP if you have no write permissions to add the JDBC driver to the vert.x lib directory and are passing it
 * using the `-cp` command line flag.
 *
 * If you want to configure any other C3P0 properties, you can add a file `c3p0.properties` to the classpath.
 *
 * Here's an example of configuring a service:
 *
 * [source,java]
 * ----
 * {@link examples.JDBCExamples#example5}
 * ----
 *
 * Hikari uses a different set of properties:
 *
 * * `jdbcUrl` for the JDBC URL
 * * `driverClassName` for the JDBC driven class name
 * * `maximumPoolSize` for the pool size
 * * `username` for the login (`password` for the password)
 *
 * Refer to the https://github.com/brettwooldridge/HikariCP#configuration-knobs-baby[Hikari documentation]
 * for further details. Also refer to the http://www.jolbox.com/configuration.html[BoneCP documentation]
 * to configure BoneCP.
 *
 * == JDBC Drivers
 *
 * If you are using the default `DataSourceProvider` (relying on c3p0), you would need to copy the JDBC driver class
 * in your _classpath_.
 *
 * If your application is packaged as a _fat jar_, be sure to embed the jdbc driver. If your application is launched
 * with the `vertx` command line, copy the JDBC driver to `${VERTX_HOME}/lib`.
 *
 * The behavior may be different when using a different connection pool.
 *
 * == Data types
 *
 * Due to the fact that Vert.x uses JSON as its standard message format there will be many limitations to the data types
 * accepted by the client. You will get out of the box the standard:
 *
 * * null
 * * boolean
 * * number
 * * string
 *
 * There is also an optimistic cast for temporal types (TIME, DATE, TIMESTAMP) and optionally disabled for UUID. UUIDs
 * are supported by many databases but not all. For example MySQL does not support it so the recommended way is to use
 * a VARCHAR(36) column. For other engines UUID optimistic casting can be enabled using the client config json as:
 *
 * ----
 * { "castUUID": true }
 * ----
 *
 * When this config is present UUIDs will be handled as a native type.
 *
 *
 * == Use as OSGi bundle
 *
 * Vert.x JDBC client can be used as an OSGi bundle. However notice that you would need to deploy all dependencies
 * first. Some connection pool requires the JDBC driver to be loaded from the classpath, and so cannot be packaged /
 * deployed as bundle.
 */
@Document(fileName = "index.adoc")
@ModuleGen(name = "vertx-jdbc", groupPackage = "io.vertx")
package io.vertx.ext.jdbc;

import io.vertx.codegen.annotations.ModuleGen;
import io.vertx.docgen.Document;
