It's rare for a new major version of software to bring about such a significant paradigm shift: while the Camunda Platform in version 7 was fully integrable into Java applications, Camunda 8 is now based on Zeebe, an independent component with which our code communicates via gRPC. Instead of representing the state of business processes in a database, the operations of the processes are stored in an event log. The goal of the Camunda developers was to create a process engine that is infinitely scalable horizontally. As a result, Camunda 8 can process a significantly higher throughput than Camunda 7, which could only handle as many requests as its central, relational database.

A frequently discussed point about the new platform is that the complexity of an average Camunda installation is higher than it was for the old engine. A productive deployment for Camunda 7 included the engine itself, a relational database, optionally a task list for processing user tasks, and a cockpit for inspecting running processes. Except for the database, we could bundle all these components in a single Java application, which we could deploy using familiar methods.

The changes made with the Camunda 7 Community Edition have caused uncertainty among its users. Not everyone has technical requirements for a process engine that justify managing so many components and maintaining a Kubernetes cluster. The alternative use of the in-house SaaS product, Camunda Cloud, might make sense for smaller companies, but here the costs scale with the executed process instances, so a use case should be carefully calculated. The break-even point, at which self-hosting becomes worthwhile, is likely only surpassed with a considerable number of process instances per hour.

But what about smaller projects that could benefit from process orchestration and the use of BPMN, but would no longer be profitable with the use of the SaaS offering or the operation of more complex infrastructure? In the following example, we will explore this question by building and operating a lightweight process.

Example: A Reminder Bot for Social Networks

A "Reminder-Bot" is a great example of a lightweight process. It involves an account that is mentioned in a message with the addition "in x days," and after this period, responds with a post as a reminder. As a BPMN process, this could look something like this:

Operation of the Process Engine

services:
  zeebe: # https://docs.camunda.io/docs/self-managed/platform-deployment/docker/#zeebe
    image: camunda/zeebe:8.4.1
    container_name: zeebe
    ports:
      - "26500:26500"
      - "9600:9600"
    environment:
      - ZEEBE_BROKER_DATA_DISKUSAGECOMMANDWATERMARK=0.998
      - ZEEBE_BROKER_DATA_DISKUSAGEREPLICATIONWATERMARK=0.999
      - "JAVA_TOOL_OPTIONS=-Xms512m -Xmx512m"
    restart: always
    healthcheck:
      test: [ "CMD-SHELL", "timeout 10s bash -c ':> /dev/tcp/127.0.0.1/9600' || exit 1" ]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 30s
    volumes:
      - ./zeebe-data:/usr/local/zeebe/data

For the container, two ports are mapped: 26500 for gRPC communication and 9600 for the startup and ready check from outside. A volume maps the data from /usr/local/zeebe/data to the host folder zeebe-data, where the broker's event log is stored. From the memory configuration -Xmx512m, which defines a maximum heap of 512MB, we can see that the engine does not have high memory requirements. However, for use cases with higher volume, this might not be sufficient. The broker is started with a docker-compose up command.

Project Setup with Spring Boot

We use Spring Boot for our server-side Java application, which interacts with the Zeebe broker. As a Maven dependency, we add the Camunda Spring Boot Starter, which configures the job workers for us and controls their lifecycle:

<dependency>
    <groupId>io.camunda.spring</groupId>
    <artifactId>spring-boot-starter-camunda</artifactId>
    <version>8.4.0</version>
</dependency>

zeebe.client.broker.gateway-address=localhost:26500
zeebe.client.security.plaintext=true

With the help of this Spring Boot integration, we can also define which process instances should be deployed from the classpath when our application starts. This is done using the @Deployment annotation, which we can add to any configuration classes.

@Configuration
@Deployment(resources = "reminder-process.bpmn")
public class ZeebeConfig {
}

@Autowired
private final ZeebeClient zeebeClient;

record ProcessInput(String content,
                    String statusId,
                    String visibility,
                    String account) {};

public Long startReminderProcess(Status status) {
   var processInput = new ProcessInput(status.content(), 
                                       status.id(), 
                                       status.visibility(),
                                       status.account().acct());

   var result = zeebeClient
           .newCreateInstanceCommand()
           .bpmnProcessId("Process_Reminder")
           .latestVersion()
           .variables(processInput)
           .send()
           .join();

   return result.getProcessInstanceKey();
}

