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.
Contents
- Introduction to the Runtime Container
- Setting up the Runtime Container
- Loading a New Module into the Runtime Container
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.
Go to File > New Project. In the New Project dialog, choose NetBeans Modules > NetBeans Platform Application:
Click Next.
- Name your application 'HelloWorld' and specify where to store it:
Click Finish. You now have your first NetBeans Platform application:
- 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:
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.
- 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:
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:
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.
Right-click the application's Modules node and choose 'Add New...'.
Give your module a project name, such as 'HelloModule' and specify a location to store the module:
Click Next.
- Specify a code name base, which is a unique string
that identifies the module:
Click Finish. You now have a new module:
- Right-click the module, choose New > Other, and then choose
Module Development > Installer/Activator:
Click Next.
- Click Finish below to complete the wizard:
You now have a new class that extends the NetBeans ModuleInstall class, which is from the Module System API.
- 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 { @Override public void restored() { System.out.println("hello world!"); } } - 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:
org.mycompany.hello.netbeans: Generating Auto Update information for org.mycompany.hello run: run.run: 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 /home/geertjan/netbeans-8.0/platform /home/geertjan/netbeans-8.0/platform 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:
