Holon platform JDBC Datastore

Latest release: 5.7.0

This is the reference JDBC implementation of the Holon Platform Datastore API, using the Java JDBC API and the SQL language for data access and manipulation.

See the Datastore API documentation for information about the Holon Platform Datastore API.

The JDBC Datastore implementation relies on the following conventions regarding DataTarget and Path naming strategy:

• The DataTarget name is interpreted as the database table (or view) name.
• The Path name is interpreted as a table column name.

As a relational Datastore, standard relational expressions are supported (alias, joins and sub-queries).

Transactions support is ensured through the Holon Platform Transactional API.

The JDBC Datastore leverages on dialects to transparently support different RDBMS vendors. Dialects for the following RDBMS are provided:

• MySQL
• MariaDB
• Oracle Database
• Microsoft SQL Server
• PostgreSQL
• IBM DB2
• IBM Informix
• SAP HANA
• H2
• HSQLDB
• Derby
• SQLite

A complete Spring and Spring Boot support is provided for JDBC Datastore integration in a Spring environment and for auto-configuration facilities.

See the module documentation for details.

Just like any other platform module, this artifact is part of the Holon Platform ecosystem, but can be also used as a stand-alone library.

See Getting started and the platform documentation for further details.

At-a-glance overview

JDBC Datastore operations:

Datastore datastore = JdbcDatastore.builder().dataSource(myDataSource).build();

datastore.save(TARGET, PropertyBox.builder(TEST).set(ID, 1L).set(VALUE, "One").build());

Stream<PropertyBox> results = datastore.query().target(TARGET).filter(ID.goe(1L)).stream(TEST);

List<String> values = datastore.query().target(TARGET).sort(ID.asc()).list(VALUE);

Stream<String> values = datastore.query().target(TARGET).filter(VALUE.startsWith("prefix")).restrict(10, 0).stream(VALUE);

long count = datastore.query(TARGET).aggregate(QueryAggregation.builder().path(VALUE).filter(ID.gt(1L)).build()).count();

Stream<Integer> months = datastore.query().target(TARGET).distinct().stream(LOCAL_DATE.month());

datastore.bulkUpdate(TARGET).filter(ID.in(1L, 2L)).set(VALUE, "test").execute();

datastore.bulkDelete(TARGET).filter(ID.gt(0L)).execute();

Transaction management:

long updatedCount = datastore.withTransaction(tx -> {
	long updated = datastore.bulkUpdate(TARGET).set(VALUE, "test").execute().getAffectedCount();
			
	tx.commit();
			
	return updated;
});

JDBC Datastore extension:

// Function definition
class IfNull<T> implements QueryFunction<T, T> {
  /* content omitted */		
}

// Function resolver
class IfNullResolver implements ExpressionResolver<IfNull, SQLFunction> {

  @Override
  public Optional<SQLFunction> resolve(IfNull expression, ResolutionContext context) {
    return Optional.of(SQLFunction.create(args ->  "IFNULL(" + args.get(0) + "," + args.get(1) + ")"));
  }
	
}

// Datastore integration
Datastore datastore = JdbcDatastore.builder().withExpressionResolver(new IfNullResolver()).build();

Stream<String> values = datastore.query(TARGET).stream(new IfNull<>(VALUE, "(fallback)"));

JDBC Datastore configuration using Spring:

@EnableJdbcDatastore
@Configuration
class Config {

  @Bean
  public DataSource dataSource() {
    return buildDataSource();
  }

}

@Autowired
Datastore datastore;

JDBC Datastore auto-configuration using Spring Boot:

spring:
  datasource:
    url: "jdbc:h2:mem:test"
    username: "sa"
    
holon: 
  datastore:
    trace: true

See the module documentation for the user guide and a full set of examples.

Code structure

See Holon Platform code structure and conventions to learn about the "real Java API" philosophy with which the project codebase is developed and organized.

Getting started

System requirements

The Holon Platform is built using Java 11, so you need a JRE/JDK version 11 or above to use the platform artifacts.

A JDBC driver which supports the JDBC API version 4.x or above is reccomended to use all the functionalities of the JDBC Datastore.

Releases

See releases for the available releases. Each release tag provides a link to the closed issues.

Obtain the artifacts

The Holon Platform is open source and licensed under the Apache 2.0 license. All the artifacts (including binaries, sources and javadocs) are available from the Maven Central repository.

The Maven group id for this module is com.holon-platform.jdbc and a BOM (Bill of Materials) is provided to obtain the module artifacts:

Maven BOM:

<dependencyManagement>
    <dependency>
        <groupId>com.holon-platform.jdbc</groupId>
        <artifactId>holon-datastore-jdbc-bom</artifactId>
        <version>5.7.0</version>
        <type>pom</type>
        <scope>import</scope>
    </dependency>
</dependencyManagement>

See the Artifacts list for a list of the available artifacts of this module.

Using the Platform BOM

The Holon Platform provides an overall Maven BOM (Bill of Materials) to easily obtain all the available platform artifacts:

Platform Maven BOM:

<dependencyManagement>
    <dependency>
        <groupId>com.holon-platform</groupId>
        <artifactId>bom</artifactId>
        <version>${platform-version}</version>
        <type>pom</type>
        <scope>import</scope>
    </dependency>
</dependencyManagement>

See the Artifacts list for a list of the available artifacts of this module.

Build from sources

You can build the sources using Maven (version 3.3.x or above is recommended) like this:

mvn clean install

NOTE: The holon-datastore-jdbc-composer artifact requires the Oracle JDBC driver as optional dependency to compile the Oracle SQLDialect class. Since the Oracle JDBC driver is not available from Maven Central, to compile the project you should manually download and install it in your local Maven repository or follow the Oracle Maven repository setup instructions here.

Getting help

• Check the platform documentation or the specific module documentation.

• Ask a question on Stack Overflow. We monitor the holon-platform tag.

• Report an issue.

• A commercial support is available too.

Examples

See the Holon Platform examples repository for a set of example projects.

Contribute

See Contributing to the Holon Platform.

Join the contribute Gitter room for any question and to contact us.

License

All the Holon Platform modules are Open Source software released under the Apache 2.0 license.

Artifacts list

Maven group id: com.holon-platform.jdbc

Artifact id	Description
holon-datastore-jdbc	JDBC Datastore API implementation
holon-datastore-jdbc-composer	The SQL composer engine based on the Java JDBC API
holon-datastore-jdbc-spring	Spring integration using the @EnableJdbcDatastore annotation
holon-datastore-jdbc-spring-boot	Spring Boot integration for JDBC Datastore auto-configuration
holon-starter-jdbc-datastore	Spring Boot starter for the JDBC Datastore auto-configuration
holon-starter-jdbc-datastore-hikaricp	Spring Boot starter for the JDBC Datastore auto-configuration using the HikariCP pooling DataSource
holon-datastore-jdbc-bom	Bill Of Materials
documentation-datastore-jdbc	Documentation