1. Introduction

The Ormlite plugin enables lightweight access multiple SQL databases. This plugin does NOT provide domain classes nor dynamic finders like GORM does.

Griffon version: 2.12.0

Ormlite version: 5.0

2. Usage

The following sections describe how you may use this plugin in a project.

2.1. Configuration

You must create a configuration file named Ormlite that holds the settings for creating instances of ConnectionSource. This file follows the same standard configuration mechanism as the application’s Config file, which means you can define the configuration using

  • a properties file

  • a Java file

  • a Groovy script

The following example shows the default settings needed to connect the default database taking into account that each environment may connect to a different database.

src/main/resources/Ormlite.groovy
database {
    username = 'sa'
    password = ''
}

environments {
    development {
        database {
            url = 'jdbc:h2:mem:@application.name@-dev'
        }
    }
    test {
        database {
            url = 'jdbc:h2:mem:@application.name@-test'
        }
    }
    production {
        database {
            url = 'jdbc:h2:mem:@application.name@-prod'
        }
    }
}

You may configure multiple named databases (the default factory is aptly named default) as the following snippet shows

src/main/resources/Ormlite.groovy
databases {
    internal {
        username = 'sa'
        password = ''
        url = 'jdbc:h2:mem:@application.name@-internal'
    }
    people {
        username = 'sa'
        password = ''
        url = 'jdbc:h2:mem:@application.name@-people'
    }
}

The following properties are optional

Property Type Default Description

connect_on_startup

boolean

false

Establishes a connection to the database at the beginning of the Startup phase.

jmx

boolean

true

Expose sessions using JMX.

The plugin’s module registers a ConnectionSourceHandler helper class that defines the base contract for accessing a database and issue SQL queries to it. This class has the following methods

griffon.plugins.ormlite.ConnectionSourceHandler.java
@Nullable
<R> R withConnectionSource(@Nonnull ConnectionSourceCallback<R> callback) throws RuntimeSQLException;

@Nullable
<R> R withConnectionSource(@Nonnull String databaseName, @Nonnull ConnectionSourceCallback<R> callback)
    throws RuntimeSQLException;

void closeConnectionSource();

void closeConnectionSource(@Nonnull String databaseName);

These method are aware of multiple databases. If no databaseName is specified when calling them then the default database will be selected. You can inject an instance of this class anywhere it’s needed using @Inject. There is one callback you may use with this method: ConnectionSourceCallback.

This callback is defined using a functional interface approach, which means you can apply lambda expressions if running with JDK8+ or closures if running Groovy.

griffon.plugins.ormlite.ConnectionSourceCallback.java
public interface ConnectionSourceCallback<R> {
    R handle(@Nonnull String databaseName, @Nonnull ConnectionSource connectionSource)
        throws SQLException;
}

2.1.1. Bootstrap

You may execute arbitrary database calls during connection and disconnection from a ConnectionSource. Simply create a class that implements the OrmliteBootstrap interface and register it within a module, for example

src/main/java/com/acme/SampleOrmliteBootstrap.java
package com.acme;

import griffon.plugins.ormlite.OrmliteBootstrap;
import com.j256.ormlite.support.ConnectionSource;

import javax.annotation.Nonnull;
import javax.inject.Named;

@Named("sample")
public class SampleOrmliteBootstrap implements OrmliteBootstrap {
    @Override
    public void init(@Nonnull String databaseName, @Nonnull ConnectionSource connectionSource) {
        // operations after first connection to database
    }

    @Override
    public void destroy(@Nonnull String databaseName, @Nonnull ConnectionSource connectionSource) {
        // operations before disconnecting from the database
    }
}
src/main/java/com/acme/ApplicationModule.java
package com.acme;

import griffon.plugins.ormlite.OrmliteBootstrap;
import griffon.core.injection.Module;
import org.codehaus.griffon.runtime.core.injection.AbstractModule;
import org.kordamp.jipsy.ServiceProviderFor;

@ServiceProviderFor(Module.class)
public class ApplicationModule extends AbstractModule {
    @Override
    protected void doConfigure() {
        bind(OrmliteBootstrap.class)
            .to(SampleOrmliteBootstrap.class)
            .asSingleton();
    }
}

2.2. Example

The following is a trivial usage of the ConnectionSourceHandler inside a Java service

com.acme.SampleService.java
package com.acme;

import griffon.core.artifact.GriffonService;
import griffon.metadata.ArtifactProviderFor;
import org.codehaus.griffon.runtime.core.artifact.AbstractGriffonService;

import griffon.plugins.ormlite.ConnectionSourceHandler;
import griffon.plugins.ormlite.ConnectionSourceCallback;
import griffon.plugins.ormlite.exceptions.RuntimeSQLException;
import com.j256.ormlite.support.ConnectionSource;
import com.j256.ormlite.dao.Dao;
import com.j256.ormlite.dao.DaoManager;

import javax.annotation.Nonnull;
import javax.inject.Inject;

@ArtifactProviderFor(GriffonService.class)
public class SampleService extends AbstractGriffonService {
    @Inject
    private ConnectionSourceHandler connectionSourceHandler;

