Maven

Talks about:

Maven projects can use the yosql-tooling-maven plugin to use YoSQL in their builds. The following steps show how a basic setup looks like. In case you are looking for more details, check out the configuration section further down below.

  1. Add the plugin to your pom.xml:
    <build>
        <plugins>
            ...
            <plugin>
                <groupId>wtf.metio.yosql</groupId>
                <artifactId>yosql-tooling-maven</artifactId>
                <version>2021.4.21</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            ...
        </plugins>
    </build>
    
  2. Add .sql files in src/main/yosql and write SQL statements into them. Take a look at the various options to structure your SQL files.
    <project_root>/
    ├── pom.xml
    └── src/
        └── main/
            └── yosql/
                └── domainObject/
                    ├── queryData.sql
                    └── changeYourData.sql
                └── aggregateRoot/
                    ├── findRoot.sql
                    └── addData.sql
    
  3. Execute the yosql:generate goal (or just run mvn generate-sources) to generate the Java code.

Build Helper Plugin

As an optional and final step to complete the setup of YoSQL, you can add the build-helper-maven-plugin to your build in order to mark the outputBaseDirectory as a source directory in your IDE like this:

<build>
    <plugins>
        ...
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>build-helper-maven-plugin</artifactId>
            <executions>
                <execution>
                    <id>add-source</id>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>add-source</goal>
                    </goals>
                    <configuration>
                        <sources>
                            <source>${project.build.directory}/generated-sources/yosql</source>
                        </sources>
                    </configuration>
                </execution>
            </executions>
        </plugin>
        ...
    </plugins>
</build>

Configuration

You can configure how YoSQL operates and how the generated code looks like by using the default Maven configuration mechanism. Take a look at the available configuration options in order to see what can be configured.

<build>
    <plugins>
        ...
        <plugin>
            <groupId>wtf.metio.yosql</groupId>
            <artifactId>yosql-tooling-maven</artifactId>
            <version>2021.4.21</version>
            <configuration>
                <configOption>configValue</configOption>
            </configuration>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        ...
    </plugins>
</build>

The generate goal binds itself automatically to the generate-sources phase. In case you want to run it in another phase, change the above example accordingly.

Multiple Configurations

In some cases it might be preferable to generate some repositories with a specific set of configuration options while using another set for other repositories. There are several ways how this can be accomplished:

  1. Place SQL files in different Maven modules.
  2. Use a single module with multiple execution configurations.
  3. Override configuration for individual SQL statements.

Multiple executions

Make sure that multiple executions do not make use of the same .sql files. Otherwise, the executions will overwrite the generated code of each other. The last execution will win. Share configuration across all executions by using a single top level configuration block.

<build>
    <plugins>
        ...
        <plugin>
            <groupId>wtf.metio.yosql</groupId>
            <artifactId>yosql-tooling-maven</artifactId>
            <version>2021.4.21</version>
            <configuration>
                <repositories>
                    <basePackageName>your.domain.persistence</basePackageName>
                </repositories>
            </configuration>
            <executions>
                <execution>
                    <id>config-a</id>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <files>
                            <inputBaseDirectory>src/main/database/reactive</inputBaseDirectory>
                        </files>
                        <repositories>
                            <generateRxJavaApi>true</generateRxJavaApi>
                        </repositories>
                    </configuration>
                </execution>
                <execution>
                    <id>config-b</id>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <files>
                            <inputBaseDirectory>src/main/database/synchronous</inputBaseDirectory>
                        </files>
                        <repositories>
                            <apiVersion>16</apiVersion>
                        </repositories>
                    </configuration>
                </execution>
            </executions>
        </plugin>
        ...
    </plugins>
</build>

Dev/Prod Split

In case you want generate logging statements while developing, but not have any log statements in production code in order to optimize runtime performance, you can use the following setup:

<properties>
    <loggingApi>SLF4J</loggingApi>
</properties>
<build>
    <plugins>
        ...
        <plugin>
            <groupId>wtf.metio.yosql</groupId>
            <artifactId>yosql-tooling-maven</artifactId>
            <version>2021.4.21</version>
            <configuration>
                <apis>
                    <loggingApi>${loggingApi}</loggingApi>
                </apis>
            </configuration>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        ...
    </plugins>
</build>

This setup requires no additional step during development (which you would have to do a lot), but instead allows you to specify the logging API like this mvn -DloggingApi=NONE in order to change the logging API per invocation of Maven, thus allow you to pass in NONE to disable log statements during release builds.