Creator: HOWTO Create a Generator

Generators create the code for Cloud projects. In their simplest form they just have a set of template files that get copied to a project under construction. They can also make changes to already existing files. Among the more advanced features is the creation of Resource Descriptors for deployment on Kubernetes/OpenShift.

So let's go through the steps of what it takes to create a Generator:

1. Choose a name - First we need to choose a name for our new Generator. Let's go with generator-example.
2. Create a folder - All the Generator's files need to live in a folder with the name of the Generator

$ mkdir creator/src/main/resources/META-INF/catalog/generators/generator-example

3. Files - Put any files that you want copied in a subfolder called files. Imagine the following folder structure for a very simple Java application:

generator-example/
   files/
      src/
         main/
            java/
               example/
                  GreetingEndpoint.java
                  Greeting.java

Show code

GreetingEndpoint.java

package example;

import javax.enterprise.context.ApplicationScoped;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;

@Path("/")
@ApplicationScoped
public class GreetingEndpoint {

    private static final String template = "Hello, %s!";

    @GET
    @Path("/greeting")
    @Produces("application/json")
    public Greeting greeting(@QueryParam("name") String name) {
        String suffix = name != null ? name : "World";
        return new Greeting(String.format(template, suffix));
    }
}

Greeting.java

package io.openshift.booster.http;

public class Greeting {
    private final String content;

    public Greeting() {
        this.content = null;
    }
    public Greeting(String content) {
        this.content = content;
    }

    public String getContent() {
        return content;
    }
}

If you think that this doesn't seem to be enough to actually build an application you would be right. We will get to that next.

4. Create metadata - Our Generator also needs an info.json in the root of our folder that contains some important metadata. For our simple example the following would be enough:

{
  "type": "generator",
  "config": {
    "base": "runtime-vertx",
  }
}

The interesting part here is the "base": "runtime-vertx"¹ which tells the Creator that before applying this Generator it should actually first apply the Runtime Generator named runtime-vertx. If you were wondering before why there seemed so little code in our example, it's because we can delegate certain tasks to other Generators. In this case runtime-vertx is a Generator that sets up a project to use the Vert.x framework. We'll talk more about Runtime Generators later on.

5. Register the Generator - Finally we need to register our Generator in the GeneratorInfo list. Just add a item to the end of the list with the exact same name we gave our Generator in the first step. It would look something like this:

enum class GeneratorInfo(val klazz: GeneratorConstructor) {
    `database-crud-dotnet`,
    `database-crud-nodejs`,
    `database-crud-quarkus`,
      .
      .
      .
    `rest-dotnet`,
    `rest-nodejs`,
    `rest-quarkus`,
    `rest-springboot`,
    `rest-thorntail`,
    `rest-vertx`,
    `rest-wildfly`,
    `example-generator`;

That's it! That's all there is to creating a simple Generator.

Let's continue to HOWTO Create a Runtime Generator

Further Reading

• [1]: The Config Section - If you want to know all about the metadata mentioned in point 4
• Create a Custom Generator - What if you need total control over your Generator? Read on.