public record ParseRequestResponse(boolean dateUnderstood, 
                                   ZonedDateTime reminderDate) {};

@JobWorker(type = "parseDate")
public ParseRequestResponse parseRequest(
	@Variable String content) {
	
    var matcher = PATTERN.matcher(content);
    if(matcher.find()) {
        var result = matcher.group(1);
        return new ParseRequestResponse(true, 
                      				    ZonedDateTime.now()
                                          .plusDays(Long.parseLong(result)));
    } else {
        return new ParseRequestResponse(false, null);
    }
}

public record SuccessOutput(String reminderStatusId) {};

@JobWorker(type = "confirmCancellation")
public SuccessOutput confirmCancellation(
						@Variable String statusId,
                        @Variable String visibility,
                        @Variable String account) {
                        
    var message = MESSAGE_TEMPLATE.formatted(account, 
                                             "Na gut, der Timer ist abgebrochen");
    var result = mastodonService.replyToStatus(statusId, 
                                               message, 
                                               visibility);
    return new SuccessOutput(result.id());
}

@JobWorker(type = "confirmReminder")
public SuccessOutput confirmReminder(
						@Variable String statusId,
                        @Variable ZonedDateTime reminderDate,
                        @Variable String visibility,
                        @Variable String account) {
    var message = MESSAGE_TEMPLATE.formatted(account, 
                                             "Hey, alles klar! Ich erinnere dich am %s".formatted(reminderDate));
    var result = mastodonService.
    				replyToStatus(statusId, message, visibility);
    return new SuccessOutput(result.id());
}

@JobWorker(type = "respondDateNotUnderstood")
public void replyNotUnderstood(
				@Variable String statusId,
                @Variable String visibility,
                @Variable String account) {
                
    var message = MESSAGE_TEMPLATE.formatted(account, 
    										 "Hi, das habe ich leider nicht verstanden. Schreibe mir 'in x Tagen' oder einfach 'x Tage'");
    mastodonService.replyToStatus(statusId, message, visibility);
}

@JobWorker(type = "remindUser")
public void remind(@Variable String statusId,
                   @Variable String visibility,
                   @Variable String account) {
    var message = MESSAGE_TEMPLATE.formatted(account, "Hi, hier ist deine Erinnerung!");
    mastodonService.replyToStatus(statusId, message, visibility);
}

The Core Implementation 

The complete code can be found as a Gist on GitHub.

On the HTML side, we keep the navigation quite simple. In the <nav> section, there are two lists, one of which is enclosed by a collapsible details block for mobile view:

<nav>
<!-- desktop -->
<ul>
    <li><a href="/">About</a></li>
    <li><a href="/">Blog</a></li>
    <li><a href="/">Contact</a></li>
</ul>

<!-- mobile -->
<details>
    <summary aria-label="open mobile menu"></summary>
    <ul>
        <li><a href="/">About</a></li>
        <li><a href="/">Blog</a></li>
        <li><a href="/">Contact</a></li>
    </ul>
</details>
</nav>

On desktop, we don't want to see the details tag and its contents, while in the mobile view, we don't want the desktop menu:

nav>details {
    display: none;
}

@media (max-width: 991px) {
    /* hide desktop menu */
    nav>ul {
        display: none !important;
    }
    
    /* show mobile menu */
    nav>details {
        display: block !important;
    }
}

Done?!

Our solution now meets all the technical requirements for a responsive menu. Visually, we want to further enhance the result in the next section.

Adding a Hamburger Menu Icon

Most of the time, we see a hamburger menu icon and a close icon on mobile versions of websites. Of course, we don't want to miss this here - and it should be implemented using only CSS:

/* custom image for mobile menu */
nav > details > summary::after {
    content: '';
    background-image: url(img/menu.svg);
    background-size: 2rem 2rem;
    
    display: inline-block;
    width: 2rem;
    height: 2rem;
}

/* alternative image for open mobile menu */
nav > details[open] > summary::after {
    background-image: url(img/close.svg);
}

/* icons used: https://ionic.io/ionicons */

