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/
                  HttpApplication.java

Show HttpApplication.java

package example;

import java.util.Objects;

import io.openshift.booster.RouterConsumer;
import io.vertx.core.json.JsonObject;
import io.vertx.rxjava.core.Vertx;
import io.vertx.rxjava.ext.web.Router;
import io.vertx.rxjava.ext.web.RoutingContext;
import rx.Completable;

import static io.vertx.core.http.HttpHeaders.CONTENT_TYPE;

public class HttpApplication extends RouterConsumer {

  public HttpApplication(Vertx vertx) {
    super(vertx);
  }

  protected static final String TEMPLATE = "Hello, %s!";

  @Override
  public void accept(Router router) {
    router.get("/api/greeting").handler(this::greeting);
  }

  @Override
  public Completable start() {
    return Completable.complete();
  }

  private void greeting(RoutingContext rc) {
    String name = Objects.toString(rc.request().getParam("name"), "World");

    JsonObject response = new JsonObject()
      .put("content", String.format(TEMPLATE, name));

    rc.response()
      .putHeader(CONTENT_TYPE.toString(), "application/json; charset=utf-8")
      .end(response.encodePrettily());
  }
}

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