Get started guide

Quick start guide

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

<dependency>
    <groupId>org.fluentjdbc</groupId>
    <artifactId>fluentjdbc</artifactId>
    <version>0.9</version>
</dependency>

note: it won't add any additional transitive dependencies. ###Create a FluentJdbc instance### A FluentJdbc object provides access to the Query API. Queries need access to JDBC Connections. This can be

either achieved with a ConnectionProvider (recommended) or passing in specific JDBC Connection object

directly.

FluentJdbc fluentJdbc = new FluentJdbcBuilder()
	.connectionProvider(provider) // optional
	.build();

####ConnectionProvider#### Provides JDBC Connections to FluentJdbc Queries. #####Connection from DataSource##### DataSourceConnectionProvider is provided out of the box

DataSource dataSource = ...
ConnectionProvider provider = new DataSourceConnectionProvider(dataSource);

#####Custom ConnectionProvider#####

ConnectionProvider provider = query -> {
	Connection connection = ...	// get a connection instance
	query.receive(connection);	// pass the connection to the query
	...	// release the connection
}

Its also possible to borrow Connections from callbacks, eg the one provided by Spring JdbcTemplate:

JdbcTemplate template = ...
ConnectionProvider provider = query -> {
	jdbcTemplate.execute(connection -> {
		query.receive(connection);
	});
}

###Run queries### With the configured ConnectionProvider

Query query = fluentJdbc.query() ...

Alternatively with a given Connection instance

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

####Update or insert queries#### The same API can be used for both update and insert queries. #####Update#####

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

Note: Result contains number of affected rows #####Update 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##### Results of select queries must be mapped from a ResultSet row to a single object. Select queries also support named parameters (see above). #####Mapping results##### Manually:

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

Or automatically to java beans:

ObjectMappers objectMappers = ObjectMappers.builder().build();
Mapper<Customer> beanCustomerMapper = 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##### (and named parameters usage)

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#### Using positional parameters:

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

Using 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 even 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();