The details[open] attribute allows us to check whether <details> is open or closed. When it's open, in our case, we replace the background image. Since we work with the ::after pseudo-element, we want to ensure that the icon doesn't take up the whole page. By combining background-size, display: inline-block;, width: 2rem; and height: 2rem;, we can ensure that the icon has our desired size.

Animations

Since we can't select parent nodes with CSS, we use a little trick that adds a subtle animation. Animations aren't strictly necessary, but since, in my opinion, this isn't an obvious solution, let's briefly look at what's possible.

nav>details>summary {
    [...]
    /* slight transition */
    transition: margin-bottom 150ms ease-out;
}

/* add margin for slight transition */
nav>details[open]>summary {
    margin-bottom: 1rem;
}

Since we can't access a parent element with CSS selectors (yet?) to animate it as a whole, we add a small margin-bottom in the open state of the dialog, which grows from 0rem to 1rem in 150ms using the transition attribute.

Custom Layouts

The exact layout is subject to individual requirements. Therefore, this article won't go into further detail. Nonetheless, we have enriched the Gist with code for a proper layout variant as an example.

Visual Variations

A Fixed Header

The existing code lets the navigation bar scroll with the entire website. However, if it should always be visible, we can fixate it as follows:

header {
    background-color: aliceblue;
    display: flex;
    justify-content: space-between;
    
    /** toggle fixed header **/
    position: fixed;
    width: 100%;
}
main {
    /* don't forget to increase the top padding with fixed navbar */
    padding: 4rem 1rem;
}

A Fixed Header in Full-Screen

So far, the header in its expanded state is only as large as its content. If this isn't desired and it should instead fill the entire page, we can influence it as follows:

nav>details>ul {
    flex-direction: column;
    align-items: end;
    margin: 0;
    
    /** toggle full page menu **/
    height: 100vh;
}

One Known Issue

Due to the absence of so-called "Focus-Trapping", the page in the background can continue to scroll. This can only be prevented by JavaScript (as of 2023). Therefore, we decided to use a fixed header for our website, which isn't full-screen.

Our core expertise lies in Java and other JVM languages such as Clojure or Kotlin. Hence, the decision to implement our website with Clojure and run it on a JVM was an easy one. Using a full-fledged Content Management System (CMS) would have meant more maintenance and care on our part since our website should only present core information about our company. The decision for server-side rendering of the HTML files was also made for simplicity: the mostly static pages don't require dynamic content in the browser, so sending a large amount of JavaScript files to the viewer's browser, which would slow down page construction, seemed unjustified.

However, this doesn't explain why our website should function entirely without JavaScript. After all, JavaScript on the website can enhance the user experience. Nathaniel provides good reasons for this decision in his blog post "Why your website should work without JavaScript". Data from the last three years suggest that 1% of all devices visiting a website do not execute JavaScript. Only a fifth of these devices intentionally avoid it, perhaps because users have disabled JavaScript or use a NoScript browser extension. The other 0.8% don't execute JavaScript due to errors: outdated browsers, misconfigured browser extensions, or security settings on business devices. Websites offering IT content should assume that the number of devices with intentionally disabled JavaScript is higher than 0.2% of all devices.

This blog aims to be primarily technical. We will write articles about software development and architecture and enrich them with detailed code examples. Syntax highlighting is crucial for the readability of this code. This is evident in the following code block, the read method from the java.io.CharArrayReader class:

@Override
public int read(CharBuffer target) throws IOException {
    synchronized (lock) {
        ensureOpen();

         if (pos >= count) {
            return -1;
        }

        int avail = count - pos;
        int len = Math.min(avail, target.remaining());
        target.put(buf, pos, len);
        pos += len;
        return len;
    }
}

The color scheme instantly helps the eye grasp the structure of the code sample. Language keywords are marked in a consistent color, as are class and method names. This is reminiscent of the highlighting in development environments that software developers use most of the time. Such highlighting usually occurs in the frontend, using tools like Prism.js or highlight.js. These are lightweight and could be easily integrated into this website. However, they add the syntax highlighting only after loading the HTML resource by searching for <code> tags and applying their logic to the content. Apart from a delay in rendering, this also means that the syntax highlighting wouldn't be applied in browsers with disabled or non-functional JavaScript, reducing the website's usability on affected devices.

