NetBeans Platform Runtime Container Tutorial

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 define a NetBeans Platform application. It consists of six modules provided by the NetBeans Platform. In this tutorial, we will look at these six 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

Note: This document uses NetBeans Platform 8.0 and NetBeans IDE 8.0. If you are using an earlier version, see the previous version of this document.


Content on this page applies to NetBeans IDE 8.0

To follow this tutorial, you need the software and resources listed in the following table.

Software or Resource Version Required
NetBeans IDE version 8.0 or above
Java Developer Kit (JDK) version 7 or above

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 these NetBeans Platform modules:


Brief overview of each of these six modules:

  • Startup (org-netbeans-core-startup)—Provides the main method of your application, as well as all the code needed for starting it up.
  • Bootstrap (org-netbeans-bootstratp)—Enables the runtime container to understand what a module is and how to load and compose them into one application.
  • Filesystem API (org-openide-filesystems)—Gives your application a virtual filesystem.
  • Module System API (org-openide-modules)—Gives you 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.
  • Utilities API (org-openide-util)—Includes several utility classes shared between the other modules in the runtime container.

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 six modules that make up the runtime container. Once we have created an application that consists of nothing more than these six 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. Go to File > New Project. In the New Project dialog, choose NetBeans Modules > NetBeans Platform Application:

    creating a new project

    Click Next.

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

    set the name

    Click Finish. You now have your first NetBeans Platform application:

    project structure

  3. Right-click the main project node in the Projects window, choose Properties, and go to the Libraries tab. There you can see all the modules that are part of this application:

    project structure

    Note: Notice that the template you used in step 1 above preselected several modules for you. Also notice that the preselected modules all come from the "platform" cluster.

    In addition to the six 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.

  4. Click the checkbox next to "platform". Now all modules are unselected, that is, there are now no modules in the application. Next, scroll down the list, find "Startup", and click the corresponding checkbox, as shown below:

    project structure

    Click the Resolve button, because the Startup module depends on code found in five other modules, that is, the other modules making up the runtime container. Now you should see that the Resolve button disappears, together with the warning messages:

    project structure

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

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

