DEV Community: Yassine Benabbas

JBang, the missing scripting tool of the Java ecosystem

Yassine Benabbas — Fri, 03 Jan 2025 19:19:10 +0000

The Java ecosystem has already two powerful project management tools, namely Maven and Gradle, yet it lacked a simple and powerful scripting tool.
This is where JBang comes in.
It is a minimalist but powerful Java, Kotlin and Groovy file launcher.
In fact, it allows you to run code as easily as you would run a script.
It also provides many other features such as dependency management, templates, and an App Store.
Let's explore JBang and its features in this post.

Setup

The jbang command-line can be installed on Windows, Linux, and macOS using different methods which are well documented here.
We can verify the installation by running jbang --version.

In addition to that, it's preferable to install the accompanying IDE extension for our favorite IDE.
The supported IDE extensions are listed here.

JBang does not depend on a JDK to JRE but a JDK is required to run scripts that use Java.
You can install one with JBang by running jbang jdk install 23 which will install the JDK 23.

We are now ready to write our first scripts.

First script

Let's create a simple script that prints "Hello, World!" to the console.

> jbang init helloworld.java

This will create a file named helloworld.java that can be run with jbang helloworld.java.

> jbang helloworld.java
Hello world

When you open the file, you will see that it is a plain Java file with a main method and a particular first line.

///usr/bin/env jbang "$0" "$@" ; exit $?
import static java.lang.System.*;

public class helloworld {
    public static void main(String... args) {
        out.println("Hello world");
    }
}

As we will see, JBang script are made up of three parts: the shebang, optional properties and the script itself.
We'll use some properties the second part in the next sections but let's focus on the first part.

This part ///usr/bin/env jbang "$0" "$@" ; exit $? tells the system to use JBang to run the script.
It is called a shebang in the Unix ecosystem and is used to specify the interpreter for the script.
We can illustrate this on a Unix System (macOS, Linux) by running chmod +x helloworld.java to make the script executable and then running ./helloworld.java.

> chmod +x helloworld.java
> ./helloworld.java
Hello world

We can now develop our script as we would with any Java file.
Once it is ready to be published, we can export it in different formats as follows:

A jar file: jbang export portable helloworld.java. If your script uses dependencies, the next commands are more recommended.
A fatjar: which contains all the dependencies: jbang export fatjar helloworld.java. This method still requires to install a JDK / JRE on the target machine. If you don't want to that, the next commands are more recommended.
A jlink binary that encompases a JDK: jbang export jlink helloworld.java. The binary to run is either helloworld-jlink/bin/helloworld on Unix or helloworld-jlink/bin/helloworld.bat on Windows.
A native imgae: jbang export native helloworld.java. This requires a GraalVM installation.

The script can also be exported as a mavenrepo with: jbang export mavenrepo helloworld.java

JDK management

As seen in a previous chapter, JBang can install JDKs on your machine.
You can list the installed JDKs with jbang jdk list, list available ones to install with jbang jdk list --available --show-details, install a new one with jbang jdk install [version]. Jbang also supports the use of SDKMAN to manage JDKs on supported systems.

Furthermore, it is possible to specify a JDK version in a scripts.
This is done by adding the following line to the script properties: //JAVA [version] if we want an exact version or //JAVA [version]+ if we want at least a specific version.
In that case JBang will automatically install the required JDK version and use it only for that script without changing the default JDK of the system.

For example, the following script uses Java 25 and some preview features.

/// usr/bin/env jbang "$0" "$@" ; exit $?
//JAVA 25
//COMPILE_OPTIONS --enable-preview -source 25
//RUNTIME_OPTIONS --enable-preview

import java.util.concurrent.Callable;
import java.util.concurrent.StructuredTaskScope;

import static java.lang.System.*;

void main(String... args) {
  out.println("Hello Java 25");
  Callable<String> task1 = () -> {
    out.println("Task 1" + Thread.currentThread());
    return "Task 1";
  };

  Callable<Integer> task2 = () -> {
    out.println("Task 2" + Thread.currentThread());
    return 2;
  };

  try (
    var scope = new StructuredTaskScope<Object>()) {
    StructuredTaskScope.Subtask<String> subtask1 = scope.fork(task1);
    StructuredTaskScope.Subtask<Integer> subtask2 = scope.fork(task2);
    scope.join();
  } catch (Exception e) {
    e.printStackTrace();
  }
}

Scripts without a "Main" class

Since script tend to be lightweight, it would be preferable to write them without a class and a main method.
Fortunately, Java has a feature called implicit declared classes and instance main methods (which is still in preview in Java 23).
This feature allows to write java programs and JBang script without a class and a static main method.

The following script will be compiled and executed without any problem.

///usr/bin/env jbang "$0" "$@" ; exit $?
//JAVA 23+
//COMPILE_OPTIONS --enable-preview -source 23
//RUNTIME_OPTIONS --enable-preview

void main(String... args) {
  System.out.println("Hello World");
}

This is made possible by adding the following properties to the script.

//JAVA 23+
//COMPILE_OPTIONS --enable-preview -source 23
//RUNTIME_OPTIONS --enable-preview

The first line, //JAVA 23+, tells JBang to use Java 23 or later.
The second and third lines, //COMPILE_OPTIONS --enable-preview -source 23 and //RUNTIME_OPTIONS --enable-preview, enable preview features for compilation and runtime, respectively.

Once the feature become stable, we can remove the 3 lines and the script will still work. Neat!

Dependencies

JBang supports adding dependencies to scripts in the form of Gradle style dependencies by adding a //DEPS atrefact-id:atrefact-name:version line for each dependency.
For example, to use the jfiglet library, we can add the following line to the script: //DEPS com.github.lalyos:jfiglet:0.0.8.

///usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS com.github.lalyos:jfiglet:0.0.9

import com.github.lalyos.jfiglet.FigletFont;

public class DependenciesDemo {
    public static void main(String... args) throws Exception {
        System.out.println(FigletFont.convertOneLine("JBang is amazing"));
    }
}

Catalogs

Catalogs in JBang allow to organize and share scripts and templates efficiently.
This feature is particularly useful for teams or communities that want to share a collection of scripts for common tasks or workflows.
It is also useful for teachers who want to distribute starter codes or show results of exercises without providing the source code.

A catalog is a JSON file named jbang-catalog.json that contains two groups of items: aliases and templates.
Aliases allow to run scripts from a catalog using a simple command, while templates provide a starting point for new scripts.
Catalogs can be remote or local and it is possible to add and use as many local or remote repositories as needed.
It is interesting to point out that JBang creates, during its setup, a local catalog with some aliases and templates out of the box.

JBang looks for local catalogs in these directories in the following order (source JBang docs):

Current directory, ./jbang-catalog.json
In ./.jbang/jbang-catalog.json
In the parent directory, ../jbang-catalog.json
In the parent’s .jbang directory, ../.jbang/jbang-catalog.json
And repeating steps 3 and 4 recursively upwards to the root of the file system
As the last step it will look in $HOME/.jbang/jbang-catalog.json

JBang will look for remote the catalogs in many open source repositories like GitHub, GitLab, Bitbucket, and others.
I'll use GitHub as an example in this post.
To create a remote catalog, you need to add jbang-catalog.json to the root folder of your repository.
The catalog is then referred to by account/repository_name.
If your repository is named jbang-catalog, then you can refer to it by account.
So, for example, if my GitHub account is named yostane and I have a repository named cours-java that contains a catalog which a file named jbang-catalog.json, I can refer to that catalog by yostane/cours-java. Furthermore, if I have a jbang-catalog.json in a repository named jbang-catalog then I can refer to it by yostane/jbang-catalog or simply yostane.

  {
    "catalogs": {},
    "aliases": {
      // aliases
    },
    "templates": {
      // templates
    }
  }

The following chapters will show how to use aliases and templates from a catalog.

Aliases

Aliases in JBang allow to run scripts from a catalog.
The full syntax is jbang alias@account/repository [args] and jbang alias [args] for respectively a remote and local alias.

Aliases can be defined in the aliases section of the catalog file using the following format:

{
  "aliases": [
    {
      "name": "alias-name",
      "description": "Some description",
      "location": "path-to-script.java or .kt or .groovy"
    },
    // More aliases ...
  ]
}

Here is the catalog I used during my session at DevoxxMA 2024.

