moleculer-spring-boot-demo

Moleculer Java Demo Project

The project demonstrates a possible design of a functioning Moleculer-based web-application. The application is launched and configured by the Spring Boot Framework. The project is a standard Maven project and can be imported into any modern IDE (VS Code, IntelliJ IDEA, Eclipse).

The project also includes a Maven installer profile to create a Windows Installer from the project, which installs the finished application as a 64-bit Windows Service.

The Windows Service creates a Moleculer Node that can be connected to another Java or Node.js-based Moleculer Node.

Documentation

Documentation

Topics of the examples

Requirements

The build targets Java 17 (<maven.compiler.release>17</maven.compiler.release>) with the standard javac compiler. The whole stack (Moleculer-Java 2.0.0, Spring Boot 3.5, Jakarta EE 10) requires Java 17+.

Runtime note: the standalone (Netty) server is validated on JDK 21. The bundled Netty 4.2.15 runtime does not run correctly on JDK 25+ yet (JDK 25 removed the sun.misc.Unsafe memory-access methods Netty relies on), so use a JDK 21 runtime for the standalone / installer mode. The WAR (servlet) mode follows whatever JDK its container runs on.

Get the binaries

There are no pre-built downloads. Build the artifacts yourself from source (see below):

Compile and run from source code

The project is a standard Maven project; no IDE plugin is required.

Run the standalone (Netty) version directly with Maven — compile, then launch MoleculerRunner:

mvn compile
mvn exec:java -Dexec.mainClass=services.moleculer.config.MoleculerRunner -Dexec.args=my.application.MoleculerApplication

Or configure a Run Configuration in your IDE with the following parameters (a ready-made VS Code launch configuration is provided in .vscode/launch.json):

The app then serves the examples at http://localhost:3000/ and opens an interactive REPL on stdin (type help).

Build the Web Application WAR

To create a WAR for Jakarta EE servers, run:

mvn clean package

The WAR is generated into the target/ directory as moleculer-demo.war. It is built on the standard non-blocking Jakarta Servlet API (web.xml uses the jakartaee 6.0 namespace) and is compatible with the following application servers:

The WAR may work with other servers as well (it relies only on the standard Jakarta Servlet API).

Build the Windows Installer

The standalone version is not Servlet-based and relies on Netty for higher performance. The project does not include any transporter libraries (JARs) in its initial state. If you want to use transporters (such as Redis, Kafka or NATS) the transporter dependencies must be added to the pom.xml.

To create the installer (Windows-only, opt-in), run:

mvn -Pinstaller package

The installer Maven profile:

  1. copies the runtime dependency JARs into target/lib (maven-dependency-plugin),
  2. packages the application classes into target/lib/moleculer-demo.jar (maven-jar-plugin),
  3. generates a minimal JDK 21+ runtime into target/jre with jlink,
  4. compiles installer/moleculer.config.iss into installer/dist/moleculer_setup_2.0.0.exe using the bundled Inno Setup compiler (installer/setup/ISCC.exe).

The Windows Service wrapper uses the current Apache Commons Daemon prunsrv.exe / prunmgr.exe binaries (in installer/bin/).

The executable installer is generated into the installer/dist directory, as moleculer_setup_2.0.0.exe. This installer creates all required libraries, the bundled Java runtime, and the configuration files needed to run the service.

image

image

image

The Moleculer service can be found in the list of the Windows Services:

image

After the installation, the application can be started in “development” or “production” mode. For “development” mode, run the following BAT file:

C:\Program Files\Moleculer Demo Project\bin\development-start.bat

The application starts in “development” mode with an Interactive Console (enter “help” or “info” to try it out). The sample programs are available at the following URL:

http://localhost:3000/

To exit the application, type “exit” in the Interactive Console. In “production” mode, launch the application with “production-start.bat”. The demo will then run as a Windows Service in the background. The application cannot run at the same time in “production” and “development” mode because the two versions use the same port. To stop the Windows Service, run “production-stop.bat”.

Make your own service

Copy the following code snippet into the “my.services” package/folder:

package my.services;

import org.springframework.stereotype.Controller;

import io.datatree.Tree;
import services.moleculer.eventbus.Listener;
import services.moleculer.eventbus.Subscribe;
import services.moleculer.service.Action;
import services.moleculer.service.Name;
import services.moleculer.service.Service;

@Name("myService")
@Controller
public class MyService extends Service {

    // --- CALLABLE ACTION ---

    @Name("myAction")
    Action action = ctx -> {

        // Read request
        String var1 = ctx.params.get("var1", "defaultValue");
        long var2 = ctx.params.get("var2", 0L);

        // Create response
        Tree rsp = new Tree();
        rsp.put("key", "value");
        return rsp;
    };

    // --- EVENT LISTENER ---

    @Subscribe("myEvent")
    Listener myEventListener = ctx -> {

        // Process event's payload
        boolean var3 = ctx.params.get("key", false);
    };

}

The “ctx.params” and “rsp” variables are hierarchical Tree structures (~= JSONs). For more information about using “Tree”, see the JavaDoc of Tree. At boot time the Spring Framework will automatically register this service as a distributed Moleculer Service, which can be called by other (Java or Node.js) nodes.

License

Moleculer implementations are available under the MIT license.

This site is open source. Improve this page.