The Core Platform

The Module System API

Before we start describing the NetBeans Module System API, let’s see some definitions and characteristics of modular systems in general.

Modularization is the act of decomposing a system into self-contained modules. Modules are identifiable artifacts containing code, with metadata describing the module and its relation to other modules. A modular application, in contrast to a monolithic one of tightly coupled code, in which every unit may interface directly with any other, is composed of smaller, separate chunks of code that are well isolated.

It provides a way to divide your application into cohesive parts and helps you build loosely coupled applications that can evolve without breaking. It also lets you add/remove features during runtime(!) without breaking your application.

The Runtime Container consists of the minimum modules required to load and execute your application and manages all of the modules in your application.

Figure 7-2 shows an explicit dependency of Module A to Module B.

Usually you put public interfaces of a module into a public package.

In other words, a module in the NetBeans Module System cannot reference classes in another module without declaring a dependency on that other module, and with that other module agreeing that the classes referenced are the ones that are the actual API of this module. This way you can design applications with high cohesion and low coupling.

All modules have a life cycle, which you can hook into via annotations. Thus, you can execute code when a module starts, shuts down, and when the window system initializes.

Figure 7-3 shows the relationships between these modules.

Lookup API

NetBeans uses a component-based way of development. Modules or components developed by independent groups or individuals must be able to communicate with each other in a loosely-coupled way.

Previously we learned about how the Module System allows you to break up your application into loosely coupled parts. These modules need a loosely coupled way to communicate with each other, too. This is where the Lookup API fits in.

