NetBeans Platform Runtime Container Tutorial

Last reviewed on 2020-12-19

This tutorial covers the most fundamental concept in the NetBeans Platform: the runtime container. The runtime container is the execution environment for the modules that make up a NetBeans Platform application. It consists of modules provided by the NetBeans Platform. In this tutorial, we will look at these modules, and use them in a very simple modular application.

Before going further, you can watch this video series, which covers the same material as the rest of this tutorial: Top 10 NetBeans APIs

For troubleshooting purposes, you are welcome to download the completed tutorial source code.

Introduction to the Runtime Container

The "NetBeans runtime container" is the collective name for the core parts of the NetBeans Platform.

Brief overview of each of these nine modules:

  • Startup (org-netbeans-core-startup) : Provides the main method of your application, as well as all the code needed for starting it up.

  • Startup Base (org-netbeans-core-startup-base): Private implementation details supporting Startup.

  • Bootstrap (org-netbeans-bootstrap) : Enables the runtime container to understand what a module is, and how to load and compose modules into an application.

  • Filesystem API (org-openide-filesystems): Gives your application a virtual filesystem.

  • Module System API (org-openide-modules): Provides access to the lifecycle of the modules in your application.

  • Lookup API (org-openide-util-lookup): Provides a generic communication mechanism for inter-modular interaction.

  • Base Utilities API (org-openide-util): Includes several utility classes shared between the other modules in the runtime container.

  • Utilities API (org-openide-util-ui): User Interface utility classes.

  • OW2 ASM (): Used for bytecode manipulation. Private implementation detail.

Setting up the Runtime Container

In this section, we will create an absolutely minimal NetBeans Platform application. It will consist of only those modules that every NetBeans Platform application must have - the modules that make up the runtime container. Once we have created an application that consists of nothing more than these none modules, we will run it. There will be no specific output from this application. However, it will build and run successfully because all the fundamental requirements of a NetBeans Platform application will have been met.

  1. Choose menu:File[New Project] (kbd:[Ctrl+Shift+N]). Under Categories, expand Java with Ant, and select NetBeans Modules. Under Projects, select Module:

new project1

Click btn:[Next].

  1. Name your application 'HelloWorld' and specify where to store it:

new project2

Click btn:[Finish]. You now have a minimal NetBeans Platform application:

new project3
  1. Right-click the main project node in the Projects window (HelloWorld), choose Properties:

new project4

The Project Properties dialog appears. Go to the Libraries tab. There you can see all the modules that are part of this application:

new project5
The template you used in step 1 above preselected several modules for you, all of which come from the "platform" cluster.

In addition to the modules making up the runtime container, many other modules are included. We are going to exclude them in the next step because the purpose of this tutorial is to create a minimal NetBeans Platform application, that is, one that contains nothing more than the runtime container.

  1. Click the checkbox next to "platform" to deselect it. There are now no modules in the application.

new project6
  1. Next, scroll down the list, find "Startup", and click the corresponding checkbox, as shown below:

new project7

Click btn:[Resolve], because the Startup module depends on code found in eight other modules that make up the runtime container. Now you should see that the Resolve button disappears, together with the warning messages:

new project8

Scroll up and down the list and notice that ONLY the nine modules that make up the runtime container are included.

Click btn:[OK] to close the Project Properties dialog.

You now have a minimal NetBeans Platform application. It does not contain a user interface. It has nine modules that provide the low level plumbing required in any NetBeans Platform application.

Right-click the application and choose Run (F6). The application successfully executes but doesn’t do or display anything special yet.

Loading a New Module into the Runtime Container

In this section, we add a custom module to the NetBeans runtime container. The custom module will do nothing special: it will only print a message to System.out. The only reason for adding the custom module will be so that you can see that it will be an equal partner to the existing modules in your application. At the end of this section, your application will have ten modules, made up of the nine modules that you already have plus your custom module.

  1. Right-click the application’s Modules node and choose 'Add New…​'.

custom module1
  1. Give your module a project name, such as 'HelloModule' and specify a location to store the module:

custom module2

Click btn:[Next].

  1. Specify a code name base (e.g. org.myorg.hellomodule), which is a unique string that identifies the module:

custom module3

Click btn:[Finish]. You now have a new module:

custom module4
  1. Right-click the module, choose New > Other:

custom module5

Then choose Module Development > Installer/Activator:

custom module6

Click btn:[Next].

  1. The module activator details are shown:

custom module7

Click btn:[Finish] to create the class.

You now have a new class that extends the NetBeans ModuleInstall class, which is from the Module System API.

  1. Add a new 'System.out.println' message in the restored method of the Installer class, as shown in the highlighted line below:

package org.myorg.hellomodule;

import org.openide.modules.ModuleInstall;

public class Installer extends ModuleInstall {