Right-click the application and choose Run. 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 one 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 six modules in your application. At the end of this section, you will have seven modules instead of the six that you already have, that is, you will have included your own custom module.

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

    project structure

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

    project structure

    Click Next.

  3. Specify a code name base, which is a unique string that identifies the module:

    project structure

    Click Finish. You now have a new module:

    project structure

  4. Right-click the module, choose New > Other, and then choose Module Development > Installer/Activator:

    project structure

    Click Next.

  5. Click Finish below to complete the wizard:

    project structure

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

  6. Add a new 'System.out.println' message in the 'restored' method of the Installer class, as shown in the highlighted line below:
    package org.mycompany.hello;
    import org.openide.modules.ModuleInstall;
    public class Installer extends ModuleInstall {
        public void restored() {
            System.out.println("hello world!");
  7. Run the application again and notice the 'Hello World' message in the application's output, in the Output window, which can be opened from the Window menu. The end of the stack trace, which includes the 'hello world' message, should be something like this:
    Generating Auto Update information for org.mycompany.hello
    hello world!
    >Log Session: Friday, June 27, 2014 5:05:32 PM CEST
    >System Info: 
      Product Version         = HelloWorld-Ant nbms-and-javadoc-1540-on-20140411
      Operating System        = Linux version 3.11.0-23-generic running on i386
      Java; VM; Vendor        = 1.8.0; Java HotSpot(TM) Server VM 25.0-b70; Oracle Corporation
      Runtime                 = Java(TM) SE Runtime Environment 1.8.0-b132
      Java Home               = /home/geertjan/jdk1.8.0/jre
      System Locale; Encoding = en_US (helloworld_ant); UTF-8
      Home Directory          = /home/geertjan
      Current Directory       = /home/geertjan/NetBeansProjects/api-samples/versions/8.0/tutorials/container/HelloWorld-Ant
      User Directory          = /home/geertjan/NetBeansProjects/api-samples/versions/8.0/tutorials/container/HelloWorld-Ant/build/testuserdir
      Cache Directory         = /home/geertjan/NetBeansProjects/api-samples/versions/8.0/tutorials/container/HelloWorld-Ant/build/testuserdir/var/cache
      Installation            = /home/geertjan/NetBeansProjects/api-samples/versions/8.0/tutorials/container/HelloWorld-Ant/build/cluster
      Boot & Ext. Classpath   = /home/geertjan/jdk1.8.0/jre/lib/resources.jar:/home/geertjan/jdk1.8.0/jre/lib/rt.jar:/home/geertjan/jdk1.8.0/jre/lib/sunrsasign.jar:/home/geertjan/jdk1.8.0/jre/lib/jsse.jar:/home/geertjan/jdk1.8.0/jre/lib/jce.jar:/home/geertjan/jdk1.8.0/jre/lib/charsets.jar:/home/geertjan/jdk1.8.0/jre/lib/jfr.jar:/home/geertjan/jdk1.8.0/jre/classes:/home/geertjan/jdk1.8.0/jre/lib/ext/nashorn.jar:/home/geertjan/jdk1.8.0/jre/lib/ext/dnsns.jar:/home/geertjan/jdk1.8.0/jre/lib/ext/sunec.jar:/home/geertjan/jdk1.8.0/jre/lib/ext/localedata.jar:/home/geertjan/jdk1.8.0/jre/lib/ext/sunjce_provider.jar:/home/geertjan/jdk1.8.0/jre/lib/ext/jfxrt.jar:/home/geertjan/jdk1.8.0/jre/lib/ext/sunpkcs11.jar:/home/geertjan/jdk1.8.0/jre/lib/ext/zipfs.jar:/home/geertjan/jdk1.8.0/jre/lib/ext/cldrdata.jar:/usr/java/packages/lib/ext/jpcap.jar
      Application Classpath   = /home/geertjan/netbeans-8.0/platform/lib/boot.jar:/home/geertjan/netbeans-8.0/platform/lib/org-openide-modules.jar:/home/geertjan/netbeans-8.0/platform/lib/org-openide-util-lookup.jar:/home/geertjan/netbeans-8.0/platform/lib/org-openide-util.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/boot_ja.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/boot_pt_BR.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/boot_ru.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/boot_zh_CN.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/org-openide-modules_ja.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/org-openide-modules_pt_BR.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/org-openide-modules_ru.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/org-openide-modules_zh_CN.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/org-openide-util-lookup_ja.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/org-openide-util-lookup_pt_BR.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/org-openide-util-lookup_ru.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/org-openide-util-lookup_zh_CN.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/org-openide-util_ja.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/org-openide-util_pt_BR.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/org-openide-util_ru.jar:/home/geertjan/netbeans-8.0/platform/lib/locale/org-openide-util_zh_CN.jar:/home/geertjan/jdk1.8.0/lib/dt.jar:/home/geertjan/jdk1.8.0/lib/tools.jar
      Startup Classpath       = /home/geertjan/netbeans-8.0/platform/core/core.jar:/home/geertjan/netbeans-8.0/platform/core/org-openide-filesystems.jar:/home/geertjan/netbeans-8.0/platform/core/locale/core_ru.jar:/home/geertjan/netbeans-8.0/platform/core/locale/core_zh_CN.jar:/home/geertjan/netbeans-8.0/platform/core/locale/org-openide-filesystems_ru.jar:/home/geertjan/netbeans-8.0/platform/core/locale/org-openide-filesystems_ja.jar:/home/geertjan/netbeans-8.0/platform/core/locale/org-openide-filesystems_zh_CN.jar:/home/geertjan/netbeans-8.0/platform/core/locale/org-openide-filesystems_pt_BR.jar:/home/geertjan/netbeans-8.0/platform/core/locale/core_ja.jar:/home/geertjan/netbeans-8.0/platform/core/locale/core_pt_BR.jar:/home/geertjan/NetBeansProjects/api-samples/versions/8.0/tutorials/container/HelloWorld-Ant/build/cluster/core/locale/core_helloworld_ant.jar
    INFO [org.netbeans.core.startup.NbEvents]: Turning on modules:
    	org.openide.util.lookup [8.24.1 201403101706]
    	org.openide.util [8.37.1 201403101706]
    	org.openide.modules [7.42.1 201403101706]
    	org.openide.filesystems [8.10.1 201403101706]
    	org.netbeans.bootstrap/1 [2.67.1 201403101706]
    	org.netbeans.core.startup/1 [1.54 nbms-and-javadoc-1540-on-20140411]
    	org.mycompany.hello [1.0 140627]
    BUILD SUCCESSFUL (total time: 18 seconds)

In this tutorial, you have used the least amount of NetBeans Platform modules that any NetBeans Platform application requires, that is, the NetBeans runtime container, consisting of six 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

To continue your journey on the NetBeans Platform, see:

Project Features

Project Links

About this Project

Platform was started in November 2009, is owned by Antonin Nebuzelsky, and has 152 members.
By use of this website, you agree to the NetBeans Policies and Terms of Use (revision 20160708.bf2ac18). © 2014, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo
Please Confirm