For these reasons, we want to perform the syntax highlighting on the server. Searching for suitable Java libraries was disappointing: Apart from many dead links to dev.java.net and Google Code, there were only a few smaller libraries supporting few languages and with very limited usage. Needing a solution that will continue to support new programming languages in the future, we decided to execute the JavaScript on the server side using Truffle.

What is GraalVM?

GraalVM is a universal virtual machine developed by Oracle. It was designed to efficiently execute and integrate various programming languages. GraalVM supports a wide range of languages, including Java, JavaScript, Python, Ruby, R, C, C++, and WebAssembly. Its main goal is to enhance the performance of languages on a shared platform and offer developers the ability to seamlessly combine different languages. We want to leverage this capability to invoke prism.js from Java (or Clojure). However, among Java developers, GraalVM is primarily known not for its polyglot features but for its ability to compile Java applications with Native Image into native binaries.

Setting up the VM and Environment

The following example uses GraalVM Community Edition version 20.0.2; it should be set up as the JVM in the context (IDE or $PATH). Since the runtime environment for JavaScript is not installed by default, it must first be installed using the GraalVM Updater:

> gu install js

Downloading: Component catalog from www.graalvm.org
Processing Component: Graal.js
Processing Component: ICU4J
Processing Component: TRegex
Additional Components are required:
    ICU4J (org.graalvm.icu4j, version 23.0.1), required by: Graal.js (org.graalvm.js)
    TRegex (org.graalvm.regex, version 23.0.1), required by: Graal.js (org.graalvm.js)
Downloading: Component js: Graal.js from github.com
Downloading: Component org.graalvm.icu4j: ICU4J from github.com
Downloading: Component org.graalvm.regex: TRegex from github.com
Installing new component: TRegex (org.graalvm.regex, version 23.0.1)
Installing new component: ICU4J (org.graalvm.icu4j, version 23.0.1)
Installing new component: Graal.js (org.graalvm.js, version 23.0.1)
Refreshed alternative links in /usr/bin/

Since we deliver our application in a containerized form, this step is also necessary in the Dockerfile:

FROM ghcr.io/graalvm/graalvm-community:20.0.2
COPY target/uberjar/website.jar /website/app.jar
EXPOSE 3000
RUN ["gu", "install", "js"]
CMD ["java", "-jar", "/website/app.jar"]

It's worth noting that it's not absolutely necessary to run the entire application on GraalVM. As described here, it's also possible to run the JavaScript runtime on a "traditional" JVM.

Calling the Library

After the lengthy introduction, the actual invocation of the code is quite straightforward. First, we create a new context using a Builder Pattern. This provides us with a JavaScript runtime environment:

import org.graalvm.polyglot.Context;
import org.graalvm.ployglot.Source;

private Context buildContext() {
  return Context.newBuilder("js").build();
}

It's advisable to initialize the context once and then reuse it. Thus, at this entry and initialization point, we can also load prism.js from a file (or better, a resource for a production application):

import org.graalvm.polyglot.Context;
import org.graalvm.ployglot.Source;

private Context buildContext() {
  var context = Context.newBuilder("js").build();
  context.eval(Source.newBuilder("js", new File("/path/to/prism.js")).build());
  return context;
}

With this initialized context, we can now work to add syntax highlighting to text for display in HTML:

private String highlightSyntax(Context context, String language, String content) {
  var command = "Prism.highlight('%s', Prism.languages.%s, '%s');".formatted(content, language, language);
  return context.eval("js", command).asString();
}

We use the created context to execute the formatted JavaScript code and return the result of the command as a Java string. To highlight the code, we use the highlight function, the documentation for which can be found here. It quickly becomes apparent that we are generating the script command via string manipulation, thereby potentially opening a door for script injection. Inputs should, therefore, be composed of data we control ourselves or be extremely well validated.

By running a quick test, we can verify that our syntax highlighting works as intended:

String javaCode = "private static final Integer BEST_NUMBER = 42;";
var highlightedCode = highlightSyntax(context, "java", javaCode);
System.out.println(highlightedCode);

<span class="token keyword">private</span> 
<span class="token keyword">static</span> 
<span class="token keyword">final</span> 
<span class="token class-name">Integer</span> 
<span class="token constant">BEST_NUMBER</span> 
<span class="token operator">=</span> 
<span class="token number">42</span>
<span class="token punctuation">;</span>

