JDBC

SeedStack JDBC add-on provides support for connection to any relational database through the JDBC API.

Dependency #

<dependency>
    <groupId>org.seedstack.addons.jdbc</groupId>
    <artifactId>jdbc</artifactId>
</dependency>
Show version 
dependencies {
    compile("org.seedstack.addons.jdbc:jdbc:3.0.3")
}

A JDBC driver is also required in the classpath and depends upon the chosen database.

Configuration #

Configuration is done by declaring one or more data-sources:

jdbc:
  # Configured data-sources with the name of the data-source as key
  datasources:
    datasource1:
      # The fully qualified class name of the data-source provider (see below, defaults to 'org.seedstack.jdbc.internal.datasource.PlainDataSourceProvider')
      provider: (Class<? extends DataSourceProvider>)
 
      # The fully qualified class name of the JDBC driver (automatically detected from url if not specified)
      driver: (Class<? extends Driver>)
      
      # The URL of the data-source
      url: (String)
      
      # The properties of the data-source (dependent on the driver) 
      properties:
        property1: value1
      
      # The username used to connect to the data-source (optional) 
      user: (String)
      
      # The password used to connect to the data-source (optional)
      password: (String)
      
      # The fully qualified class name of the exception handler (optional)
      exceptionHandler: (Class<? extends JdbcExceptionHandler>)
      
      # When looking up the datasource through JNDI, the name of the data-source.
      jndiName: (String)
      
      # When looking up the datasource through JNDI, the context to do the lookup (use the default context if not specified)
      jndiContext: (String)      
    
  # The name of the configured data-source to use if nothing is specified in the '@Jdbc' annotation    
  defaultDatasource: (String)

To dump the jdbc configuration options:

mvn -q -Dargs="jdbc" seedstack:config

Examples #

With Hikari pooling

The following YAML configures a data-source named datasource1, using the Hikari connection pool which is a very fast and reliable connection pool.

jdbc:
  datasources:
    datasource1:
      provider: org.seedstack.jdbc.internal.datasource.HikariDataSourceProvider
      url: jdbc:hsqldb:mem:testdb1

Note that the driver class name is automatically detected according to the URL. The Hikari dependency will be needed:

<dependency>
    <groupId>com.zaxxer</groupId>
    <artifactId>HikariCP</artifactId>
    <version>2.5.1</version>
</dependency>
dependencies {
    compile("com.zaxxer:HikariCP:2.5.1")
}

JNDI lookup

When a JNDI name is specified, the provider, url, properties, user and password configuration options are ignored.

jdbc:
  datasources:
    datasource1:
      jndiName: java:comp/env/jdbc/my-datasource

The jndiContext configuration option is needed only when you want to do the lookup in a non-default JNDI context.

Usage #

The following examples show how to get a JDBC connection.

public class MyRepository {
    @Inject
    private Connection connection;
 
    @Transactional
    @Jdbc("datasource1")
    public void updateStuff(int id, String bar){
        try{
            String sql = "INSERT INTO FOO VALUES(?, ?)";
            PreparedStatement statement = connection.prepareStatement(sql);
            statement.setInt(1, id);
            statement.setString(2, bar);
            statement.executeUpdate();
        } catch(SqlException e){
            throw new SomeRuntimeException(e, "message");
        }
    }
}

Any interaction with this connection have to be done inside a transaction. Refer to the transaction documentation for more detail.

Data source providers #

Built-in #

When using a non JNDI data-source, we recommend the use of a connection pool. This is done by specifying a class implementing the DataSourceProvider interface. The built-in providers are:

  • HikariCP with HikariDataSourceProvider
  • Commons DBCP with DbcpDataSourceProvider
  • C3P0 with C3p0DataSourceProvider
  • A test-only, do-nothing, plain data-source provider with PlainDataSourceProvider. Do not use in production.

To use a connection pool, add its dependency on the classpath. Each connection pool must be configured according to its documentation.

Custom #

In the case you want to use another data source provider, you can create your own DataSourceProvider by implementing the DataSourceProvider interface:

public class SomeDataSourceProvider implements DataSourceProvider {
    @Override
    public DataSource provideDataSource(String driverClass, String url, String user, String password, Properties jdbcProperties) {
        // TODO: build the data-source and return it
    }
}

To use it, just specify the fully qualified name of the class in the provider configuration option.


On this page


Edit this page