Griffon GSQL Plugin

1. Introduction

The Gsql plugin enables lightweight access to datasources using Groovy SQL.. This plugin does NOT provide domain classes nor dynamic finders like GORM does.

Griffon version: 2.12.0

2. Usage

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

2.1. Configuration

This plugin relies on the griffon-datasource-plugin. Please follow the instructions to configure this plugin first.

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

griffon.plugins.gsql.GsqlHandler.java

@Nullable
<R> R withSql(@Nonnull GsqlCallback<R> callback)
    throws RuntimeGsqlException;

@Nullable
<R> R withSql(@Nonnull String datasourceName, @Nonnull GsqlCallback<R> callback)
    throws RuntimeGsqlException;

void closeSql();

void closeSql(@Nonnull String datasourceName);

These method are aware of multiple datasources. If no datasourceName is specified when calling them then the default datasource 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: GsqlCallback.

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.gsql.GsqlCallback.java

public interface GsqlCallback<R> {
    R handle(@Nonnull String datasourceName, @Nonnull Sql sql);
}

2.1.1. Bootstrap

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

src/main/groovy/com/acme/SampleGsqlBootstrap.groovy

package com.acme

import griffon.plugins.gsql.GsqlBootstrap
import groovy.sql.Sql

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

@Named("sample")
class SampleGsqlBootstrap implements GsqlBootstrap {
    @Override
    void init(@Nonnull String datasourceName, @Nonnull Sql sql) {
        // operations after first connection to datasource
    }

    @Override
    void destroy(@Nonnull String datasourceName, @Nonnull Sql sql) {
        // operations before disconnecting from the datasource
    }
}

src/main/java/com/acme/ApplicationModule.java

package com.acme;

import griffon.plugins.gsql.GsqlBootstrap;
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(GsqlBootstrap.class)
            .to(SampleGsqlBootstrap.class)
            .asSingleton();
    }
}

2.2. Example

The following is a trivial usage of the GsqlHandler inside a service

com.acme.SampleService.groovy

package com.acme

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

import griffon.plugins.gsql.GsqlHandler

import javax.inject.Inject

@ArtifactProviderFor(GriffonService)
class SampleService {
    @Inject
    private GsqlHandler gsqlHandler

    String getPersonName(final int id) {
         gsqlHandler.withSql(String datasourceName, Sql sql ->
             sql.firstRow("SELECT * FROM people WHERE id = ?", [id])?.name ?: null
         }
    }
}

2.3. Events

The following events will be triggered by GsqlHandler

GsqlConnectStart(String datasourceName, Map<String, Object> config): Triggered before connecting to the datasource.
GsqlConnectEnd(String datasourceName, Map<String, Object> config, Sql sql): Triggered after connecting to the datasource.
GsqlDisconnectStart(String datasourceName, Map<String, Object> config, Sql sql): Triggered before disconnecting from the datasource.
GsqlDisconnectEnd(String datasourceName, Map<String, Object> config): Triggered after disconnecting from the datasource.

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

2.4. AST Transformation

You can apply the @GsqlAware AST transformation on any class. This injects the behavior of GsqlHandler into said class.

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-gsql-groovy-compile-2.1.0.jar, with locations

dsdl/griffon_gsql.dsld
gdsl/griffon_gsql.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-gsql-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-gsql-core:2.1.0'
}

Compile Only

dependencies {
    compileOnly 'org.codehaus.griffon.plugins:griffon-gsql-groovy-compile:2.1.0'
}

3.2. Maven

First configure the griffon-gsql-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-gsql-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-gsql-core</artifactId>
</dependency>

Provided scope

<dependency>
    <groupId>org.codehaus.griffon.plugins</groupId>
    <artifactId>griffon-gsql-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-gsql-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. Gsql

Module name: gsql

Depends on: datasource

bind(GsqlStorage.class)
    .to(DefaultGsqlStorage.class)
    .asSingleton();

bind(GsqlFactory.class)
    .to(DefaultGsqlFactory.class)
    .asSingleton();

bind(GsqlHandler.class)
    .to(DefaultGsqlHandler.class)
    .asSingleton();

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

5. Links

Javadoc

API Sources