Get started guide

This guide shows how to use FluentJdbc in a project. ###Requirements### Java 8 ###Include FluentJdbc library###

<dependency>
    <groupId>org.codejargon</groupId>
    <artifactId>fluentjdbc</artifactId>
    <version>0.9.1</version>
</dependency>

###Set up FluentJdbc instance### A FluentJdbc instance needs to be configured for the project. It's responsible for custom configuration and provides access to the Query API. The Query API needs access to JDBC Connections, provided by a ConnectionProvider. The following example shows this based on a JDBC DataSource.

DataSource dataSource = ...
ConnectionProvider provider = new DataSourceConnectionProvider(dataSource);
FluentJdbc fluentJdbc = new FluentJdbcBuilder()
	.connectionProvider(provider)
        // maybe further customizations
	.build();

Note: There are many other ways than using a DataSource to integrate FluentJdbc to an environment. See further details at the Integration / ConnectionProvider section in the sidebar. ####Create a Query API instance#### With the configured ConnectionProvider (thread-safe)

Query query = fluentJdbc.query();

Alternatively with a given Connection instance (not thread-safe)

Connection connection = ...
Query query = fluentJdbc.queryOn(connection);

###Querying### The Query interface can then be used to execute SQL queries. Check the Query API page for all the details. Some examples: ####Update or insert queries#### With positional parameters

UpdateResult result = query
	.update("UPDATE CUSTOMER SET NAME = ?, ADDRESS = ?")
	.params("John Doe", "Dallas")
	.run();

With named parameters

Map<String, Object> namedParams = new HashMap<>();
namedParams.put("name", "John Doe");
namedParams.put("address", "Dallas");

UpdateResult result = query
	.update("UPDATE CUSTOMER SET NAME = :name, ADDRESS = :address")
	.namedParams(namedParams)
	.run();

####Select queries##### All result rows of a select query will be mapped to single java object by a Mapper. #####Mappers##### Implemented manually

Mapper<Customer> manualCustomerMapper = resultSet -> {
	return new Customer(resultSet.getString("NAME"));
}

Generated baed on object field name / column name matching (case-insensitive, ignoring '_')

ObjectMappers objectMappers = ObjectMappers.builder().build();
...
Mapper<Customer> generatedCustomerMapper = objectMappers.forClass(Customer.class);

#####List of results#####

List<Customer> customer = query
	.select("SELECT * FROM CUSTOMER WHERE NAME = ?")
	.params("John Doe")
	.listResult(customerMapper);

#####First result#####

Optional<Customer> firstCustomer = query
	.select("SELECT * FROM CUSTOMER WHERE NAME = ?")
	.params("John Doe")
	.firstResult(customerMapper);

#####Convenience mappers#####

Map<String, Object> namedParams = ...
Long count = query
	.select("SELECT COUNT(*) FROM CUSTOMER WHERE NAME = :name")
	.namedParams(namedParams)
	.singleResult(Mappers.singleLong());

#####Iterating large resultsets##### query .select("SELECT * FROM CUSTOMER") .iterateResult(customerMapper, (customer) -> { // do something with the customer }); ####Batch inserts or updates#### With positional parameters:

Iterator<List<Object>> params = ...;
query
	.batch("INSERT INTO CUSTOMER(NAME, ADDRESS) VALUES(?, ?)")
	.params(params)
	.singleResult(Mappers.singleLong);

With named parameters:

Iterator<Map<String, Object>> params = ...;
query
	.batch("INSERT INTO CUSTOMER(NAME, ADDRESS) VALUES(:name, :address)")
	.namedParams(params)
	.run();

####Custom parameter types#### Parameters can be normal JDBC types (Integer, Long, String, BigDecimal, java.sql.Date, ...) or

java.time types - supported out of the box.

query
	.update("UPDATE CUSTOMER SET DEADLINE = ?, UPDATED = ?")
	.params(LocalDate.of(2015, Month.MARCH, 5), Instant.now())
	.run();

Support for more types can be registered to FluentJdbc

Map<Class, ParamSetter> paramSetters = ...
FluentJdbc fluentJdbc = new FluentJdbcBuilder()
	.connectionProvider(provider)
	.paramSetters(paramSetters)
	.build();

####Transactions#### All queries will be executed in transactions as long as Connections provided by the ConnectionProvider are transaction-managed. Check the Transactions page for further details.