{
    "catalogs": {},
    "aliases": {
      "palcli": {
        "script-ref": "tutorials/devoxxma2024-jbang/paltools/palcli.java",
        "description": "Palindrome tester CLI"
      },
    "palqrest": {
        "script-ref": "tutorials/devoxxma2024-jbang/paltools/palqrest.java",
        "description": "Palindrome tester Quarkus Rest API"
      },
    "hellojfx": {
        "script-ref": "tutorials/devoxxma2024-jbang/javafx/hellojfx.java",
        "description": "Basic JavaFX window that shows Java and JavaFx versions"
      }
    }
}

You can run these aliases with the following commands:

jbang palcli@yostane/cours-java madam
jbang palqrest@yostane/cours-java
jbang hellojfx@yostane/cours-java

The official JBang GitHub account provides a catalog with many aliases and templates.
Let's run some of them:

jbang httpd@jbangdev run a local webserver.
jbang gavsearch@jbangdev [arg] search for [arg] on search.maven.org.

Templates

Templates, which are pre-defined scripts that can be used as a starting point for new scripts.
They are defined in the templates section of the catalog file using the following format:

{
  "catalogs": {},
  "aliases": {
    //...
  },
  "templates": {
    "template-name": {
      "file-refs": {
        "filename.java": "path-to-template-file.java, .kt, .groovy or .qute"
      },
      "description": "Some description"
    },
    // More templates ...
  }
}

When a template is used, JBang creates copies of all the files int the file-refs property.
When a file-ref contains {basename}, JBang replaces it with the name of the script being created.
When a file-ref uses the .qute extension, JBang uses the Qute templating engine

Here are some examples of some templates available out of the box:

A CLI script that uses picocli: jbang init -t cli hellocli.java
A Quarkus single file REST API: jbang init -t qrest helloqrest.java

We can also use templates from the internet shared by the community.
For example, this command creates a JUnit unit test file: jbang init -t junit@jbangdev file_to_test.java.
From the command we can locate the jbang-catalog.json that defined the tempalte in the jbangdev/jbang-catalog repository.

{
  "catalogs": {},
  "aliases": {
    //...
  },
  "templates": {
    //...
    "junit": {
      "file-refs": {
        "{basename}Test.java": "templates/junit.java.qute"
      },
      "description": "Basic template for JUnit tests"
    }
  }
}

App Store

The JBang App Store is a web app that allows to browse aliases of indexed catalogs.
It provides a convenient way to discover and use various tools and utilities without the need for complex setup or installation processes.
For example, when we search for yostane, we should be able to find the different aliases that I have defined in my different catalogs.
The following image shows the result of the search.

Here are some interesting and funny scripts that I found by browsing on the the App Store:

Cowsay. Here are some examples of running the script:
- jbang cowsay@ricksbrown/cowsay MOO!
- jbang cowsay@ricksbrown/cowsay -f dragon "I'm Veldora Tempest!"
Find substring like grep: jbang grep@a-services "hello" .
Create PDF from images: images2pdf@a-services. The following commands will create a PDF file from two images:

  wget -O img1.png "https://blog.worldline.tech/images/post/modulith/modulith-thumb.png"
  wget -O img2.png "https://blog.worldline.tech/images/post/ryuk/testcontainers-396x120.png"
  # Create a file that contains the paths to the images. This file is required by the script.
  echo "img1.png" > ./files.txt
  echo "img2.png" >> ./files.txt
  jbang images2pdf@a-services files.txt

When you publish a catalog, it will very probably appear after the next indexing of the JBang AppStore.
It is a scheduled GitHub action defined here.

Some examples with notable frameowrks

With JBang, we can create single file applications that use popular frameworks and libraries.
Some examples include Quarkus, picolcli, and JavaFX.
Let's explore some example in the following sections.

JavaFX (openjfx)

JavaFX is a desktop and UI framework.
Its official website is openjfx.io and is also supported by Gluon which provides additional UI components and brings mobile app support to JavaFX.
JBang supports this frameowrk and can be used to create signle file JavaFX applications.

Here are some examples JavaFX apps created with JBang:

Basic window
More beautiful example jbang https://gist.github.com/FDelporte/c69a02c57acc892b4c996a9779d4f830
A template jbang init -t javafx@yostane hellojfx

Quarkus

Quarkus is a Java framework that is optimized for Kubernetes and serverless environments.
It provides a fast boot time and low memory consumption, making it ideal for cloud-native applications.

Thanks to JBang, we can create single-file Quarkus applications that leverage the power of this framework.
The following example shows a rest API that tests if a string is a palindrome. It has JSON parsing, logging and provides an OpenAPI and Swagger documentation.

///usr/bin/env jbang "$0" "$@" ; exit $?
//JAVA 17+
// Update the Quarkus version to what you want here or run jbang with
// `-Dquarkus.version=<version>` to override it.
//DEPS io.quarkus:quarkus-bom:${quarkus.version:3.15.1}@pom
//DEPS io.quarkus:quarkus-resteasy
//DEPS io.quarkus:quarkus-resteasy-jsonb
//DEPS io.quarkus:quarkus-smallrye-openapi
//DEPS io.quarkus:quarkus-swagger-ui

//JAVAC_OPTIONS -parameters
//JAVA_OPTIONS -Djava.util.logging.manager=org.jboss.logmanager.LogManager

//SOURCES PalindromeService.java

//Q:CONFIG quarkus.banner.enabled=false
//Q:CONFIG quarkus.swagger-ui.always-include=true

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.MediaType;

import java.util.Map;

@Path("/palindrome")
@ApplicationScoped
public class palqrest {
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Map<String, String> isPalidrome(@QueryParam("input") String input) {
        return Map.of("result",
                PalindromeService.isPalindrome(input) ? "Palindrome" : "Not Palindrome");
    }
}

We may notice a //SOURCES PalindromeService.java line in the script.
It tells JBang to look for a file named PalindromeService.java in the same directory as the script.
This means that JBang supports multi-file scripts.

You can run the server with jbang palqrest@yostane/cours-java and call the endpoint with curl http://localhost:8080/palindrome?input=madam.

jbang palqrest@yostane/cours-java
# In another terminal
curl http://localhost:8080/palindrome?input=madam
# {"result":"Palindrome"}

Other languages

JBang supports running Java, Kotlin, JShell and Groovy code.
It can even run Java code from markdown files.
Here are some examples of how to use JBang with different languages:

Kotlin: You can initialize a Kotlin script with jbang init -t hello.kt filename.kt. Please note that this is different from the official .main.kts Kotlin scripts. In fact, Kotlin scripts created by JBang can benefit from the catalog and App Store features. Here is an example of a Kotlin script created with JBang.

  ///usr/bin/env jbang "$0" "$@" ; exit $?
  //DEPS org.fusesource.jansi:jansi:2.4.1

  import org.fusesource.jansi.Ansi.*
  import org.fusesource.jansi.Ansi.Color.*
  import org.fusesource.jansi.AnsiConsole

  public fun main() {
      AnsiConsole.systemInstall()
      println(
          ansi().eraseScreen().fg(RED).a("Hello").fg(GREEN).a(" DevoxxMA ").fg(RED).a("2024").reset()
      )
      println(ansi().eraseScreen().render("@|red JBang|@ @|green 💖 Kotlin|@"))
  }

Interesting fact: the idea of JBang came from kscript which is targeted to the Kotlin ecosystem.
Kotlin already has native scripting support (with .main.kts scripts) but seems to lack the catalog, template, and App Store features.
- Groovy: Initialize a Groovy script with jbang init -t hello.groovy filename.groovy. Here is an example of a Groovy script created with JBang.

  ///usr/bin/env jbang "$0" "$@" ; exit $?
  println("Hello Groovy World");

JShell: JBang supports JShell scripts with .jsh or .jshell extensions and inline scripts using jbang -c 'System.out.println("Inline Java ☕ yay!")'. Here is an example of a JShell script created with JBang.

  ///usr/bin/env jbang "$0" "$@" ; exit $?
  //DEPS com.github.lalyos:jfiglet:0.0.9

  import com.github.lalyos.jfiglet.FigletFont;

  System.out.println("hello from jshell");
  System.out.println(FigletFont.convertOneLine("DevoxxMA"));