One of the biggest challenges in the history of software design is how to design loosely-coupled systems with high cohesion. “In computing and systems design a loosely coupled system is one in which each of its components has, or makes use of, little or no knowledge of the definitions of other separate components,” according to Wikipedia (https://en.wikipedia.org/wiki/Loose_coupling).

Cohesion means that all code (and resources) related to a particular feature should be organized within the same module or the same set of modules. Coupling , on the other hand, refers to the degree to which the modules depend on each other. Modules should be independent of each other, as much as possible, enabling components to be modified or moved around without a big impact on the application. The higher the level of cohesion and the lower the level of coupling, the more sustainable and robust with respect to future modifications (less maintenance headache) the architecture is.

Let’s assume that the Client and the ProviderImpl exist in two different modules (see Figure 7-4). How does the Client find the ProviderImpl (in a loosely coupled way)? Spring uses dependency injection or inversion of control via its xml files. Java 6 uses a Query-based approach, the ServiceLoader that we briefly describe later in this chapter.

NetBeans RCP introduces a new way to accomplish loose coupling, the @ServiceProvider:

@ServiceProvider(service = Provider.class, position=1)

public class ProviderImpl implements Provider { }

The magic line is the first line that tells NetBeans that this class is an implementation of the service Provider.class. NetBeans creates a text file package.Provider inside build/classes/META-INF/services/ folder of the module that contains the fully qualified names of the implementation classes, for example, package.ProviderImpl. If you have worked with ServiceLoader, then this is not new to you.

However, the big question has not been answered yet. How does the client find the implementation? In NetBeans this is done with the use of lookups! The client looks in the default lookup for the interface (not the implementation). The default Lookup (also known as service registry ) is a Lookup that evaluates the service declarations in the META-INF/services folder. It is callable through the Lookup.getDefault() method . By asking for a service interface in this way, you receive instances of implementing classes registered in the META-INF/services folder.

for example: Map<String, Set<String>> or Map<Provider, Set<Provider>>.

It was created to allow for inter-component binding and dependencies.

As you can see from the above code examples, the client has no clue about which implementation it uses; it only knows the interface. Loose coupling!

Imagine the lookup as a map in memory that stores implementations of all the services of your application. You put the service implementation in the lookup when you define it with the @ServiceProvider annotation , and then you search for it using the above commands. Service implementations can be in different modules and in non-public packages.

NetBeans also allows you to order implementations by ascending positions, that is, instances with smaller numbers in the position attribute of the @ServiceProvider annotation are returned before instances with larger numbers.

We have seen two attributes of the @ServiceProvider annotation, service and position. There are two more, not that commonly used: path, a path in the System FileSystem where the provider is registered; and supersedes, a list of implementations, which this implementation supersedes.

The NetBeans Module System API versus the Java 9 Module API

The purpose was to make Java SE more flexible, scalable, maintainable, and secure; make it easier to construct, maintain, deploy, and upgrade applications; and enable improved performance.

How do you access a class from another package while preventing other classes from using it? You can only make the class public, thus exposing it to all other classes (i.e., break encapsulation). There are no explicit dependencies; explicit import statements are only at compile time; there is no way to know which other JAR files your JAR requires at runtime; the developer has to provide correct jars in the classpath during execution and in the correct order.

Maven solves compile-time dependency management by defining POM (Project Object Model) files (Gradle works in a similar way). OSGi solves runtime dependencies by requiring imported packages to be listed as metadata in JARs, which are then called bundles .

Once a classpath is loaded by the JVM, all classes are sequenced into a flat list, in the order defined by the classpath argument. When the JVM loads a class, it reads the classpath in fixed order to find the right one. As soon as the class is found, the search ends and the class is loaded. What happens when duplicate classes are in the classpath? Only one (the first one encountered) wins. The JVM cannot efficiently verify the completeness of the classpath upon starting. If a class cannot be found in the classpath, then you get a runtime exception. The term “Classpath Hell” or “JAR Hell” should now be clearer to you.

With project Jigsaw, Java now has its one module system. Modules can either export or strongly encapsulate packages. Modules express dependencies on other modules explicitly. Each JAR becomes a module, containing explicit references to other modules. A module has a publicly accessible part and an encapsulated part. All this information is available at compile time and runtime accidental dependencies on code from other non-referenced modules can be prevented. Optimizations can be applied by inspecting transitive dependencies.

As a consequence, JDK now consists of 19 platform modules.

As already mentioned in Chapter 3, a module has a name (e.g., java.base), groups related code and possibly other resources, and is described by a module descriptor . Like packages are defined in package-info.java, modules are defined in module-info.java (in root package). A modular jar is a jar with a module-info.class inside it. In Chapter 3, we also saw how NetBeans provides support for Java 9 modules.

As already described, both modular systems provide support for encapsulation and exporting public interfaces and explicitly handle dependencies while both don’t allow cyclic dependencies. Java 9 doesn’t allow cyclic dependencies during compile time, but it does during runtime. The Java 9 module system doesn’t support versioning, something that has been criticized by the Java community.

ServiceProvider does not have the drawbacks of ServiceLoader. It is dynamic, so you can plug in/unplug modules while your application is running, it doesn’t load all services at startup, and it allows you to set priorities (with the position attribute). It is extensible, supports listeners, understands the NetBeans platform module system, and one can create as many Lookups as they wish (there can be only one instance of ServiceLoader per classloader).

As we saw, both module systems have their pros and cons. NetBeans Module System API can also work outside of NetBeans; just use the related JAR files (they can be found inside platform/lib folder of your NetBeans IDE installation): boot.jar, core.jar, org-openide-filesystems.jar, org-openide-modules.jar, and org-openide-util.jar.

Don’t mix up module systems, that is, don’t use both Jigsaw and NetBeans Module System in your project. It will unnecessarily complicate things, and it won’t give any extra benefit to your application.

The File System API

The NetBeans Platform File System API provides an abstraction for standard files. The File System API handles both files and folders (you can think of them as resources) on the physical file system as well as on the NetBeans virtual file system (e.g., they may reside in memory, in a JAR or ZIP or XML file, or even on a remote server).

A FileSystem is a collection of FileObjects that can reside anywhere. A FileSystem is hierarchical and has a root. A FileObject represents either a file or a directory (folder) in the FileSystem; it must physically exist in the FileSystem (unlike Java’s java.io.File) and has a MIME type, which determines how the file is handled. A FileObject is an implementation of the Composite design pattern, that is, it can contain other FileObjects (files or subdirectories). A FileObject also includes support for attributes (which are key-value pairs or type String).

You may listen for changes to a FileObject (such as file/folder creation, renaming, modification, deletion, or attribute changing) with the FileChangeListener interface . Finally, FileUtil is a utility class with many methods that manipulates FileSystems, FileObjects, and even standard java.io.File objects .

A summary of the above is depicted in Figure 7-5 in a graphical way.

An Example Application

Let’s try to apply what we have learned so far by porting a Swing ToDo application to NetBeans RCP. If you wish to download the ToDo Swing application and build it yourself, please proceed; otherwise you may skip to the section of this chapter “The Todo Swing Application.” You may also find the fixed version in the book’s source code.

Build the Todo Swing Application

Download the original Swing application from here (http://netbeans.org/community/magazine/code/nb-completeapp.zip), unzip it, and open it in NetBeans. Since this is a rather old application, you will encounter a number of problems. Press the Resolve Problems button to get a list of the problems. Click Resolve… in order for NetBeans to try to resolve them.

NetBeans will resolve the first and the last as shown in Figure 7-6. The other two need to be resolved manually. Follow the instructions in this FAQ (http://wiki.netbeans.org/FaqFormLayoutGenerationStyle) to resolve the “swing-layout” library issue.

Download hsqldb.zip (from http://hsqldb.org), create a lib folder inside TodoNB5, and copy in there the hsqldb.jar file from hsqldb.zip. Right-click on Libraries and select Add JAR/folder… from the pop-up menu. Navigate to the lib folder and select the hsqldb.jar (make sure you have relative path selected).

You should now be able to run it. When you run it, you should see the error in the status bar: “Cannot fetch from the database”. This is due to the version of HSQLDB. Open TaskManager.java, locate method listTasksWithAlert() , and replace curtime() with CURRENT_TIMESTAMP. Rerun the application. You should now be able to see a window with empty tasks.

The Todo Swing Application

As you can see in Figure 7-7, the application consists of two windows. The main window provides a list of tasks. The Task Details dialog box allows the user to create a new or edit an existing task.

Here is a short list of requirements of the application:

• Tasks should have a priority, so users can focus first on higher-priority tasks.

• Tasks should have a due date, so users can instead focus on tasks that are closer to their deadline.

• There should be visual cues for tasks that are either late or near their deadlines.

• Tasks can be marked as completed, but this doesn’t mean they have to be deleted or hidden.

There are two main windows for the Todo application: a tasks list and a task-editing form. A rough sketch for both is shown in Figure 7-8.

The Todo application is going to be developed in three steps:

• Step 1. Build a “static” visual prototype of the user interface, using a visual GUI builder.

• Step 2. Build a “dynamic” prototype of the application, coding user interface events and associated business logic, and creating customized UI components as needed.

• Step 3. Code the persistence logic.

It consists of three packages: todo.model, todo.view, todo.controller (see Figure 7-9).

As shown in Figure 7-10, the Swing ToDo application follows the Model-View-Controller architecture.

We shall create a similar architecture using the NetBeans platform module system, using modules instead of packages (see Figure 7-11).

Let’s get started. Click on the New Project toolbar button and select the NetBeans Platform Application in the NetBeans Modules category (see Figure 7-12). Use “TodoRCP” as the project name and choose a suitable project location. Then click Finish.

NetBeans creates the NetBeans Platform Application project containing an empty Modules folder and an Important Files folder. This is the container for the modules that will be created in the rest of this part of the book. We shall create the same Model-View-Controller structure for our TodoRCP application.

Right-click the Modules folder icon and choose Add New. Type "View" as the module name and click Next. Type todo.view as the Code Base Name and then click on Finish. You should see the structure shown in Figure 7-13.

Create the other two modules, "Model" (todo.model) and “Controller” (todo.controller), the same way. Finally, create a new module called “Libraries” that will wrap any external libraries required by the application.

Having one module that includes all the applications’ external libraries has the benefit that we need to add only one new module to our module suite and a single reference to it from the modules that need it. The drawback is that if a module needs only one jar, it needs to reference all other jars that are wrapped inside the Libraries module.

We shall wrap two java libraries (a.k.a. jar files) inside this module: the hsqldb.jar that we downloaded earlier in this chapter, and the SwingX library that is not included any longer in the ide/modules/ext/ folder. Download it instead from here (https://mvnrepository.com/artifact/org.swinglabs.swingx/swingx-all).

Let’s create the module and add the external libraries that we will need for the TodoRCP application:

1. 1.

   Right-click the Modules folder icon of the TodoRCP module suite and choose Add New. Type Libraries as the module name and click Next. Type lib as the Code Base Name and then Finish.

    
2. 2.

   Right-click on the newly created module and select Properties ➤ Libraries ➤ Wrapped JARs. Click on Add JAR and add the swingx-all-x.x.x.jar. Repeat the procedure to the add hsqldb.jar.

    
3. 3.
   Select the API Versioning category from the left panel of the opened Project Properties ➤ Libraries dialog box and make the following packages public by checking them:

   • org.hsqldb

   • org.jdesktop.swingx

    
4. 4.

   After clicking on OK, clean and build the Libraries module.

    

The TodoRCP module suite should now contain four modules (see Figure 7-14).

There is a plugin to visualize the dependencies between modules. Download the DisplayDependencies plugin from https://sourceforge.net/projects/netbeansmoddep/. Click on Tools ➤ Plugins menu and then on the Downloaded tab. Click on the Add Plugins… button and navigate to the location that you saved the downloaded 1475781757_eu-dagnano-showdependencies.nbm file. Click on Install button and follow the wizard to install the plugin. A new button with tooltip Show Dependencies is displayed on the toolbar. Click on a module or on the module suite and then on the Show Dependencies button to view a graph like the one in Figure 7-11 (without all the dependencies yet).

Copy the Task.java from the ToDo Swing application to the todo.model package of the Model module. To ease our development, we shall use a mock TaskManager that stores the tasks to memory instead of the database.

The TaskManager class is a DAO (Data Access Object). Being the only DAO on the application, it contains many methods that would otherwise be in an abstract superclass. Its implementation is very simple, so there’s lots of room for improvement. We can extract the following interface in Model module based on the persistent TaskManager of the original article. Copy TaskManager from ToDo application, inside the todo.model package of the Model module. Select the class name inside the editor and click on menu Refactor ➤ Extract Interface. Select only the methods shown in Figure 7-15.

You may adapt it a bit to look like the code in Listing 7-11.

package todo.model;

import java.util.List;

public interface TaskManagerInterface {

    void addTask(Task task) throws ValidationException;

    void updateTask(final Task task) throws ValidationException;

    void removeTask(final int id);

    List<Task> listAllTasks(boolean priorityOrDate);

    List<Task> listTasksWithAlert() throws ModelException;

    void markAsCompleted(final int id, final boolean completed);

}

Listing 7-11

TaskManagerInterface

Copy ValidationException and ModelException classes from the ToDo application to resolve the errors, too. Click now on the bulb on the left of the TaskManagerInterface name and select Implement Interface. Give it the name TaskManager and click OK. NetBeans generates a skeleton implementation. Refactor-move it to a new package todo.model.impl. It is a good strategy to implement TaskManager as a service provider of the TaskManagerInterface service (Listing 7-12).

package todo.model.impl;

import java.util.*;

import todo.model.ModelException;

import todo.model.Task;

import todo.model.TaskManagerInterface;

import todo.model.ValidationException;

import org.openide.util.lookup.ServiceProvider;

@ServiceProvider(service = TaskManagerInterface.class)

public class TaskManager implements TaskManagerInterface {

    private final List<Task> tasks = new ArrayList<>();

    public TaskManager() { // mock data

        final GregorianCalendar cal = new GregorianCalendar(TimeZone.getTimeZone("Europe/Athens"));

        cal.set(2019, Calendar.JULY, 2, 10, 00, 00);

        tasks.add(new Task(1, "Hotel Reservation", 1, cal.getTime(), true));

        cal.set(2019, Calendar.JULY, 15, 16, 30, 00);

        tasks.add(new Task(2, "JCrete 2019", 1, cal.getTime(), true));

        cal.set(2019, Calendar.JULY, 5, 12, 45, 00);

        tasks.add(new Task(3, "Reserve time for visit", 2, cal.getTime(), false));

    }

    @Override

    public List<Task> listAllTasks(final boolean priorityOrDate) {

        Collections.sort(tasks, priorityOrDate ? new PriorityComparator() : new DueDateComparator());

        return Collections.unmodifiableList(tasks);

    }

    @Override

    public List<Task> listTasksWithAlert() throws ModelException {

        final List<Task> tasksWithAlert = new ArrayList<> (tasks.size());

        for (Task task : tasks) {

            if (task.hasAlert()) {

                tasksWithAlert.add(task);

            }

        }

        return Collections.unmodifiableList(tasksWithAlert);

    }

    @Override

    public void addTask(final Task task) throws ValidationException {

        validate(task);

        tasks.add(task);

    }

    @Override

    public void updateTask(final Task task) throws ValidationException {

        validate(task);

        Task oldTask = findTask(task.getId());

        tasks.set(tasks.indexOf(oldTask), task);

    }

    @Override

    public void markAsCompleted(final int id, final boolean completed) {

        Task task = findTask(id);

        task.setCompleted(completed);

    }

    @Override

    public void removeTask(final int id) {

        tasks.remove(findTask(id));

    }

    private boolean isEmpty(final String str) {

        return str == null || str.trim().length() == 0;

    }

    private void validate(final Task task) throws ValidationException {

        if (isEmpty(task.getDescription())) {

            throw new ValidationException("Must provide a task description");

        }

    }

    private Task findTask(final int id) {

        for (Task task : tasks) {

            if (id == task.getId()) {

                return task;

            }

        }

        return null;

    }

    private static class PriorityComparator implements Comparator<Task> {

        @Override

        public int compare(final Task t1, final Task t2) {

            if (t1.getPriority() == t2.getPriority()) {

                return 0;

            } else if (t1.getPriority() > t2.getPriority()) {

                return 1;

            } else {

                return -1;

            }

        }

    }

    private static class DueDateComparator implements Comparator<Task> {

        @Override

        public int compare(final Task t1, final Task t2) {

            return t1.getDueDate().compareTo(t2.getDueDate());

        }

    }

}

Listing 7-12

TaskManager as a service provider

Don’t hesitate to create the new Task constructor. To resolve the error of the ServiceProvider, click on the bulb and select Search Module Dependency for ServiceProvider. The dialog box of Figure 7-16 will be displayed, which will prompt you to select the (surprise, surprise) Lookup API.

You just added a new dependency from your Model module to the Lookup API module.

Clean and build your module to resolve any errors.

In the Files tab, expand the Model module as shown in Figure 7-17 to verify that a new file META-INF/services/todo.model.TaskManagerInterface has been created, which contains the various implementations of the service, in our case todo.model.impl.TaskManager.

TaskManagerDB will be another service provider of TaskManagerInterface . In the next chapter, we shall see how we can use these services. Please notice that TaskManager or TaskManagerDB may exist in other modules of your application, and in non-public packages.

As an exercise, you may wish to refactor these two classes to use Java 8 syntax and libraries, for example, the new java.time.* classes and/or lambdas/streams.

Finally, we need to expose the todo.model package to other modules so that when other modules add dependencies to the Model module, they can access the classes inside this public package. Right-click on the Model module, select Properties | API Versioning, and check the todo.model package from the Public Packages section to make it public (see Figure 7-18). Clean and build the Model module.

In the next chapter we shall see how to add dependencies between modules.

For an overview of the NetBeans platform modules, right-click on the TodoRCP module suite, select Properties, and click on the Libraries category. Expand the platform node to view a list of all platform modules included or not to your application.

Before we close this chapter, we shall take a brief look at the System FileSystem or layer.xml we described earlier.

To generate the layer.xml file, select the View module, right-click and select New ➤ Other from the context menu, then the Module Development category and the XML Layer file type. Follow the wizard and you will see a new layer.xml file created in the module’s Source Package. In the Projects window, expand it,¹ and you will see <this layer> and <this layer in context> (see Figure 7-19). Entry <this layer> refers to configuration information in this module, and entry <this layer in context> refers to the entire application (in other words, it combines all layer.xml file contents of all the modules of the application, that is, it is the System FileSystem). You will notice that layer.xml for our module is empty and only contains <filesystem/>. The layer.xml file consists of four main tags: <filesystem>, <folder>, <file>, and <attr>.

One can access/create objects in the layer.xml using the FileSystem API that was described earlier in this chapter.

We shall learn how we can customize our application by editing this file in the next chapter.²