The symbols have been provided with CSS classes and can now be highlighted with CSS.

java.lang.IllegalStateException: Multi-threaded access requested by thread Thread[http-nio-8778-exec-1,5,main] but is not allowed for language(s) js.

Decorating the code in the HTML source with Clojure

We write our blog entries in a headless CMS. The content is delivered to our frontend, which you, dear readers, are currently looking at, as HTML. This means that we don't have easy access to the raw source code in the article, so we must apply Prism.js manually to it. While we've previously clarified the use of JavaScript on GraalVM with Java code, we'll now demonstrate further steps using Clojure code, which we use for this blog in this exact (or a similar) manner. Firstly, we need to initialize the script engine with prism.js. We create this context in the respective namespace using defonce and delay. With delay, we ensure that the engine is created only when it's actually used, so after an application restart when syntax highlighting occurs for the first time. This ensures that the initialization doesn't block during application startup, but the trade-off is that the first rendering might take an extra 200-300ms.

(defonce js-context
         (delay (doto
                  (.build (Context/newBuilder (into-array ["js"])))
                  (.eval
                    (.build
                      (Source/newBuilder "js"
                                         (clojure.java.io/resource "prism.js")))))))

The code, sadly peppered with Java Interop syntax to work with Java syntax from Clojure, operates just as in the Java example above.

There are also no major surprises in executing the actual JavaScript syntax:

(defn highlight-code [language code]
  (let [context @js-context]
    (locking context
      (.asString
        (.eval context
               "js"
               (format "Prism.highlight('%s', Prism.languages.%s, '%s');" 
                       code 
                       language 
                       language))))))

Again, the code looks very familiar to us. Three things are noteworthy: The @ before js-context dereferences our lazily initialized context. If this has not happened by this point, it is initialized here. Furthermore, we use Clojure's locking function to prevent parallel access to the js-context. On the other hand, we might want to scratch our heads a bit here: We use Java-Interop code from Clojure to ultimately execute JavaScript, which one might find amusing.

To finally apply our syntax highlighting to all code blocks in our articles, we need to find them in the HTML, extract, and replace them with the new, annotated code. Fortunately, we don't have to do this manually; we can rely on enlive, a Clojure library based on JSoup:

(defn highlight-code-in-article [content]
  (apply str
         (-> content
             (html/html-snippet)
             (html/transform [:code]
                             (fn [selected-node]
                               (update-in selected-node [:content]
                                          (fn [[content]]
                                            (if-let [language-class (get-in selected-node [:attrs :class])]
                                              (html/html-snippet (highlight-code (clojure.string/replace language-class #"language-" "") content))
                                              content)))))
             (html/emit*))))

The highlight-code-in-article function takes the entire article text. This text is loaded into enlive with html/html-snippet and converted into a Clojure data structure. The function html/transform then searches for all <code> elements in this structure with the selector :code and applies an anonymous function, which we'll extract for better readability:

(fn [selected-node]
  (update-in selected-node [:content]
             (fn [[content]]
               (if-let [language-class (get-in selected-node [:attrs :class])]
                 (html/html-snippet (highlight-code (clojure.string/replace language-class #"language-" "") content))
                 content))))

Prism.js returns a string to us, so using enlive and html/html-snippet, we must convert it back into a Clojure data structure before embedding it in the HTML. The result is exactly what you see on this page: the code is already decorated with CSS classes by the server.

Discussion

Is the result worth the effort? We believe so. We've achieved our goal of leveraging a sophisticated syntax-highlighting library in the backend. We use Java, or rather JVM tools, and the library itself. It should be noted that the execution speed of this solution is not particularly fast. With 5 to 6 code blocks, an extra 200-300ms can be added if the JavaScript context has been previously initialized. This is not a concern in our use case, as we cache the articles and don't need to process them every time they're delivered. If this were different, we'd probably look for a more performant solution.

The use cases for GraalVM's polyglot features are numerous. Besides JavaScript, Ruby, Python, and R are particularly interesting. The ability to have these languages operate with Java on the same VM is exciting and could open up new possibilities, especially in the field of statistical evaluations.