    public String getPersonName(final int id) {
         return connectionSourceHandler.withConnectionSource(new ConnectionSourceCallback<String>() {
             public String handle(@Nonnull String databaseName, @Nonnull ConnectionSource connectionSource)
                 throws RuntimeSQLException {
                 Dao<Person, Integer> peopleDao = DaoManager.createDao(connectionSource, Person.class);
                 Person person = peopleDao.queryForId(id);
                 return person != null ? person.getName() : null;
         });
    }
}

Here’s the Groovy version of it

com.acme.SampleService.groovy
package com.acme

import griffon.core.artifact.GriffonService
import griffon.metadata.ArtifactProviderFor

import griffon.plugins.ormlite.ConnectionSourceHandler
import com.j256.ormlite.support.ConnectionSource
import com.j256.ormlite.dao.Dao
import com.j256.ormlite.dao.DaoManager

import javax.inject.Inject

@ArtifactProviderFor(GriffonService)
class SampleService {
    @Inject
    private ConnectionSourceHandler connectionSourceHandler

    String getPersonName(int id) {
         connectionSourceHandler.withConnectionSource { String databaseName, ConnectionSource connectionSource ->
             Dao<Person, Integer> peopleDao = DaoManager.createDao(connectionSource, Person)
             peopleDao.queryForId(id)?.name ?: null
         }
    }
}

2.3. Events

The following events will be triggered by ConnectionSourceHandler

OrmliteConnectStart(String databaseName, Map<String, Object> config)

Triggered before connecting to the database.

OrmliteConnectEnd(String databaseName, Map<String, Object> config, ConnectionSource connectionSource)

Triggered after connecting to the database.

OrmliteDisconnectStart(String databaseName, Map<String, Object> config, ConnectionSource connectionSource)

Triggered before disconnecting from the database.

OrmliteDisconnectEnd(String databaseName, Map<String, Object> config)

Triggered after disconnecting from the database.

DataSource events may be triggered during connection and disconnection from a ConnectionSource.

2.4. AST Transformation

You can apply the @ConnectionSourceAware AST transformation on any class. This injects the behavior of ConnectionSourceHandler into said class. The previous Groovy service example can be rewritten as follows

com.acme.SampleService.groovy
package com.acme

import griffon.core.artifact.GriffonService
import griffon.metadata.ArtifactProviderFor
import griffon.transform.ConnectionSourceAware

import com.j256.ormlite.support.ConnectionSource
import com.j256.ormlite.dao.Dao
import com.j256.ormlite.dao.DaoManager

@ConnectionSourceAware
@ArtifactProviderFor(GriffonService)
class SampleService {
    String getPersonName(int id) {
         withConnectionSource { String databaseName, ConnectionSource connectionSource ->
             Dao<Person, Integer> peopleDao = DaoManager.createDao(connectionSource, Person)
             peopleDao.queryForId(id)?.name ?: null
         }
    }
}

2.5. DSL Descriptors

This plugin provides DSL descriptors for Intellij IDEA and Eclipse (provided you have the Groovy Eclipse plugin installed). These descriptors are found inside the griffon-ormlite-groovy-compile-2.1.0.jar, with locations

  • dsdl/griffon_ormlite.dsld

  • gdsl/griffon_ormlite.gdsl

3. Build Configuration

3.1. Gradle

You have two options for configuring this plugin: automatic and manual.

3.1.1. Automatic

As long as the project has the org.codehaus.griffon.griffon plugin applied to it you may include the following snippet in build.gradle

dependencies {
    griffon 'org.codehaus.griffon.plugins:griffon-ormlite-plugin:2.1.0'
}

The griffon plugin will take care of the rest given its configuration.

3.1.2. Manual

You will need to configure any of the following blocks depending on your setup

dependencies {
    compile 'org.codehaus.griffon.plugins:griffon-ormlite-core:2.1.0'
}
Compile Only
dependencies {
    compileOnly 'org.codehaus.griffon.plugins:griffon-ormlite-groovy-compile:2.1.0'
}

3.2. Maven

First configure the griffon-ormlite-plugin BOM in your POM file, by placing the following snippet before the <build> element

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.codehaus.griffon.plugins</groupId>
            <artifactId>griffon-ormlite-plugin</artifactId>
            <version>2.1.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Next configure dependencies as required by your particular setup

<dependency>
    <groupId>org.codehaus.griffon.plugins</groupId>
    <artifactId>griffon-ormlite-core</artifactId>
</dependency>
Provided scope
<dependency>
    <groupId>org.codehaus.griffon.plugins</groupId>
    <artifactId>griffon-ormlite-groovy-compile</artifactId>
</dependency>

Don’t forget to configure all -compile dependencies with the maven-surefire-plugin, like so

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <classpathDependencyExcludes>
            <classpathDependencyExclude>
                org.codehaus.griffon:griffon-ormlite-groovy-compile
            </classpathDependencyExclude>
        </classpathDependencyExcludes>
    </configuration>
</plugin>

4. Modules

The following sections display all bindings per module. Use this information to successfully override a binding on your own modules or to troubleshoot a module binding if the wrong type has been applied by the Griffon runtime.

4.1. Ormlite

Module name: ormlite

bind(ResourceBundle.class)
    .withClassifier(named("ormlite"))
    .toProvider(new ResourceBundleProvider("Ormlite"))
    .asSingleton();

bind(Configuration.class)
    .withClassifier(named("ormlite"))
    .to(DefaultOrmliteConfiguration.class)
    .asSingleton();

bind(ConnectionSourceStorage.class)
    .to(DefaultConnectionSourceStorage.class)
    .asSingleton();

bind(ConnectionSourceFactory.class)
    .to(DefaultConnectionSourceFactory.class)
    .asSingleton();

bind(ConnectionSourceHandler.class)
    .to(DefaultConnectionSourceHandler.class)
    .asSingleton();

bind(GriffonAddon.class)
    .to(OrmliteAddon.class)
    .asSingleton();

5. Links

Javadoc

API Sources