This is the common type of application modules. They are loaded on application start. The application loading time is extended by the time of module initialization. Therefore, it is recommended to keep the module initialization very short. Normally it is not necessary to run anything during module loading, as many tasks can be defined declaratively.

These modules are loaded only when another module requires them. Autoload modules correspond to the principle of lazy-loading. This mode is usually used for those modules acting as libraries.

Eager modules are only loaded when all dependencies are met. This is another option to minimize starting time. For example, if module X depends on the modules A and B, which are not available, it makes no sense to load module X.

In the following sections, all attributes of a module manifest are described briefly, each with a short example.

OpenIDE-Module-Requires: org.openide.modules.os.Windows

Listing 3-2 shows a manifest file with some typical attributes.

OpenIDE-Module: com.galileo.netbeans.module
OpenIDE-Module-Public-Packages: -
OpenIDE-Module-Module-Dependencies:
   com.galileo.netbeans.module2 > 1.0,
   org.jdesktop.layout/1 > 1.4,
   org.netbeans.core/2 = 200610171010,
   org.openide.actions > 6.5.1,
   org.openide.awt > 6.9.0,
OpenIDE-Module-Java-Dependencies: Java > 1.5
OpenIDE-Module-Implementation-Version: 200701100122
OpenIDE-Module-Specification-Version: 1.3
OpenIDE-Module-Install: com/galileo/netbeans/module/Install.class
OpenIDE-Module-Layer: com/galileo/netbeans/module/layer.xml
OpenIDE-Module-Localizing-Bundle: com/galileo/netbeans/module/Bundle.properties
OpenIDE-Module-Requires:
   org.openide.windows.IOProvider,
   org.openide.modules.ModuleFormat1

The order in which the entries of the layer file are read (and hence shown in the menu bar) is defined by a position attribute, as shown in Listing 3-4.

<filesystem>
  <folder name="Menu">
    <folder name="Edit">
      <file name="CopyAction.shadow">
        <attr name="originalFile"
                stringvalue="Actions/Edit/org-openide-actions-CopyAction.instance"/>
        <attr name="position" intvalue="10"/>
      </file>
      <file name="CutAction.shadow">
        <attr name="originalFile"
                stringvalue="Actions/Edit/org-openide-actions-CutAction.instance"/>
        <attr name="position" intvalue="20"/>
      </file>
    </folder>
  </folder>
</filesystem>

Thus, the copy action is shown before the cut action. If necessary, you can also use this attribute to define the order of the folder elements. In practice, positions with greater distance are chosen. This facilitates the subsequent insertion of additional entries. Should the same position be assigned twice, a warning message is logged while running the application.

In order to easily position the layer content, the NetBeans IDE offers a layer tree in the Projects window, in which all entries of the layer files are shown. There, their order is defined by drag-and-drop. The respective entries in the layer file are then handled by the IDE.

After we create our first module, the "Creating Modules" section of this chapter shows where to find the layer tree. You determine the order of an action while creating actions with a wizard (see Chapter 4). The respective attributes are then created by the wizard.

Should positions of entries in the layer tree be changed, some entries will be added into the layer file. Those files overwrite the default positions of the entries affected by the change. The position of an entry (also that of entries of a NetBeans Platform module) is overwritten as follows:

<attr name="Menu/Edit/CopyAction.shadow/position" intvalue="15"/>

Use the complete file path of the affected entry before the attribute name position.

Files of the type .instance in the System Filesystem describe objects of which instances can be created. The filename typically describes the full class name of a Java object (e.g., com-galileo-netbeans-module-MyAction.instance), which by a default constructor or static method creates an instance. An instance is created by using the File Systems and Data Systems APIs, as follows:

public static Object getInstance(String name) {
   FileSystem f = Repository.getDefault().getDefaultFileSystem();
   FileObject o = f.getRoot().getFileObject(name);
   DataObject d = DataObject.find(o);
   InstanceCookie c = d.getCookie(InstanceCookie.class);
   return c.instanceCreate();
}

If seeking a more convenient name for an instance, the full class name can be defined by using the attribute instanceClass. Thereby much shorter names can be used:

<file name="MyWindow.instance">
   <attr name="instanceClass" stringvalue="com.galileo.netbeans.module.MyWindow"/>
</file>

In classes not having a parameterless default constructor, create the instance via a static method defined by the attribute instanceCreate:

<file name="MyWindow.instance">
   <attr name="instanceCreate"
           methodvalue="com.galileo.netbeans.module.MyWindow.getDefault"/>