Markdown with Java and JShell code blocks: You can run Java and JShell code blocks directly from a markdown file using jbang my_markdown.md.

  # jbang runs markdown

  Jbang can execute code blocks.

  ```

java
  class Demo {
      void test() {
          System.out.println("I am a print in a markdown!");
      }
  }


  ```

  ```

jshelllanguage
  new Demo().test();


  ```

  ```

jsh
  //DEPS com.github.lalyos:jfiglet:0.0.9
  import com.github.lalyos.jfiglet.FigletFont;

  System.out.println(FigletFont.convertOneLine(
        "Hello " + ((args.length>0)?args[0]:"jbang")));


  ```

  ```

java
  if(args.length==0){
      System.out.

  println("You have no arguments!");
  }else{
      System.out.

  printf("You have %s arguments! First is %s",args.length, args[0]);
  }


  ```

  ```

kt
  fun main() {
      print("We love Kotlin")
  }


  ```

  ```

kotlin
  println("We love Kotlin")


  ```

  ```

groovy
  println("We love Kotlin")


  ```
  ```

`

## Other and experimental features

In this section, we will delve into some additional and experimental features of JBang that can further enhance your scripting experience.
These features include file configuration, caching, the JBang wrapper, and even generating scripts using OpenAI.
Let's briefly view some of them next.

### File Configuration

