Omni

---

[TOC]

Overview

Omni allows a set of files in a Maven module to be managed by another Maven module. When a large number of different modules all require similar boilerplate code, Omni allows that code to be managed in one place.

Installation

Build and run tests:

mvn install

Usage

A "format" is a Java class that defines the location and content of a set of generated files. Generally, it is packaged in its own Maven module, and added as a dependency when calling the Omni Maven Plugin in a another project that needs the generated files.

This guide describes the process of creating a custom format from scratch, and then testing it by importing it into another project. To skip the nuts and bolts and simply get a working example, you can find the resulting code from the tutorial here.

Create a new Maven module

Create a new a directory named customformat, add a pom.xml file to it with this contents:

./customformat/pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <groupId>mycompany.customformat</groupId>
    <artifactId>customformat</artifactId>
    <version>0.1.0-SNAPSHOT</version>
    <name>${project.artifactId}</name>
    
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <java.version>1.8</java.version>
        <maven.compiler.source>${java.version}</maven.compiler.source>
        <maven.compiler.target>${java.version}</maven.compiler.target>
        <omni.version>0.1.0-SNAPSHOT</omni.version>
    </properties>
    
    <dependencies>
        <!-- Dependency on omni core -->
        <dependency>
            <groupId>mattalexx.omni.core</groupId>
            <artifactId>omni-core</artifactId>
            <version>${omni.version}</version>
        </dependency>
    </dependencies>
    
    <build>
        <plugins>
            <!-- Plugin to allow tab completion in templates -->
            <plugin>
                <groupId>mattalexx.omni.tools</groupId>
                <artifactId>omni-template-schema-maven-plugin</artifactId>
                <version>${omni.version}</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>create-template-schema</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Create a format class

Add your format class:

./customformat/src/main/java/mycompany/customformat/CustomFormat.java

package mycompany.customformat;

import mattalexx.omni.core.format.Format;
import mattalexx.omni.core.format.OmniFormat;

@OmniFormat(name = "customformat")
public class CustomFormat extends Format {}

Generate tab completion schema for templates

Now that we've created the format class, run a compile:

cd customformat
mvn compile -e

This will trigger omni-template-schema-maven-plugin to generate classes in ./target/generated-sources/templateschema that provide tab completion when editing templates. Depending on your format class and also which extensions you are using, the variables available to your templates will change. For this reason, these files will regenerate every time you compile your format module.

Prepare the resources directory for templates

Omni uses Freemarker for templating. Freemarker automatically loads a resource file called freemarker_implicit.ftl, so we can use that to configure Freemarker:

./customformat/src/main/resources/freemarker_implicit.ftl

[#ftl]
[#-- @implicitly included --]
[#-- @ftlroot "mycompany/customformat/templates" --]

Define a file to be generated by the format

In this example, we are going to define a file to be created in the root of the project, named file_in_base_directory.txt. To demonstrate template variables, the file should contain the version of Omni used to generate it.

Each file definition includes:

• A Java class under the mycompany.customformat.templates package. This defines the filename, location, and a few other attributes of the file.
• A Freemarker template file, named after the Java class, located in the resources directory, in a mycompany/customformat/templates subdirectory. This defines the contents of the file.

Create the Java class

./customformat/src/main/java/mycompany/customformat/templates/FileInBaseDirectoryTxtFile.java

package mycompany.customformat.templates;

import mattalexx.omni.core.file.AbstractBaseFile;
import mattalexx.omni.core.file.OmniFile;

@OmniFile
public class FileInBaseDirectoryTxtFile extends AbstractBaseFile {}

We are naming the class FileInBaseDirectoryTxtFile because, as a convention, Omni will convert that to file_in_base_directory.txt.

These are the currently available naming conventions:

Parent Class	Java Class Name	Resulting File Name
mattalexx.omni.core.file.AbstractBaseFile	FileNameTxtFile	file_name.txt
mattalexx.omni.extension.javasupport.file.JavaClassFile	FileNameJavaFile	FileName.java

Alternatively, the file name can be manually configured by overriding the getOutputFileBasename() method in your file class.

Create the template file

./customformat/src/main/resources/mycompany/customformat/templates/FileInBaseDirectoryTxtFile.ftl

<#-- @ftlvariable name="" type="templateschema.FileDataSchema" -->
This file was generated using Omni version ${coreVersion}!

Install the new format

Now that we have a format module, let's install it to the local Maven repository so we can refer to it from another project:

cd customformat
mvn install -e

Create a new Maven project to test the format

Create a new directory called customproject next to the existing customformat directory. Add a pom.xml file to it with this contents:

./customproject/pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>mycompany.project</groupId>
    <artifactId>customproject</artifactId>
    <version>0.1.0-SNAPSHOT</version>

    <build>
        <plugins>
            <!-- The Omni Maven Plugin regenerates format files during the compile phase -->
            <plugin>
                <groupId>mattalexx.omni.core</groupId>
                <artifactId>omni-maven-plugin</artifactId>
                <version>0.1.0-SNAPSHOT</version>
                <dependencies>
                    <!-- Add your custom format as a dependency of omni maven plugin -->
                    <dependency>
                        <groupId>mycompany.customformat</groupId>
                        <artifactId>customformat</artifactId>
                        <version>0.1.0-SNAPSHOT</version>
                    </dependency>
                </dependencies>
                <executions>
                    <execution>
                        <goals>
                            <goal>update</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Compile the project

To test your new format, compile the new project.

cd customproject
mvn compile -e

A file named file_in_base_directory.txt should appear in the root of the project, containing the following text:

This file was generated using Omni version 0.1.0-SNAPSHOT!

Further reading

More tutorials and examples can be found here.

TODO

• Allow generation of code outside of Maven, using command line calls
• Integration tests
• Disable update commands for format generator
• Rename java-swagger extension to swagger-java and leverage the new java-support extension
• Rename extensions with -support
• Rename java-support to java-maven-support
• Add source plugin everywhere
• Use findBaseExtensionClass in template generator
• Look for TODOs and add stuff here
• Replace bin/* scripts with something more standard