</file>

In doing so, the FileObject of the entry is passed to the getDefault() method, if declared so in the factory method signature. With this FileObject you read self-defined attributes. Assume you want to define the path of an icon or any other resource in the layer file as an attribute:

<file name="MyWindow.instance">
   <attr name="instanceCreate"
           methodvalue="com.galileo.netbeans.module.MyWindow.getDefault"/>
   <attr name="icon" urlvalue="nbres:/com/galileo/icon.gif"/>
</file>

The method getDefault(), creating an instance of the MyWindow class, looks as follows:

public static MyWindow getDefault(FileObject obj) {
   URL url = (URL) obj.getAttribute("icon");
   ...
   return(new MyWindow(...));
}

Notice that we specified the path with a urlvalue attribute type. Therefore, a URL instance is delivered directly. In addition to the already-known attribute types stringvalue, methodvalue, and urlvalue, there are several others. They are accessed in the Filesystem DTD (http://netbeans.org/dtds/filesystem-1_2.dtd).

One or more instances of a certain type can also be generated by Lookup, rather than via an InstanceCookie, as shown previously. Thereby we create a lookup for a particular folder of the System Filesystem. By using the lookup() or lookupAll() method, one or more instances (if several have been defined) can be delivered.

Lookup lkp = Lookups.forPath("MyInstanceFolder");
Collection<? extends MyClass> c = lkp.lookupAll(MyClass.class);

Such a lookup is used in Chapter 5 to extend the context menu of a TopComponent with your own actions defined in the layer file.

The basic class of the interface can be user-defined by the instanceOf attribute in the layer file. This allows a more efficient working of Lookup and avoids Lookup having to initiate each object in order to determine from which base class the class will inherit, or which interface it implements. Lookup is able to create directly only instances of the desired object type.

If the class MyAction from the prior entry implements, for example, the Action interface, we complete the entry as follows:

<file name="com-galileo-netbeans-module-MyAction.instance">
   <attr name="instanceOf" stringvalue="javax.swing.Action"/>
</file>

.shadow files are a kind of link or reference to an .instance file. They are used mainly when singleton instances of objects, as with actions, are used. These are defined by an .instance file in the Actions folder. An entry in the Menu or Toolbars folder then refers to the action by using the .shadow file (see Listing 3-5). A .shadow file refers to files in the System Filesystem as well as to files on disk. In this way, the Favorites module stores its entries. The path to the .instance file is specified by the attribute originalFile.

<folder name="Actions">
  <folder name="Window">
    <file name="com-galileo-netbeans-module-MyAction.instance"/>
  </folder>
</folder>
<folder name="Menu">
  <folder name="Window">
    <file name="MyAction.shadow">
      <attr name="originalFile"
        stringvalue="Actions/Window/com-galileo-netbeans-module-MyAction.instance"/>
    </file>
  </folder>
</folder>

.settings files are an extended version of .instance files in the layer file. Information on the type of class and how an instance is created from this class—i.e., information on what these attributes can determine in an .instance file—is defined in a separate XML file. The main difference to an .instance file is that the complete class hierarchy—i.e., all superclasses and also all implemented interfaces—can be specified in the separate XML file.

These .settings entries are used, for example, with TopComponent s (see Chapter 5). The associated XML file looks like Listing 3-6.

<!DOCTYPE settings PUBLIC
   "-//NetBeans//DTD Session settings 1.0//EN"
   "http://www.netbeans.org/dtds/sessionsettings-1_0.dtd">
<settings version="1.0">
 <module name="com.galileo.netbeans.module" spec="1.0"/>
 <instanceof class="javax.swing.JComponent"/>
 <instanceof class="org.openide.windows.TopComponent"/>
 <instanceof class="com.galileo.netbeans.module.MyTopComponent"/>
 <instance class="com.galileo.netbeans.module.MyTopComponent" method="getDefault"/>
</settings>

The layer file refers to this file by the url attribute, specifying the path relative to the XML file:

<folder name="Windows2">
   <folder name="Components">
      <file name="MyTopComponent.settings" url="MyTopComponentSettings.xml"/>
   </folder>
</folder>

Your module may use folders, files, and attributes from the layer file in order to provide extension points to other modules. The readout of entries is accomplished by accessing the System Filesystem:

Repository.getDefault().getDefaultFileSystem();

This call returns a FileSystem object. Its properties and functionality are described in detail in Chapter 7. The "Window: TopComponent" section in Chapter 5 shows you how to define your own entries in the layer file; it also shows how they can be read and, thereby, how they can provide an extension point for other modules in a way that makes them available to additional modules.

To guarantee compatibility between dependencies, you must define versions. In that regard, there is the major release version, the specification version, and the implementation version. These versions are based on the Java Package Versioning Specification and reflect the basic concepts of dependencies. You can define and edit dependencies in the Properties dialog of modules, which you can access via Properties

First, define the major release version in this window. This is the version notifying the user of incompatible changes, compared to the previous version of the module. Here, the slash is used to separate the code name base from the version within the manifest file:

OpenIDE-Module: com.galileo.netbeans.module/1

Figure 3.7. Setting the module version

The most important version is the specification version. The Dewey decimal system is used to define this version:

OpenIDE-Module-Specification-Version: 1.0.4

The implementation version is freely definable text. Typically, a timestamp is used, providing the date and time. In that way, you determine it is unique. If not explicitly set in the Properties dialog of the module, the IDE adds the implementation version when the module is created, using the current timestamp, set within the manifest file:

OpenIDE-Module-Implementation-Version: 200701231820

On the other hand, if you define your own implementation version in the Properties dialog, the IDE adds the OpenIDE-Module-Build-Version attribute with the current timestamp.

In the list of public packages, all packages in your module are listed. To expose a package to other modules, check the box next to the package you want to expose. In doing so, you define the API of your module. Exposed packages are listed as follows in the manifest file:

OpenIDE-Module-Public-Packages:
   com.galileo.netbeans.module.*,
   com.galileo.netbeans.module.model.*

To restrict access to the public packages (e.g., to allow only your own modules to access the public packages), you can define a module's friends. You define them beneath the list of public packages in the API Versioning section of the Properties dialog. These are then listed as follows in the manifest file:

OpenIDE-Module-Friends:
   com.galileo.netbeans.module2,
   com.galileo.netbeans.module3

Based on these various versions, define your dependencies. To that end, three different types of dependencies are available: a module depends on a module, a package, or a version of Java.

Module Dependencies

You define and edit module dependencies via Properties

NO DEPENDENCY? NO ACCESS!

To use classes from another module, including the NetBeans Platform's own modules, you must first define a dependency, as described in the following sections. That means, if you use a NetBeans Platform class in your module and the code editor cannot find the desired class, the problem can normally be fixed by simply setting a dependency on the module that provides the class.

Figure 3.8. Definition of module dependencies

In this window, use Add Dependency to add dependencies to your module. The NetBeans module system offers different methods to connect dependencies to a particular module.

In the simplest case, no version is required. That means there should simply be a module available, though not a particular version; although where possible you still specify a version:

OpenIDE-Module-Module-Dependencies: com.galileo.netbeans.module2

In addition, you may require a certain version. In this case, the module version should be greater than 7.1. This is the most common manner in which to define dependencies:

OpenIDE-Module-Module-Dependencies: org.openide.dialogs > 7.1

If the module on which you want to depend has a major release version, it must be specified via a slash after the name of the module:

OpenIDE-Module-Module-Dependencies: org.netbeans.modules.options.api/1 > 1.5

Finally, you may also specify a range of major release versions:

OpenIDE-Module-Module-Dependencies: com.galileo.netbeans.module3/2-3 > 3.1.5

To create tight integration to another module, set an implementation dependency. The main reason for this approach is to make use of all the packages in the module, regardless of whether the module has exposed them or not. A dependency of this kind must be set with care, since it negates the principle of encapsulation. To enable the system to guarantee the consistency of the application, the dependency must be set precisely on the version of the given implementation version. However, this version changes with each change to the module.

OpenIDE-Module-Module-Dependencies: com.galileo.netbeans.module2 = 200702031823

Select the required dependency in the list (see Figure 3-8) and click the Edit button. In this window (shown in Figure 3-9), you set various types of dependencies.

Figure 3.9. Editing module dependencies

OpenIDE-Module-Package-Dependencies: javax.sound.midi.spi > 1.4

Java Version Dependency

If the module depends on a specific Java version, such as Java 5, specify that in the module properties under Properties

OpenIDE-Module-Java-Dependencies: Java > 1.5, VM > 1.0

You can require an exact version using the equal sign or require a version that is greater than the specified version.

To achieve the scenario just outlined, create a library wrapper module. The NetBeans IDE provides a project type and a wizard for this purpose. To create a new Library Wrapper project, go to File

Figure 3.11. Creating a Library Wrapper project

Click Next to choose the required JAR files. You can choose one or more JAR files here (hold down the Ctrl key to select multiple JAR files). You are also able to add a license file for the JAR you are wrapping as a module. In the next step, provide a project name, as well as a location to store the new module. Specify the Module Suite or Platform Application to which the library wrapper module belongs. Click Next again to fill out the Basic Module Configuration dialog, as shown in Figure 3-12.

Figure 3.12. Library wrapper module configuration

Here, you define the code name base. Normally this field is prefilled with the name of the JAR file. Provide the module with a name and a localizing bundle (see the "Module Manifest" section earlier in the chapter) to localize the manifest file. With a click of the Finish button, you create your new module project.

When expanding the Source Packages folder in the Projects window, observe that there is only a Bundle.properties file and a manifest file. The library, which is encapsulated by the module, is found in the folder release/modules/ext, which is seen in the Files window.

To understand how a library wrapper module works, take a look at the related manifest file. It's found in the Projects window, within the Important Files file. Note that the following information (in Listing 3-10) may not reflect exactly what is found in your specific manifest file. Certain information, such as the public packages, are only created when you build the project. To see the entire manifest file, create the module and then look at the manifest file within the created JAR file, found in the build/cluster/modules folder of your application. The exposed packages are also seen in the Properties dialog of the library wrapper modules, under the API Versioning tab. There, you can easily hide packages you do not want to have exposed.

Manifest-Version: 1.0
Ant-Version: Apache Ant 1.7.0
Created-By: 1.6.0-b105 (Sun Microsystems Inc.)
OpenIDE-Module: com.hboeck.mp3
OpenIDE-Module-Public-Packages:
   com.hboeck.mp3.*,
   com.hboeck.mp3.id3.*,
   ...
OpenIDE-Module-Java-Dependencies: Java > 1.4
OpenIDE-Module-Specification-Version: 1.0
OpenIDE-Module-Implementation-Version: 070211
OpenIDE-Module-Localizing-Bundle: com/hboeck/mp3/Bundle.properties
OpenIDE-Module-Requires: org.openide.modules.ModuleFormat1
Class-Path: ext/com-hboeck-mp3.jar

Two very important things have been accomplished by the wizard. First, it marked all packages in the third-party library with the attribute OpenIDE-Module-Public-Packages, making all these packages publicly accessible. That's useful because it means the library can now be used by other modules. Second, the wizard marked the library it found in the ext/ folder with the Class-Path attribute, putting it on the module classpath. In this way, the classes in the library can be loaded by the module classloader. The library wrapper module is automatically assigned the Autoload type (see the "Module Types" section near the beginning of the chapter), so that it is only loaded when needed.

It is advisable to always use a library wrapper module when integrating a third-party library into an application. Creating a new module in this way for a third-party library adds to the value and maintainability of the application as a whole, because you can then set dependencies on the library via the module that wraps it.

In some cases, it is desirable to add the third-party library directly to the module using it. Taking this approach is simple and similar to creating library wrapper modules.

Open the Project Metadata file (project.xml) in the Important Files node in your module project, within the Projects window. For each library you want to include in your module, create a class-path-extension entry (see Listing 3-11). Via the runtime-relative-path attribute, define the path where the library is found in the distribution. Before, this was done automatically by the wizard. Use the binary-origin attribute to specify the location where the original library is found. As you see, this is the same approach as taken with library wrapper modules.

<project xmlns="http://www.netbeans.org/ns/project/1">
  <type>org.netbeans.modules.apisupport.project</type>

<configuration>
    <data xmlns="http://www.netbeans.org/ns/nb-module-project/3">
      <code-name-base>com.galileo.netbeans.module</code-name-base>
      <class-path-extension>
        <runtime-relative-path>ext/org-hboeck-mp3.jar</runtime-relative-path>
        <binary-origin>release/modules/ext/org-hboeck-mp3.jar</binary-origin>
      </class-path-extension>
    </data>
  </configuration>
</project>

Via this entry in the project metadata file, the creation of the module results in the library being copied to the ext/ folder. In the manifest file, the entry Class-Path: ext/com-hboeck-mp3.jar is added. In contrast to a library wrapper module, the packages of the library are not exposed. As a result, they can only be used by the module where the library is found, which is normally the reason for taking this approach in the first place. It is also possible to define the packages as being public, which is automatically the case with library wrapper modules.