JBang allows you to configure various settings through a configuration file.
This can be particularly useful for setting default options, managing dependencies, and customizing the behavior of your scripts.
You can learn more about file configuration [here](https://www.jbang.dev/documentation/guide/latest/config.html).

### Caching

To improve performance and reduce redundant downloads, JBang supports caching of dependencies and other resources.
For certain situations, we may want to clear the cache with `jbang cache clear` and ignore the cache when fetching a catalog with `--fresh` argument.
For example, `jbang --fresh palqrest@yostane/cours-java` will ignore the cache and get the latest version of the alias.
Documentation on caching can be found [here](https://www.jbang.dev/documentation/guide/latest/caching.html).

### JBang Wrapper

The JBang wrapper is a convenient tool that allows you to bundle JBang with your project.
This ensures that anyone who clones your repository can run your scripts without needing to install JBang separately.
More details on the JBang wrapper are available [here](https://www.jbang.dev/documentation/guide/latest/cli/jbang-wrapper.html).

### OpenAI Script Generation (Experimental)

JBang has the ability to generate scripts using OpenAI.
By providing a description of what you want your script to do, JBang can leverage OpenAI's capabilities to create a script for you.
This feature is still in preview and requires an OpenAI API key (I personally could not get an OpenAPI key so I couldn't test by myself).

For example, you can generate a script to count the number of people in an image using OpenCV with the following command:

```sh
jbang --preview --verbose init ImageProcessor.java "Write a Java program that counts the number of people in an image with OpenCV"
```

As a side note, if we want to prompt from the terminal, there are already many stable tools such as [mods](https://github.com/charmbracelet/mods).

## Conclusion

JBang is a highly versatile tool that brings powerful scripting capabilities to the Java ecosystem.
It is particularly useful for single-file projects, allowing developers to quickly and easily run Java, Kotlin, and Groovy scripts.
It can be applied to a wide range of use cases: Rest APIs, GUI apps, general scripting, etc.
The tool's features, such as templating, the App Store, and catalogs, enhance its utility by facilitating sharing and collaboration among developers.

Whether it is for teaching or for scripting, JBang is a valuable addition to the Java developer's toolkit.

## Credits and resources

- [jbang](https://jbang.dev)
- [jfiglet](https://github.com/lalyos/jfiglet)
- [fusesource/jansi](https://github.com/fusesource/jansi)
- [Java 23 Implicitly Declared Classes and Instance Main Methods](https://docs.oracle.com/en/java/javase/23/language/implicitly-declared-classes-and-instance-main-methods.html)
- [baeldung.com/jbang](https://www.baeldung.com/jbang-guide)
- [JBang OpenAI example](https://www.infoq.com/news/2023/06/jbang-107/)

A tour of CLI tools for installing Java and creating projects

Yassine Benabbas — Sat, 01 Jun 2024 17:02:27 +0000

Java Developers have at their disposal many tools and libraries that make their DX (Developer eXperience) easier and more fun.

Being a terminal lover, let me share with you some CLI (Command Line Interface) tools that will make installing the JDK and bootstrapping projects a breeze.
You can even complement your existing tooling with the ones that we'll see here.

💡 This post is also for you if you use Kotlin for the JVM.

JDK version management

Let's start with the first thing that we need to do when we want to start a Java project: installing the JDK.

With Java releasing a new version every 6 months and with all the available JDK distributions, having a proper JDK version management is a must.
Thus, I strongly discourage to install a JDK using an installer.
In addition to that, some JDKs have license costs in production environments and we need to be careful about that.
So, I suggest you don't install a JDK from search engines without proper prior knowledge, such as the one offered by whichjdk.com.

Instead, we can use an intermediary tool that will allow to install different JDKs and change the default one whenever we want.
This kind of tool is called a Java version manager.
I recommend these two tools depending on your OS.

On Windows: scoop is a package manager which supports Java version management. It provides a Java wiki with detailed instructions.
On Linux and macOS: SDKMAN! is a SDK manager specialized in the Java ecosystem. Instructions on how to manage JDKs is provided here.

In addition to listing and installing JDKs with different versions and providers, these tools can change the current active JDK with a single command (by automatically updating JAVA_HOME and PATH environment variables).
Furthermore, we can install with a single command other Java related tools such as Maven, Gradle, Kotlin, etc.

For example, to list the available JDKs using scoop, we run scoop search jdk to get an output similar the following one:

...
temurin17-nightly-jdk     17.0.10-6.0.202312241232  java
temurin18-jdk             18.0.2-101                java
temurin18-nightly-jdk     18.0.2-101.0.202210032342 java
temurin19-jdk             19.0.2-7                  java
temurin19-nightly-jdk     19.0.2-7.0.202302250348   java
temurin20-jdk             20.0.2-9                  java
temurin21-jdk             21.0.1-12.1               java
temurin8-jdk              8.0.392-8                 java
temurin8-nightly-jdk      8.0.402-5.0.202312251854  java
zulu-jdk                  21.30.15                  java
zulu10-jdk                10.3.5                    java
zulu11-jdk                11.68.17                  java
zulu12-jdk                12.3.11                   java
zulu13-jdk                13.54.17                  java
zulu14-jdk                14.29.23                  java
...

As you can see, that there are plenty of choices.
My general recommendation is to use the latest LTS release and a distribution which provides the best balance of features (license, community, performance, security updates, etc.).
In this regard, I use either Zulu JDK or Temurin JDK.
This seems to be in-line with whichjdk.com which recommends to use Adoptium Eclipse Temurin 21 (which superseeds adoptopenjdk) (Please note that Java 21 is the current LTS at the time of writing).

So let's install Temurin with scoop install temurin21-jdk if you are on Windows or with sdk install java 21.0.1-tem if you are on Linux, macOS or WSL.
Once done, you can immediately check that that the setup succeeded with a java --version.

Projects managers

In this section, I'll show three tools for creating and managing Java projects from the command line.

JBang

JBang is one of the simplest and easiest ones to get started with Java.
In fact, it allows to create self-contained source-only projects, where build configuration files are not needed.
This means that a JBang project can fit in a single Java (or Kotlin) file.

This tool also provides an AppStore feature which allows to run Java projects shared by the community very easily.
⚠ Of course, every script must be verified before running it on your machine.

JBang can be installed on Windows using scoop with this command: scoop install jbang, or on macOS and Linux using SDKMAN with this command: sdk install jbang.

After that, we can create a basic project with jbang init hello.java. We can run it with jbang run hello.java (on Linux and macOS, we first need to run chmod +x hello.java to make the java file executable).

JBang provides many other templates that we can list with jbang template list.
Here is the output of this command at the time of writing this post.

agent = Agent template
cli = CLI template
githubbot@quarkusio = Example of making a github app
gpt = Template using ChatGPT (requires --preview and OPENAI_API_KEY)
gpt.groovy = Template using ChatGPT for groovy (requires --preview and OPENAI_API_KEY)
gpt.kt = Template using ChatGPT for kotlin (requires --preview and OPENAI_API_KEY)
hello = Basic Hello World template
hello.groovy = Basic groovy Hello World template
hello.kt = Basic kotlin Hello World template
qcli = Quarkus CLI template
qmetrics = Quarkus Metrics template
qrest = Quarkus REST template
readme.md = Basic markdown readme template

The cli template create a starter project with picocli which is a great library for creating console apps that consume command-line arguments.

Another way to create projects is to pass a prompt that generates starter code thanks to OpenAI's (the company behind chatGPT).
This feature is still experimental but it looks promising as shown in this blog post.

I personally used JBang to create Java projects for solving some advent of code challenges and it was really useful.
The JBang community was also reactive to my feedback and fixed my issues very quickly.
Big thanks to them!

To summarize, JBang is particularly well suited for education, for small projects or to try tools or templates available in its AppStore (as long as we make sure they are safe beforehand).

Gradle

Gradle is project management tool used by Android developers. It is also and also by Java developers as an alternative to Maven.
Even though it seems to be mostly used by Kotlin or Java devs, Gradle is language agnostic and supports other languages which are at the time of writing: Groovy, Scala, C++ and Swift.

In addition to project management, Gradle provides a gradle init command which bootstraps a blank or a hello world project.
Let's try this out and create a Java project from scratch.
The following snippet show a terminal interaction with the introduced command.

➜ gradle init

Select type of project to generate:
  1: basic
  2: application
  3: library
  4: Gradle plugin
Enter selection (default: basic) [1..4] 2 # Choose 2 for a 'Hello world' project

Select implementation language:
  1: C++
  2: Groovy
  3: Java
  4: Kotlin
  5: Scala
  6: Swift
Enter selection (default: Java) [1..6] 3 # Choose 3 for Java

Generate multiple subprojects for application? (default: no) [yes, no]

Select build script DSL:
  1: Kotlin
  2: Groovy
Enter selection (default: Kotlin) [1..2] # Leave default to use Kotlin script for the build file

Select test framework:
  1: JUnit 4
  2: TestNG
  3: Spock
  4: JUnit Jupiter
Enter selection (default: JUnit Jupiter) [1..4] # Leave default to use JUnit Jupiter

Project name (default: gradle-java): # Leave default to use the folder name as the project name

Source package (default: gradle.java): # Leave default to use the suggested package name

Enter target version of Java (min. 7) (default: 17): # Leave default to use your current Java version

Generate build using new APIs and behavior (some features may change in the next minor release)? (default: no) [yes, no]


> Task :init
To learn more about Gradle by exploring our Samples at https://docs.gradle.org/8.5/samples/sample_building_java_applications.html

BUILD SUCCESSFUL in 31s
2 actionable tasks: 2 executed

Once the project is generated, we can immediately open it with gradle run or test it with gradle test.

The project structure is as follows (output of PowerShell's tree /F command):

│   .gitattributes
│   .gitignore
│   gradlew
│   gradlew.bat
│   settings.gradle.kts
│
├───app
│   │   build.gradle.kts
│   │
│   └───src
│       ├───main
│       │   ├───java
│       │   │   └───gradle
│       │   │       └───java
│       │   │               App.java
│       │   │
│       │   └───resources
│       └───test
│           ├───java
│           │   └───gradle
│           │       └───java
│           │               AppTest.java
│           │
│           └───resources
└───gradle
    │   libs.versions.toml
    │
    └───wrapper
            gradle-wrapper.jar
            gradle-wrapper.properties

We can verify this follows the usual gradle project structure.
Even a test case is provided out of the box!

Maven arcehtype:generate

Maven is a Java project management which was predominant before Gradle and JBang appeared. Indeed, it appeared where the most used tool was ant

Among its features, the mvn arcehtype:generate command allows to generate various types of projects from templates.
The only requirement is to run the command with the correct template information: its archetypeGroupId, archetypeArtifactId and archetypeVersion.

Locally installed templates can be listed by running mvn archetype:generate and many more can be found by searching on the internet.
Calling mvn archetype:generate on my computer listed more than 3000 projects, which can be a bit overwhelming for beginners.

We must also be careful because the quantity does not necessarily mean quality. For example, to create a simple Java project, we run this command that we find in the official Maven website:

mvn archetype:generate -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4
# in powershell, prefix the - with a `
mvn archetype:generate `-DarchetypeGroupId=org.apache.maven.archetypes `-DarchetypeArtifactId=maven-archetype-quickstart `-DarchetypeVersion=1.4

When I opened the generated project, I found out in the pom file (as shown in the below snippet) that it is using Java 7 while the current LTS at the time of writing is Java 21.

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.7</maven.compiler.source>
    <maven.compiler.target>1.7</maven.compiler.target>
</properties>

I have also encountered this issue with other archetypes but it is surprising that the one provided by the official website is so much outdated.

JBang vs Gradle vs Maven

As you may have guessed by reading the previous section, my least favorite way of creating a Java project in the command line is Maven's archetype:generate for these reasons:

Long commands
We need to look for them in the internet or in a long list of templates
We may find outdated templates, even from the official website

Maven being out of the way, let's continue by comparing gradle init and JBang.
They both support languages other than Java, namely Groovy and Kotlin, but JBang's support for those is still experimental and gradle init supports more languages (such as C++ and Swift).

JBang is adapted for small Java projects or for ones that have a template.
For example, and as far as I know, only JBang provides a picocli starter.
gradle init is a better choice for large projects that want to start from scratch and want to have a folder structure.
However, if you want to create a project with a specific Java framework, you may need to use the tools provided by the framework:

Spring boot: spring initializr or Spring Boot CLI
Quarkus: code.quarkus.io or Quarkus CLI
JEE: Open Liberty starter, Eclipse starter for Jakarta EE, Wildlfy quickstart projects on GitHub

To summarize, we have many tools at our disposal and all provide great features.

Let's explore further the tools we just introduced.

Spring Boot CLI and Quarkus CLI

Two of the most famous Java server frameworks, namely Spring and Quarkus, provide CLIs for improving DX.

Spring Boot CLI generates new Spring boot projects and encodes passwords (for use with Spring Security).
The project generation feature is the CLI counterpart of the web UI start.spring.io.
Below are some examples of using the Spring Boot CLI:

# Generate a zip file that contains a Kotlin project which uses Gradle Kotlin build file and inclids the web-services and postgresql dependencies
spring init --build gradle -l kotlin -t gradle-project-kotlin -d web-services,postgresql
# Generate a Java 21 project that uses maven and includes the web-services and postgresql dependencies
spring init -x --build maven -j 21 -a sb-cli-demo -g org.sb.test -d web-services,postgresql --description "project created with Spring Boot CLI"
# List all possible options to initialize a project
spring help init

Spring Boot CLI features are very basic.
Some features that I miss are upgrading spring version and adding new dependencies.
Maybe they'll be implemented in the future.
But as it is right now, I don't need to keep it installed on my computer.

Quarkus CLI provides much more features than Spring Boot CLI.
Not only it allows to create new Quarkus projects, but it's also able to manage other life cycle tasks: running dev mode, building for production, upgrading versions, etc.
Thus, it can be used instead of Gradle or Maven for most tasks.
This makes the DX with Quarkus much more universal and agnostic of the underlying build tool (Gradle or Maven).

Here are some sample uses of quarkus cli:

# List available quarkus extension
quarkus ext ls
# Create a Quarkus rest API wirh Gradle build system
quarkus create app --extension="rest" --gradle-kotlin-dsl --wrapper
cd .\code-with-quarkus\
# Run the app in dev mode
./gradlew quarkusDev

# Create a Quarkus CLI app (with Picocli) that uses Kotlin and Gradle with Kotlin DSL
quarkus create cli --name="quarkus-cli-demo" --kotlin --gradle-kotlin-dsl --wrapper
# Open the folder
cd code-with-quarkus
# run the app with gradle
./gradlew quarkusRun -Dquarkus.args='-c -w --val 1' --console=plain
# Run the app with quarkus cli (this fails at the time of writing)
quarkus run -Dquarkus.args='-c -w --val 1'

Quarkus CLI is a very interesting and useful tool, a must-have for Quarkus devs.
I personally used it to migrate a Quarkus project and this tool helped me a lot!
I was also surprised to discover that we can create a picocli app with Quarkus.
So, please give it a try.

Project scaffolders

We have seen earlier that JBang, Gradle and Maven are able to generate projects from scratch.
Scaffolding goes a bit further by also generating other layers of the app (database, front-end, etc.).

Yeoman

Yeoman is a general purpose project scaffolder which is framework and language agnostic.
Even though the tool itself relies on npm (which is installed alongside nodeJS), it can generate any type of project as long as the corresponding project generator is available.
A project generator defines how to scaffold a set of projects.
Fortunately for us, we can explore generators in the discover page and search for the one that we need in a webUI.
There we can find for example, starter projects for VSCode extensions, Office extensions, webaaps, or even servers.

Anyone can create a project generator and publish it to npm so that it is available in the yeoman search engine.

In order to generate a yeoman project locally, we first need to install yeoman with npm i -g yo.
Next, we install the generator with npm install -g [generator].
For example, the generator-jvm can be installed npm install -g generator-jvm and provides some JVM project generators.
Finally, we need to run the generator with yo generator.
For example, to generate a JVM project, we can run yo jvm.

For Java developers, there is a more tailored scaffolder based on Yeoman which is called JHispter.

JHipster and JHipsterLite

JHipster is a project scaffolder specialized in Java projects.
It generates ready-to-use full stack projects with a database, a Java backend, a web frontend and different common services (such as authentication and caching).
The backend is based on Spring Boot with Java and the frontend is based on Angular, React or Vue.

The tool works by asking questions to the user and generating the project based on the answers.
Here is an example of the questions asked and the anwsers that I gave when creating a new project:

? What is the base name of your application? jhispterDemo
? Which *type* of application would you like to create? Monolithic application (recommended for simple projects)
? What is your default Java package name? com.mycompany.myapp
? Would you like to use Maven or Gradle for building the backend? Gradle
? Do you want to make it reactive with Spring WebFlux? Yes
? Which *type* of authentication would you like to use? JWT authentication (stateless, with a token)
? Besides JUnit, which testing frameworks would you like to use?
? Which *type* of database would you like to use? SQL (H2, PostgreSQL, MySQL, MariaDB, Oracle, MSSQL)
? Which *production* database would you like to use? PostgreSQL
? Which *development* database would you like to use? PostgreSQL
? Which cache do you want to use? (Spring cache abstraction) Ehcache (local cache, for a single node)
? Do you want to use Hibernate 2nd level cache? Yes
? Which other technologies would you like to use? Elasticsearch as search engine, Apache Kafka as asynchronous messages broker
? Do you want to enable Gradle Enterprise integration? No
? Which *framework* would you like to use for the client? React
? Besides Jest/Vitest, which testing frameworks would you like to use? Cypress
? Do you want to generate the admin UI? Yes
? Would you like to use a Bootswatch theme (https://bootswatch.com/)? Default JHipster
? Would you like to enable internationalization support? Yes
? Please choose the native language of the application French
? Please choose additional languages to install English
? Would you like to audit Cypress tests? Yes

Once the project is created, the database can be designed with JDL Studio and imported into the project.

Jhipster Lite (or JHLite) is the web counterpart of JHipster.
It is not feature-equivalent to JHipster but it allows to create a project from a web UI.
This page notes that JHLite it is better suited for designing around business and XDD approaches (eXtreme Design Driven).

Both JHipster and JHLite are very useful for quickly prototyping or for projects that use the same technologies provided by them.
However, the opinionated nature of the generated code and the selected frameworks may not suit everyone.
For example, Quarkus is not supported by JHipster and we need to use the Quarkus CLI to generate a Quarkus project.

Advantages and drawbacks

Project scaffolders allow to get a project running really fast where a lot of boilerplate code is already written for us.
Thus the gain in terms of effort and time is considerable.
However, the generated code may not coincide with the developer's way of coding.
Also, some choices are very opinionated, such as the exclusive use of Spring on JHipster.
There's also the issue of vendor-locking where we must update our project using tools provided by the scaffolder if we don't want to take the risk of breaking the dependencies.
In addition to that, since we are dealing with a community project, we face the usual issues of trust and updates.
For example, when I installed Yeoman (on January 2024), npm detected 7 high vulnerabilities.

➜ npm install -g yo

added 801 packages, and audited 802 packages in 1m

122 packages are looking for funding
  run `npm fund` for details

13 vulnerabilities (6 moderate, 7 high)

So, in my opinion, scaffolders are quite relevant for prototypes, PoCs or when we have tight deadlines.
For long term projects, I would use official tools to generate them and avoid scaffolders so that I keep more control over my code.
For example, to develop a Quarkus + Vue project, I'll use Quarkus CLI or code.quarkus.io to create the Quarkus project and vite to create a Vue project.
Of course, this is my current personal opinion which may change in the future.

Conclusion

This post has shown how to get advantage of the command line tools to install a JDK and to create new projects.
We first have seen how to install and manage Java JDKs with scoop and SDKMAN!.
Next, we studied some tools that create Java projects which are JBang, Gradle and Maven.
After that, we have compared Spring Boot CLI and Quarkus CLI which are specialized for their respective frameworks.
Finally, we have seen how to scaffold projects with Yeoman, JHipster and JHipsterLite.

I have also shared my opinion on the use of these tools.
To summarize, I recommend to use CLI tools as much as possible depending on the use case to avoid GUIs and to keep the DX as simple as possible.

I hope that this post has been useful to you and that you have discovered new tools that will make your Java development experience more enjoyable.

My feedback after upgrading a Quarkus project from v2 to v3

Yassine Benabbas — Mon, 04 Dec 2023 11:12:51 +0000

In our team (Worldline TechSquad), we are develop and maintain a CRUD REST API for managing our internal events. The development started with Kotlin and Quarkus 1 which was updated to Quarkus 2.
Since July 2023 Quarkus 3.2 is the current LTS release. Thus, we wanted to update our app as soon as possible to remain on a proper long term release.

This post shares my experience upgrading our REST API from Quarkus 2 to Quarkus 3 hoping that it'll help you avoid our issues if you do a similar upgrade 😊.

(Almost) Easy upgrade with Quarkus-cli

The official documentation recommends to upgrade using the quarkus-cli by running quarkus update. However, this did not work on our project on the first try.
This may be caused by many reasons, maybe because our project was not created using a recent Quarkus starter or because we modified the POM file a bit too much.
For example, we were not using the Quarkus BOM and we were specifying the version on each Quarkus library.

Since my assumptions were based on a POM file which is not quarkus-cli friendly, I decided to make a new one.
In order to do that, I first created a new project through code.quarkus.io and selected all the extensions that we use in our project: Kotlin, Postgres and Panache, RESTEasy Classic Jackson, etc. After that, I replaced our old POM with the one the generated one. Finally, I added the libraries that we use and that were not available as extensions, such as arrow.

After updating the POM and checking that the project still compiles, I tried to run quarkus update again but the update failed. Since I'm on Windows I tried on PowerShell Core and on CMD but both failed. My last hope was using a proper Linux environment: WSL.

So I installed the quakus-cli, again, on a WSL Ubuntu and ran another quarkus update.
This time, the upgrade successfully completed. One of the biggest changes that this tool did was to rename all javax imports to jakarta.
I didn't count how many lines were affected but I think it was near to 100 lines.
So the upgrade tool proved to be really helpful.

After the upgrade, our project was also building without issues and the REST API was running again. Yay!
The next step was to check if there were no regressions on runtime.

Issues encountered after the upgrade

Can you guess if we encountered any issues ? Of course yes!

Actually, most of the bugs that we had originated from migrating Hibernate from version 5 (used by Quarkus 2) to version 6 (used by Quarkus 3). Quarkus provided two migration guides (this one, and this other one) just for Hibernate. Since I didn't read the docs beforehand 🤦‍♂️, the issues that we encountered were to be expected.

Here is a listing of the errors that we got and how we fixed them:

Composite keys new requirement

Composite keys require to implement Comparable or they fail to instantiate at runtime.

// before: fails on Quarkus 3 (with Hibernate 6)
data class CompositeKey(
  var reference: String = "", 
  var session: OtherCompositeKey = OtherCompositeKey()
  ) : Serializable

To fix this, we made our composite keys implement Comparable as follows:

// after
data class CompositeKey(
  var reference: String = "",
  var otherCompositeKey: OtherCompositeKey = OtherCompositeKey()
  ) : Serializable, Comparable<CompositeKey> {
    // Comparing reference works in our case becase we use a UUID 
    override fun compareTo(other: CompositeKey) 
      = reference.compareTo(other.reference)
}

Our implementation of compareTo(other: CompositeKey) compares only reference field instead of using both fields of the composite key. This works fine for us (at least for now) because we use UUIDs for references, and it's very rare to get a duplicate UUID. Maybe in the future we'll implement a more correct compareTo like this one :

override fun compareTo(other: CompositeKey) 
  = (reference + otherCompositeKey)
       .compareTo(other.reference + other.otherCompositeKey)

What do you think ?

Implicit foreign column names not working anymore

We had JPQL queries that reference foreign columns and we used the names generated by hibernate. After migrating to Quarkus 3 (thus Hibernate 6), those queries failed because the foreign columns were not found anymore. For example, these foreign column names were not detected anymore in JPQL: edition_event_reference and edition_reference.

It looks like we could have fixed this using the foreignKey attribute of the @JoinColumn annotation as explained in this post.

@ManyToOne
@JoinColumn(name = "edition_id", foreignKey = @ForeignKey(name="edition_reference"))
private Edition editionReference;

But in our case, we simply replaced those columns with join statements. For example, we replaced uses of edition_reference by a join; select s from Session s join s.edition e.

It's good to be lazy

Non-lazy (or eager) OneToMany fields started to generate cryptic errors. A fortunately found forum post gave me the hint to set the fetch attribute to FetchType.LAZY and the error was magically fixed.

Angry sequence generator

We were using a @GeneratedValue which was referencing an automatically generated sequence by hibernate which is called hibernate_sequence.

@Id
@GeneratedValue(
    strategy = GenerationType.SEQUENCE,
    generator = "hibernate_sequence"
)
var id: Long = 0

After migrating to Hibernate 6, this caused issues with the generated ids. After some investigation, my colleague shared an article that helped us fix the issue. Kudos to the author Nicholas Tsim !

After reading the article, we understood that issue was that the allocation size (the range of ids that managed by the Hibernate) which was not in sync between hibernate and the database sequence linked to it.
To put it simply, Hibernate optimizes requests for the next id the sequence by managing a set of ids internally which is called allocationSize.

For example, if the next number of the database sequence is 5 and allocationSize, then Hibernate will internally manage the autoincrement from 5 to 14 (or 15 I'm not sure here :)).
When it reaches the next id, it will request the next database sequence
We fixed this by explicitly specifying the allocation size in code and

Si our code we added a @SequenceGenerator annotation:

@Id
@GeneratedValue(
    strategy = GenerationType.SEQUENCE,
    generator = "registration_id_seq"
)
@SequenceGenerator(
    name = "registration_id_seq",
    sequenceName = "hibernate_sequence",
    allocationSize = 10
)
var id: Long = 0

And in the database we set the increment of the sequence with the same amount of the allocation size.
We achieved this by running this SQL script ALTER SEQUENCE hibernate_sequence INCREMENT BY 10;.
After these changes, our id generation issue was finally fixed !

Conclusion

Upgrading our Quarkus project from version 2 to version 3 went globally very smoothly given the legacy code that we had.
Our pain points were the POM which was not friendly with upgrade tool, and the migration from Hibernate 5 to 6.
But the biggest pain point was the latter.
Thus, the lesson that I learnt is to not underestimate the migration impacts of a dependency which can be bigger than the framework that uses it.

After overcoming all the challenges, our API is now rocking on Quarkus 3 LTS and we are waiting for the next LTS to arrive.

Happy coding !

Creating an iCalendar event with HTML content in Kotlin / JVM

Yassine Benabbas — Wed, 25 Jan 2023 19:33:37 +0000

Introduction

The iCalendar format allows to define calendar events in a simple text file. The most common file extension of an iCalendar file is .ics and is supported by many apps, such as Outlook.

An iCalendar can define many types of information, such as events and to-dos, using many standard properties. Among these properties, an important one is missing for standard events, which is to define the event description in HTML. Indeed, the default description property DESCRIPTION takes only plain text values. Fortunately, there is an experimental property X-ALT-DESC that can supports HTML markup.

In this post, we'll use a library called biweekly in order to programmatically create an iCalendar event with an HTML description. But first let's start with some manually created files.

Manually created iCalendar with an X-ALT-DESC property

The following file illustrates a basic iCalendar event that contains both DESCRIPTION and X-ALT-DESC.

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//xyz Corp//NONSGML PDA Calendar Version 1.0//EN
BEGIN:VEVENT
UID:uid1@awesome.com
ORGANIZER:mailto:organizer@awesome.com
DTSTAMP:20230101T100000Z
DTSTART:20230101T100000Z
DTEND:20230102T113000Z
SUMMARY:Awesome Event
DESCRIPTION:Please join this awesome event
X-ALT-DESC;FMTTYPE=text/html:<!doctype html><html><body><h1 style="color:blue">Awesome event</h1><p>Please join</p></body></html>
END:VEVENT
END:VCALENDAR

Setting both DESCRIPTION and X-ALT-DESC properties in the same event is valid and works on any tool that is compatible with iCalendar. In fact, if the tool does not support X-ALT-DESC, then DESCRIPTION will be used instead. Tools that do support X-ALT-DESC can ignore the DESCRIPTION field and use X-ALT-DESC instead. That's what Outlook does as we'll see later.

You can test iCalendar by first putting this content in a text file and changing its extension to .ics. Next you can just open it if you have a calendar app installed (such as Outlook) or import it into a Calendar app (such as Google Calendar). You can also download this ics file which already contains the above text.

This is how Outlook renders the ics file:

We can note that Outlook ignores DESCRIPTION when X-ALT-DESC is available.

And here is the rendering of Google Calendar. We can note that it just ignores X-ALT-DESC and uses DESCRIPTION instead.

Creating an iCalendar with an X-ALT-DESC property with biweekly

biweekly is an iCalendar library which supports the JVM and Android. This means that it can target a wide range of applications. In this chapter, we'll use this library to create and ics file in a Kotlin project. We'll use IntelliJ IDEA community edition because it's free and provide powerful Kotlin support.

So, let's create a new project by choosing Kotlin as language:

After that, we need to add biweekly as a dependency in build.gradle.kts:

dependencies {
    ...
    implementation("net.sf.biweekly:biweekly:0.6.6") // add this line
    ...
}

Next comes the fun part where we write some code. The following snippet creates an iCalendar event and prints it to the console and writes it into a file.

val event = VEvent()
// set start and end dates
val startDateTime = LocalDateTime.of(2022, 1, 1, 10, 0)
event.setDateStart(Date.from(startDateTime.toInstant(ZoneOffset.UTC)), true)
val endDateTime = startDateTime.plusDays(2).plusHours(1).plusMinutes(30)
event.setDateEnd(Date.from(endDateTime.toInstant(ZoneOffset.UTC)), true)
// set summary, description and organizer
event.setSummary("Awesome event")
event.setDescription("Please join this awesome event")
event.setOrganizer("organizer@awesome.com")
// set the HTML content to X-ALT-DESC. We also need to set FMTTYPE parameter to text/html
event.setExperimentalProperty(
    "X-ALT-DESC",
    "<!doctype html><html><body>" +
            "<h1 style='color:blue'>Awesome event</h1>" +
            "<p>Please join</p></body></html>"
).setParameter("FMTTYPE", "text/html")
// create the iCalendar
val ical = ICalendar()
ical.addEvent(event)
// Print it on the console
print(Biweekly.write(ical).go())
// Write to file
val file = File("awesome-event.ics")
Biweekly.write(ical).go(file)

The generated ics is as follows:

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Michael Angstadt//biweekly 0.6.6//EN
BEGIN:VEVENT
UID:4a945aec-3b58-437d-90fe-7ded8e352ec9
DTSTAMP:20230125T184903Z
DTSTART:20220101T100000Z
DTEND:20220103T113000Z
SUMMARY:Awesome event
DESCRIPTION:Please join this awesome event
ORGANIZER:mailto:organizer@awesome.com
X-ALT-DESC;FMTTYPE=text/html:<!doctype html><html><body><h1 style='color:bl
 ue'>Awesome event</h1><p>Please join</p></body></html>
END:VEVENT
END:VCALENDAR

We can note that biweekly automatically adds the VERSION, PRODID and UID fields, which is always nice.

Opening the ics with outlook show this.

We can go even further by embedding an image using a base64 src. Here is the improved code that embeds an image in the ics.

val event = VEvent()
val startDateTime = LocalDateTime.of(2023, 1, 1, 10, 0)
event.setDateStart(Date.from(startDateTime.toInstant(ZoneOffset.UTC)), true)
val endDateTime = startDateTime.plusDays(2).plusHours(1).plusMinutes(30)
event.setDateEnd(Date.from(endDateTime.toInstant(ZoneOffset.UTC)), true)
event.setSummary("Awesome event")
event.setDescription("Please join this awesome event")
event.setOrganizer("organizer@awesome.com")
event.setExperimentalProperty(
    "X-ALT-DESC",
    "<!doctype html><html><body>" +
            "<h1 style='color:blue'>Awesome event</h1>" +
            "<p>Please join</p>" +
            "<img src=\"data:image/jpeg;base64,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\" alt=\"\" />" +
            "</body></html>"
).setParameter("FMTTYPE", "text/html")
val ical = ICalendar()
ical.addEvent(event)
print(Biweekly.write(ical).go())
Biweekly.write(ical).go(File("awesome-event-with-image.ics"))

The ics should render as follows in Outlook.

Conclusion

In this post, we have created some iCalendar files by hand and by code using biweekly. We also took advantage of the experimental property X-ALT-DESC to display a more fun and colorful description thanks to the power of HTML.

You can find the source code of the project here.

Happy coding.

How to build a native Linux app of a Quarkus project from another OS using a container

Yassine Benabbas — Wed, 07 Dec 2022 20:37:43 +0000

Quarkus qualifies itself as SUPERSONIC/SUBATOMIC/JAVA partly thanks to its support for GraalVM. This post shows how to build a GraalVM native image for Linux from using a container, allowing to perform this task from Windows or macOS.

Motivation

GraalVM is a high performance JDK distribution which brings many interesting features such as supporting non JVM languages (such as Python). Among the features of this JDK, the one that we're interested in here is called native image, which compiles Java code into a native binary. This means that the resulting binary will contain machine code instead of the traditional bytecode. Theoretically, we would gain in performance and startup speed.

Quarkus allows to generate a native image for the current platform quite easily. However, since most servers run on Linux, we would like to find the simplest way to generate a native Linux binary. Unfortunately, GraalVM does not seem to support cross-compilation yet. Thus, we need to find other alternatives. Hopefully, Quarkus provide a very accessible technique, described here, which requires to have a container engine installed and does not require to install GraalVM.

In this post, we'll try out to use a container to build the native image and we'll use podman as the container engine.

Prerequisites

Please read my previous post which describes how to install the prerequisites which are summarized as follows:

Java JDK 17
podman
On Windows, WSL needs to be installed and enabled

You can verity that you're good to go by running these commands.

java --version
podman run hello-world

We don't need to install GraalVM nor any native compilation toolchain as they will be handled by the container which will build the native image.
That's what makes this technique so easy !.

Sample project

We're going to use the sample project developed during a previous post. It consists of a Quarkus Rest API that uses a PostgreSQL database for development and a H2 in-memory database for production. For the sake of simplification, H2 is chosen in because it makes the production app autonomous and easier to test. The application.yaml file is shown below:

greeting:
  message: "hello"

quarkus:
  datasource:
    db-kind: PostgreSQL

"%prod":
  quarkus:
    datasource:
      db-kind: H2
      jdbc:
        url: jdbc:h2:mem:default

After cloning the project, please run the following commands to verify that we're ready to go:

Run tests: .\gradlew test or in Windows .\gradlew.bat test
Run the server in production mode: .\gradlew quarkusDev -Dquarkus.profile=prod

The backtick character is required on PowerShell for arguments that have a dot .. So, -Dquarkus.profile=prod becomes (backtick)-Dquarkus.profile=prod in PowerShell, and so on.

Checking the production profile locally is recommended because the native image will use that profile.
Once you're ready, let's create the native image.

Creating the native image using a container

Open a terminal on the project folder and run this command:

.\gradlew build -Dquarkus.package.type=native -Dquarkus.native.container-build=true -Dquarkus.native.container-runtime=podman

This argument -Dquarkus.native.container-runtime=podman allows to use podman as a container tool.

The command should finish with an output similar to this one:

------------------------------------------------------------------------------------------------------------------------
Produced artifacts:
 /project/testcontainers-demo-1.0.0-SNAPSHOT-runner (executable)
 /project/testcontainers-demo-1.0.0-SNAPSHOT-runner-build-output-stats.json (json)
 /project/testcontainers-demo-1.0.0-SNAPSHOT-runner-timing-stats.json (raw)
 /project/testcontainers-demo-1.0.0-SNAPSHOT-runner.build_artifacts.txt (txt)
========================================================================================================================
Finished generating 'testcontainers-demo-1.0.0-SNAPSHOT-runner' in 3m 34s.

The native app (also called native image) is /project/testcontainers-demo-1.0.0-SNAPSHOT-runner

Running the Linux app from other OSes

We'll be exploring two techniques even if there may be more, such using a virtual machine.

Using WSL on Windows

On windows, it's quite easy to test thanks to WSL:

wsl # open a WSL session
./build/testcontainers-demo-1.0.0-SNAPSHOT-runner

The output should display this:

__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2022-12-06 22:42:05,809 INFO  [io.quarkus] (main) testcontainers-demo 1.0.0-SNAPSHOT native (powered by Quarkus 2.14.2.Final) started in 0.942s. Listening on: http://0.0.0.0:8
080
2022-12-06 22:42:05,828 INFO  [io.quarkus] (main) Profile prod activated.
2022-12-06 22:42:05,828 INFO  [io.quarkus] (main) Installed features: [agroal, cdi, config-yaml, hibernate-orm, hibernate-orm-panache, hibernate-orm-panache-kotlin, jdbc-h2, j
dbc-postgresql, kotlin, narayana-jta, resteasy-reactive, resteasy-reactive-jackson, resteasy-reactive-kotlin-serialization, smallrye-context-propagation, vertx]
^C2022-12-06 22:42:12,136 INFO  [io.quarkus] (Shutdown thread) testcontainers-demo stopped in 0.012s

This means that the server is up and running.

Using a container

We can also test the native Linux app by running it from a container. This allows to run the app from any OS as long as there is a tool that runs containers. But, we need to first create the image.

Hopefully, projects generated using Quarkus starter already provides the configuration file, located in src/main/docker/Dockerfile.native-micro that is used by the container tool in order to generate the image that hosts and runs the native Linux app. It just requires that the native Linux app is already generated, which we already did. So, let's run this command:

podman build -f src/main/docker/Dockerfile.native-micro -t IMAGE_NAME .

Please replace IMAGE_NAME with the desired name of the image, such as: myapp/native-server.

You can test the image by running podman run IMAGE_NAME_OR_ID and upload it to a container registry by running podman push IMAGE_NAME_OR_ID REGISTRY_NAME. IMAGE_NAME_OR_ID REGISTRY_NAME corresponds to either the name of the image that you used earlier, or its ID that you can get by running podman images.

If running the image fails, it may be due to a missing execution permission for the native app. Please add a RUN chmod +x /work/application in the dockerfile src/main/docker/Dockerfile.native-micro to fix this. The file that I used is shown below:

FROM quay.io/quarkus/quarkus-micro-image:1.0
WORKDIR /work/
RUN chown 1001 /work \
    && chmod "g+rwX" /work \
    && chown 1001:root /work
COPY --chown=1001:root build/*-runner /work/application
RUN chmod +x /work/application

EXPOSE 8080
USER 1001

CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]

You can run my generated image hosted on quay.io as an example: podman run quay.io/yostane/quarkus-jvm-demo/quarkus-jvm-demo-micro.

podman run quay.io/yostane/quarkus-jvm-demo/quarkus-jvm-demo-micro
__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2022-12-07 20:19:51,660 INFO  [io.quarkus] (main) testcontainers-demo 1.0.0-SNAPSHOT native (powered by Quarkus 2.14.2.Final) started in 0.357s. Listening on: http://0.0.0.0:8080
2022-12-07 20:19:51,669 INFO  [io.quarkus] (main) Profile prod activated.
2022-12-07 20:19:51,669 INFO  [io.quarkus] (main) Installed features: [agroal, cdi, config-yaml, hibernate-orm, hibernate-orm-panache, hibernate-orm-panache-kotlin, jdbc-h2, jdbc-postgresql, kotlin, narayana-jta, resteasy-reactive, resteasy-reactive-jackson, resteasy-reactive-kotlin-serialization, smallrye-context-propagation, vertx]

Conclusion

This post showed how to generate a native Linux image of a Quarkus application in a very simple and straightforward way. This native app does not a require a JRE and is "theoretically" faster and more optimized than a JVM counterpart.

We used a container to generated the image which handled all the native complication toolchain. It also allowed to cross-compile to Linux. I was really surprised to see how it's easy to generate a native image using this technique. So, why not try it out on your side ?

Using Podman to run Testcontainers in a Quarkus project

Yassine Benabbas — Tue, 29 Nov 2022 20:12:20 +0000

In the area of container engines, podman seems to be a relevant alternative to docker, at least during the development phase on a Windows or macOS machine. Indeed, both podman and podman-desktop, it's desktop UI, do not require a paid licence. Which is not the case anymore for Docker-Desktop under certain conditions (it's still free for individual developers, education, open source communities, and small businesses). In addition to that, podman is daemonless and can run in rootless mode.

This article shows how to use podman as a container engine instead of Docker and Docker-Desktop on Windows and macOS. We'll see how to install this tool and how to configure it to run tests that rely on Testcontainers. So let's get started with the prerequisites.

Prerequisites

Even though you can use the official installers, I suggest to use package managers moving forward.

On Windows, you can use scoop
On macOS, you can use sdkman for java-related tools ad homebrew for the others.
Java JDK 17
podman
Optionnal: podman-desktop
On Windows, WSL needs to be enabled

Start and configure podman

Open a terminal and run these commands:

podman machine init, which initializes a new VM. You just need to run it once.
podman machine start, which starts the VM. You need to re-run it after each reboot.
Podman-desktop allows to configure the podman machine to auto-start. You can start if from the apps menu.

Now we are ready to launch containers. Run podman run hello which launches a basic container.
The last thing we need to configure is to set this environment variable to TESTCONTAINERS_RYUK_DISABLED to true

The next section demonstrates that we can use Testcontainers through a sample project.

Sample Quarkus project that uses Testcontainers

Let's create with an app with Quarkus which consists of a REST API that backs its data on a postgreSQL database.

Quarkus provides zero-confguration databases for development and test modes (called DEV SERVICES FOR DATABASES). It relies on a containerization tool, such as docker or podman, for some databases. Since we have podman installed and configured, we are ready to go.

In order to create a starter project, open code.quarkus.io and choose JDBC Driver - PostgreSQL extension and any other extensions that you'd like to use for you project.

In the following, I have selected the following extensions just for fun 😁.

YAML Configuration
JDBC Driver - PostgreSQL
Hibernate ORM with Panache
Hibernate ORM with Panache and Kotlin
Kotlin
RESTEasy Reactive
RESTEasy Reactive Kotlin Serialization

I also selected Gradle with Kotlin SDL build tool, but you can use any available one.

Once the applications information and extensions are selected, generate and download the zip archive. After that, unzip that archive and open a terminal on the root folder of the project (the one contains pom.xml, build.gradle or build.gradle.kts).

Next, run the tests using .\gradlew.bat test (if you are using powershell). You should see the following output:



********************************************************************************
Ryuk has been disabled. This can cause unexpected behavior in your environment.
********************************************************************************
2022-11-27 00:16:55,210 INFO  [org.tes.DockerClientFactory] (build-57) Checking the system...
2022-11-27 00:16:55,212 INFO  [org.tes.DockerClientFactory] (build-57) ?? Docker server version should be at least 1.6.0
2022-11-27 00:16:55,241 INFO  [org.tes.uti.ImageNameSubstitutor] (build-57) Image name substitution will be performed by: DefaultImageNameSubstitutor (composite of 'ConfigurationFileImageNameSubstitutor' and 'PrefixingImageNameSubstitutor')
2022-11-27 00:16:55,284 INFO  [doc.io/postgres:14]] (build-57) Pulling docker image: docker.io/postgres:14. Please be patient; this may take some time but only needs to be done once.
...
BUILD SUCCESSFUL in 21s
9 actionable tasks: 1 executed, 8 up-to-date

The tests were executed successfully. The output proves that a container image has been downloaded and started. We can deduce that Podman was successfully able to interact with Testcontaiers, which is the library that is responsible for testing with containers.

Let's analyse this output. The following line means that the environment variable that we set earlier was detected.

Ryuk has been disabled. This can cause unexpected behavior in your environment.

This line means that postgreSQL container image docker.io/postgres:14 is being downloaded.

2022-11-27 00:16:55,284 INFO [doc.io/postgres:14]] (build-57) Pulling docker image: docker.io/postgres:14. Please be patient; this may take some time but only needs to be done once.

Finally, we can check with podman the presence of a postgreSQL image. Open a terminal and run podman images, you should see an output similar to this one.



REPOSITORY                  TAG         IMAGE ID      CREATED      SIZE
docker.io/library/postgres  14          c920f82d2df2  11 days ago  384 MB

Indeed, the postgres image is present. We have used containers with Podman. Horaaay !

Testing with an entity

Even though we validated that podman works with testcontainers, we did not really use the database yet. Thus, for the sake of completion, let's create a Panache entity as well as a repository, and update our REST resource and tests to use this entity.

Here is the code on the app side:



@Entity
@Serializable
class Greeting : PanacheEntity() {
    lateinit var message: String
}

@ApplicationScoped
class GreetingRepository : PanacheRepository<Greeting> {
    fun findByPrefix(prefix: String) = list("message like ?1", "$prefix%")
}

@Path("/")
class GreetingResource {

    @Inject
    lateinit var greetingRepository: GreetingRepository

    @GET
    @Path("/greetings/{prefix}")
    @Produces(MediaType.APPLICATION_JSON)
    fun greetings(@PathParam("prefix") prefix: String) = greetingRepository.findByPrefix(prefix).orEmpty()
}

The library used for entity mangement is called Panache and allows to use the repository pattern with Hibernate.

⚠ We added @Serializable on the entity so that it can be parsed into and from JSON. However, the Quarkus project generator did not add an important plugin that makes serialization work with Kotlin. Please add this plugin to build.gradle.kts in order to enable this feature: id("org.jetbrains.kotlin.plugin.serialization") version "1.7.21"

The plugin part should look like this:



plugins {
    kotlin("jvm") version "1.7.21"
    kotlin("plugin.allopen") version "1.7.21"
// add this line
    id("org.jetbrains.kotlin.plugin.serialization") version "1.7.21"
    id("io.quarkus")
}

This is the test code. The method prepareData adds initial data to the database and testHelloEndpoint tests the above endpoint. The library that is used for testing the REST API is called rest-assured and provides a nice DSL (Domain Specific Language) with functions such as given and when.



@QuarkusTest
class GreetingResourceTest {

    @Inject
    lateinit var greetingRepository: GreetingRepository

    @Transactional
    @BeforeEach
    fun prepareData() {
        greetingRepository.deleteAll()
        val greeting = Greeting()
        greeting.message = "hello world"
        greetingRepository.persist(greeting)
        greetingRepository.flush()
    }

    @Test
    fun testHelloEndpoint() {
        given()
            .`when`().get("/greetings/hello")
            .then()
            .statusCode(HttpStatus.SC_OK)
            .body("$.size()", equalTo(1))
            .body("message", hasItem("hello world"))
    }

}

As stated earlier, no database configuration is needed, thanks to Quarkus' Dev Services. We just need to run .\gradlew.bat test to run the tests and ./gradlew quarkusDev to run the development server.

Conclusion

This article showed how to use podman as a container tool on a Quarkus + testcontainers project. The most important setting that make Podman and Testcontainers interact with each other is setting the environment variable TESTCONTAINERS_RYUK_DISABLED to true.

Happy coding

DEV Community: Yassine Benabbas

JBang, the missing scripting tool of the Java ecosystem

Setup

First script

JDK management

Scripts without a "Main" class

Dependencies

Catalogs

Aliases

Templates

App Store

Some examples with notable frameowrks

JavaFX (openjfx)

Quarkus

Other languages

A tour of CLI tools for installing Java and creating projects

JDK version management

Projects managers

JBang

Gradle

Maven arcehtype:generate

JBang vs Gradle vs Maven

Spring Boot CLI and Quarkus CLI

Project scaffolders

Yeoman

JHipster and JHipsterLite

Advantages and drawbacks

Conclusion

Links

My feedback after upgrading a Quarkus project from v2 to v3

(Almost) Easy upgrade with Quarkus-cli

Issues encountered after the upgrade

Composite keys new requirement

Implicit foreign column names not working anymore

It's good to be lazy

Angry sequence generator

Conclusion

Creating an iCalendar event with HTML content in Kotlin / JVM

Introduction

Manually created iCalendar with an X-ALT-DESC property

Creating an iCalendar with an X-ALT-DESC property with biweekly

Conclusion

How to build a native Linux app of a Quarkus project from another OS using a container

Motivation

Prerequisites

Sample project

Creating the native image using a container

Running the Linux app from other OSes

Using WSL on Windows

Using a container

Conclusion

Using Podman to run Testcontainers in a Quarkus project

Prerequisites

Start and configure podman

Sample Quarkus project that uses Testcontainers

Testing with an entity

Conclusion