    @Override
    public void restored() {
        System.out.println("hello world!");
    }

}
  1. Run the application again and notice the 'Hello World' message in the application’s output (Output window, which can be opened from the Window menu if required). The end of the stack trace, which includes the 'hello world' message, should be something like this:

>Log Session: Saturday, December 19, 2020 at 3:02:09 PM Australian Eastern Daylight Time
>System Info:
  Product Version         = HelloWorld 12.2-d73d3dd898acc440c460924dabf8ad5feb90369f
  Operating System        = Linux version 5.4.0-58-generic running on amd64
  Java; VM; Vendor        = 11.0.9.1; OpenJDK 64-Bit Server VM 11.0.9.1+1-Ubuntu-0ubuntu1.20.04; Ubuntu
  Runtime                 = OpenJDK Runtime Environment 11.0.9.1+1-Ubuntu-0ubuntu1.20.04
  Java Home               = /usr/lib/jvm/java-11-openjdk-amd64
  System Locale; Encoding = en_AU (helloworld); UTF-8
  Home Directory          = /home/bradh
  Current Directory       = /home/bradh/NetBeansProjects/HelloWorld
  User Directory          = /home/bradh/NetBeansProjects/HelloWorld/build/testuserdir
  Cache Directory         = /home/bradh/NetBeansProjects/HelloWorld/build/testuserdir/var/cache
  Installation            = /home/bradh/NetBeansProjects/HelloWorld/build/cluster
                            /snap/netbeans/41/netbeans/platform
                            /snap/netbeans/41/netbeans/platform
  Boot & Ext. Classpath   =
  Application Classpath   = /snap/netbeans/41/netbeans/platform/lib/boot.jar:/snap/netbeans/41/netbeans/platform/lib/org-openide-modules.jar:/snap/netbeans/41/netbeans/platform/lib/org-openide-util-lookup.jar:/snap/netbeans/41/netbeans/platform/lib/org-openide-util-ui.jar:/snap/netbeans/41/netbeans/platform/lib/org-openide-util.jar
  Startup Classpath       = /snap/netbeans/41/netbeans/platform/core/asm-8.0.1.jar:/snap/netbeans/41/netbeans/platform/core/asm-commons-8.0.1.jar:/snap/netbeans/41/netbeans/platform/core/asm-tree-8.0.1.jar:/snap/netbeans/41/netbeans/platform/core/core-base.jar:/snap/netbeans/41/netbeans/platform/core/core.jar:/snap/netbeans/41/netbeans/platform/core/org-netbeans-libs-asm.jar:/snap/netbeans/41/netbeans/platform/core/org-openide-filesystems-compat8.jar:/snap/netbeans/41/netbeans/platform/core/org-openide-filesystems.jar:/home/bradh/NetBeansProjects/HelloWorld/build/cluster/core/locale/core_helloworld.jar
-------------------------------------------------------------------------------
hello world!
INFO [org.netbeans.core.startup.NbEvents]: Turning on modules:
	org.openide.util.lookup [8.44 12.2-d73d3dd898acc440c460924dabf8ad5feb90369f]
	org.openide.util [9.17 12.2-d73d3dd898acc440c460924dabf8ad5feb90369f]
	org.openide.util.ui [9.18 12.2-d73d3dd898acc440c460924dabf8ad5feb90369f]
	org.openide.modules [7.58 12.2-d73d3dd898acc440c460924dabf8ad5feb90369f]
	org.openide.filesystems [9.20 12.2-d73d3dd898acc440c460924dabf8ad5feb90369f]
	org.openide.filesystems.compat8 [9.19 12.2-d73d3dd898acc440c460924dabf8ad5feb90369f]
	org.netbeans.libs.asm [5.13 12.2-d73d3dd898acc440c460924dabf8ad5feb90369f]
	org.netbeans.core.startup.base [1.72.0.1 1 12.2-d73d3dd898acc440c460924dabf8ad5feb90369f]
	org.netbeans.bootstrap/1 [2.88 12.2-d73d3dd898acc440c460924dabf8ad5feb90369f]
	org.netbeans.core.startup/1 [1.72.0.1 12.2-d73d3dd898acc440c460924dabf8ad5feb90369f]
	org.myorg.hellomodule [1.0 201219]
BUILD SUCCESSFUL (total time: 20 seconds)

Summary

In this tutorial, you have used the minimal set of NetBeans Platform modules that any NetBeans Platform application requires, that is, the NetBeans runtime container, consisting of nine modules. You added a custom module, that is, a module that you created yourself. The custom module printed a message into the Output window.

Notice that you did not need to create a main method because the NetBeans runtime container contains one already. The "module" concept was also predefined in the NetBeans runtime container. Other features of the NetBeans runtime container will be introduced as you take the next steps outlined below.

Next Steps