Site icon JVM Advent

JBang, a gift that keeps on giving

Last week Microsoft published a JBang catalog at https://github.com/microsoft/jbang-catalog.

Now anyone who has downloaded and installed JBang can run jbang catalog list to see the list of Java programs Microsoft made available this way:

$ jbang catalog list microsoft
Aliases:
--------
appinsights-agent@microsoft = Azure Application Insights Agent 3.2.3
Run with `jbang --javaagent appinsights-agent@microsoft <yourapp>`. Needs connection string setup - see https://docs.microsoft.com/en-us/azure/azure-monitor/app/java-in-process-agent for details.
minecraft-server@microsoft = Minecraft: Java Edition Server
Requires agreeing to EULA to run. Create `eula.txt` file with `eula=true` as content and then run using `jbang minecraft-server@microsoft`
                             Java Version: 16
                             Java Options: -Xmx1024M -Xms1024M
playwright@microsoft = Playwright lets you automate Chromium, Firefox and Webkit with a single API.
With this CLI you can install, trace, generate pdf and screenshots and more.
See all commands available:
```
  jbang playwright@microsoft --help
```

You can run the Java based Minecraft Server, the world wide famous sandbox game, PlayWright cli to capture and grab html based content automatically with your favourite browser and finally enable Azure Application Insights as an agent with any jar based java application.

All of this is done using Java, and the user does not even need to install Java manually to run it – just run the following in any bash or zsh based shell:

 curl -Ls https://sh.jbang.dev | bash -s - app setup

If you prefer using operating system specific setup use one of the many other installation options available from jbang.dev.

Once that is installed you can for example run: jbang playwright@microsoft screenshot https://jbang.dev jbang.png and have a screenshot of your favourite website.

All without installing anything but JBang. Everything else is taken care of; and behind the scenes it is just Java driving it all.

Everyone can have a catalog

The beauty of the JBang Catalog is that it’s just a snippet of json you can host anywhere.

Especially if using GitHub, GitLab or bitbucket JBang makes it extra easy, i.e. jbang catalog list microsoft fetches automatically searches for an organization named microsoft with a repository named jbang-catalog.

Microsoft is not the only organization on GitHub who have done this: junit-team, jruby, karatelabs, neo4j, jooq and quarkusio have done similar. Just try using jbang catalog quarkusio or any of the other organizations to see the variety of different applications available.

Individual repositories can add a jbang-catalog.json to get similar benefits. Apache Camel done this enabling: jbang catalog list apache/camel.

Likewise individual people started making catalogs of useful utilities. People like Pierre-Yves Fourmond with his bursting catalog at grumpfy0x48. I.e. he has a git clone you can run as jbang git-clone@grumpyf0x48. Or Tako who has his main catalog at https://github.com/quintesse/jbang-catalog and also a experimental catalog with even more fun things – especially jbang imap@quintesse~experimental – an imap filter/sorting application all in Java.

Anyone can publish a catalog. All you need to do is create a jbang-catalog.json file using jbang alias add -f . myutil <myjar or myjava> and push the generated file to a git hosting site like github or gitlab.

If published in a public GitHub repository it will even show up in JBang AppStore

Read more about Alias and Catalogs in jbang documentation.

Sharing is Caring

Some of the catalogs point to proprietary jars (like Microsoft’s Minecraft), others to opensource projects like Apache/Camel and then there are the JBang scripts.

These files are plain java source files and you can directly see what they are, using jbang info.

For example if we wanted to know how httpd@jbangdev, a standalone http server, is implemented, you run jbang info httpd@jbangdev and get something like:

jbang info tools httpd@jbangdev
{
  "originalResource": "https://raw.githubusercontent.com/jbangdev/jbang-catalog/HEAD/httpd.java",
  "backingResource": "/Users/max/.jbang/cache/urls/24709f5e6c948be4357faa07695271d554275657104b21608577f33ca008c610/httpd.java",
  "applicationJar": "/Users/max/.jbang/cache/jars/httpd.java.7ee224329a71136197c73980f2ab2e9fe39beff924cc835d39f03f35872a39ef.jar",
  "resolvedDependencies": [],
  "availableJdkPath": "/Users/max/.sdkman/candidates/java/current"
}

The “originalResource” gives you the raw source file to go look and learn.

Using jbang edit httpd@jbangdev you can open up the file and dependent source files in an editor. Just note, that edits will not be persisted back to the remote location. For that you need to have the file cloned or copied locally first.

JBang not only makes it easy to publish your script but also to view and edit them. All in the spirit of making everything easily accessible and easy to tinker with.

The Origin Story

Simple java source code being runnable is the origin story of JBang. It set out two years ago to make it easy to use Java for scripting. Initial version was focused on making it easy to use Maven style dependencies from a java file without having to set up Maven or Gradle.

The “hello world” for JBang was and is the following:

///usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS com.github.lalyos:jfiglet:0.0.8
import com.github.lalyos.jfiglet.FigletFont;
class hello {
   public static void main(String... args) throws Exception {
       System.out.println(FigletFont.convertOneLine(
              "Hello " + ((args.length>0)?args[0]:"jbang")));
   }
}

In here you’ll see the first line be a Java comment as well as a bash/zsh compatible command. This lets you directly run using ./hello.java. The second line is a java comment and also a command for JBang. The //DEPS line resolves the Maven artifact called com.github.lalyos:jfiglet:0.0.8. These two “tricks” means that from the view point of any other tools or IDE’s this file is an ordinary Java source file.

When you run the file with jbang, JBang will take care of downloading Java if needed, fetch dependencies, compile the code (possibly multiple files), package it into a jar, cache it all and run it.

This small piece of magic lets anyone share self-contained snippets of code, write full programs, make reproducers for bug reports, play with JavaFX, Quarkus, Spring, you name it – everything available as a maven dependency just works with JBang on your local computer, directly in your terminal or in your IDE.

No terminal, no IDE, no laptop ?

Unfortunately not all have access to a terminal, an IDE or even their own laptop at times. How do we make Java available and accessible here ? One can use cloud-based environments like Eclipse Che, GitHub Codespaces or Gitpod but these still require a certain level of skill and setup.

For a while repl.it have made JBang available in their templates, and its been the “engine” behind https://jbang.dev/try. Lets you create Java scripts directly in your browser. Real Java Script, not JavaScript.

Recently though, jdoodle.com have introduced support for JBang. JDoodle is a website that lets you easily try out many different languages directly in your browsers. JDoodle even allow embedding runnable snippts into your website or a blog like this.

Below is the exact same hello world from above but just JDoodle-enabled. Try run it and even edit it.

You can make your own embeddable JBang snippet using https://jdoodle.com/try-jbang.

Conclusion

JBang started out with a basic idea of making it easier to write small scripts in Java. It then grew into a mission on making Java more accessible by removing as much of the traditional ceremony found in the Java ecosystem.

In this blog we covered how that little spark now enabled easy distribution of any existing java project using JBang Catalogs, how to share and collaborate on Java code – allowing anyone to learn from Java code others written without setup. Finally we now have proper embeddable in browser Java code via sites like repl.it and jdoodle.com.

There is no longer any reason to hide Java behind a wall of complex build systems or IDE setup – jbang enables easy access to the full Java ecosystem – online as well as locally.

There is much more to JBang, you can find out more on jbang.dev.

I hope you like what you see and decided to give it a go using Java in this years adventofcode.com or for your own utility or maybe your next microservice ?

In any case, looking forward to see what gifts you decide to share using JBang!

Author: Max Andersen

Exit mobile version