During software lifecycles, it is quite common for users to request patches when experiencing unexpected error messages. In addition, development teams often want to make new features available between one release and the next. It would be cumbersome to redistribute the entire application when providing a patch or a new feature. A major advantage of modular architectures is its support for the distribution of modules that provide patches or updates for existing applications.

For the user, installation of updates must be as simple and intuitive as possible. To that end, the NetBeans Platform provides an Auto Update service connected to the Plugin Manager. The Plugin Manager automatically searches for updated or new modules in a set of predefined update centers, dynamically loading them at runtime. Additionally, users are able to manually install downloaded updates or new modules into the Plugin Manager.

Updates are made available as NBM files. These update packages are offered via an update center (see Figure 12-1). Within a NetBeans Platform application, users register update centers in the Plugin Manager so that the Auto Update service can search those centers for changes.

The registration of update centers in the Plugin Manager is done manually by users or by a module that automatically registers the update centers. Users configure the application so that update centers are polled periodically for changes. Users may manually initiate this update task as well.

Figure 12.1. Components making up Auto Update functionality and their dependencies

Modules available as update packages are distributed in the form of NBM files. A file of this type is a JAR archive containing the actual module, together with its configuration data and update information required by the Plugin Manager (see Figure 12-2). It may also contain the libraries required by the module. The contents of the module JAR file and its related configuration files are described in Chapter 3.

One file we haven't yet discussed is the info.xml file. This file contains information displayed to the user when choosing modules in the Plugin Manager. The manifest element (see Listing 12-1) provides information from the module's manifest file, such as dependencies that must be met for the module to be installed. If the user chooses to download a module dependent on another module, the latter is automatically activated, so it can be downloaded simultaneously with the selected module. If dependencies cannot be satisfied, the user installs the module without being able to activate it.

License information may be added here, too, via the license element, which the user finds in the Plugin Manager before installation of the module begins. This forces the user to confirm that licensing requirements have been satisfied and the module can be installed.

Figure 12.2. Content of an NBM file

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module PUBLIC
   "-//NetBeans//DTD Autoupdate Module Info 2.5//EN"
   "http://www.netbeans.org/dtds/autoupdate-info-2_5.dtd">
<module codenamebase="com.galileo.netbeans.module"
        distribution="./com-galileo-netbeans-module.nbm"
        downloadsize="7123"
        homepage="http://heikoboeck.de"
        license="AD9FBBC9"
        moduleauthor="Heiko Boeck"
        needsrestart="false"
        releasedate="2009/03/11">
   <manifest AutoUpdate-Show-In-Client="true"
             OpenIDE-Module="com.galileo.netbeans.module"
             OpenIDE-Module-Name="My Module"
             OpenIDE-Module-Implementation-Version="090311"
             ...
             OpenIDE-Module-Specification-Version="1.0"/>
   <license name="AD9FBBC9">Place your license information here
   </license>
</module>

An NBM file is created automatically by the NetBeans IDE. Right-click a module in the Projects window and choose Create NBM.

When you choose Create NBM, the IDE attempts to sign the NBM file. To make this possible, a keystore must be prepared and generated. Use the Keystores Manager in the IDE, which is only available after installation of the Mobility plugin. This is part of the full as well as the Java IDE distribution. The easiest way is to install this plugin over the Plugin Manager (Tools

Open the Keystores Manager via Tools

Figure 12.3. Creating a keystore

The newly created keystore must be provided with a key pair, with which the NBM file is signed. In the Keystores Manager, choose the keystore and then click the New button. The next dialog provides an alias, as well as certificate details, such as organization name (see Figure 12-4). Provide the same password as when creating the keystore. Next, click OK to close the dialog, which creates the key pair in the keystore.

Figure 12.4. Creating a key pair

To enable the IDE to find the keystore and key pair, define the following properties in the nbproject/project.properties file (found within the Projects window, under Important Files

keystore=nbproject/private/keystore.ks
nbm_alias=mymodule

Now invoke the Create NBM menu item again, which lets the IDE sign the NBM file. A dialog is shown for entering the password assigned to the keystore. Enter the correct password, enabling successful signature.

If you don't want to enter this password every time, you may define it in the nbproject/private/private.properties file (found in the Projects window, under Important Files

storepass=mypassword

Now, in the Plugin Manager, the user will see the module certificate, after downloading the selected module is completed, but before the installation process begins. Be aware that a warning will show that the module is not trusted. To prevent this, provide an official certificate from an official certificate vendor, such as VeriSign.

NBM files—that is, updates for a distributed application—are put into an update center, from which they can be downloaded. An update center is nothing more than a storage place where the module is placed, generally on a server accessible via the Internet. Use an update center descriptor, in the form of an XML file, to describe the module location and other details. In this way, the Auto Update service finds the module, while determining whether the module is updated or new.

The update center descriptor lists the content of the info.xml file (explained in the previous section) for each of the NBM files in the update center. As a result, the Auto Update service of the application need not open or download an NBM file to determine its version.

The license element is defined outside the module element (see Listing 12-2) to provide license information for multiple modules concurrently, while ensuring only one license is shown to the user. Multiple use of the license element is possible as well, providing a separate license for each module.

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE module_updates PUBLIC
   "-//NetBeans//DTD Autoupdate Catalog 2.5//EN"
   "http://www.netbeans.org/dtds/autoupdate-catalog-2_5.dtd">
<module_updates timestamp="08/54/21/11/03/2009">
   <module codenamebase="com.galileo.netbeans.module"
           distribution="./com-galileo-netbeans-module.nbm"
           ...
   </module>
   <module codenamebase="com.galileo.netbeans.module2"

distribution="./com-galileo-netbeans-module2.nbm"
           ...
   </module>
   <license name="AD9FBBC9">Place your license information here</license>
</module_updates>

The root element of the update center descriptor is the module_updates element. The module_updates element contains the timestamp attribute, which the Auto Update service compares with a timestamp obtained from previous connection to the update center. The Auto Update service reads an update center only when the timestamp date is more recent than the date of the last connection.

Optionally, modules may be grouped in the update center descriptor, via the module_group element. This allows modules to be displayed as a group in the Plugin Manager. In the module element, the distribution attribute is very important. It defines the location from which the module will be downloaded. Rather than a relative location, as shown in Listing 12-2, an absolute URL can be provided, pointing to the location of the module.

The address of an update center descriptor is defined as a URL in the update center settings in the Plugin Manager. The update center descriptor need not be manually created. Right-click the application project in the Projects window and choose Create NBMs. Aside from generating an individual NBM file for each module, an XML file named updates.xml is created. The updates.xml file is the update center descriptor. The NBMs and the update center descriptor are found in the build/updates folder, visible in the Files window.

In Chapter 10, localizing the language-specific content of modules was explained. Two variations were discussed. First, localized resources can be placed directly within the module. Second, they are put in a JAR file and that file in the locale folder. In both cases, assume the developer has access to the module or to the application of which the module forms a part. It is possible to provide a localizing bundle for an application that has already been distributed.

Additional localizing bundles for an already distributed module are simple to create. Do this by creating an updated or new module and making it available via an update center. The only difference is that the manifest element in the info.xml file and in the update center descriptor are supplemented by the l10n element. The structure is as follows:

<l10n langcode="de"
      module_major_version="1"
      module_spec_version="1.0"
      OpenIDE-Module-Name="Mein Modul"
      OpenIDE-Module-Long-Description="German localization of My Module."/>

Use the langcode attribute to define the language for the NBM file. With version attributes, you define versions that the NBM file targets. The localizing bundle is activated only when localizing bundle versions match those of the installed module.

To enable an application to connect to new or updated modules in an update center, the update center must be registered in the Plugin Manager, which can be opened via Tools

Figure 12.5. Configuring an update center

When switching to the Updates tab, use the Reload Catalog button to allow the Auto Update service to look for modules in the defined update centers. Updated versions of modules are sought for those modules that are already installed in the application. For new modules, use the same approach in the Available Plugins tab. Found modules are displayed immediately in a list, from which you can select those you need. Use the Update or Install buttons to add selected modules to the application.

Modules that are locally available—that is, those that are personally downloaded—can be installed as well. Switch to the Downloaded tab, and then click Add Plugins to open NBM files from disk into the Plugin Manager. Finally, click Install to install the selected modules.

The last tab discussed is the Installed tab (see Figure 12-6). All currently installed modules are listed there, organized into categories. You can deactivate modules here, as well as completely uninstall them.

Figure 12.6. The Installed tab lists all installed modules, where they can be activated and deactivated.

New Update Center

As pointed out, users may register update centers in the application's Plugin Manager. Rather than by manual approach, you can add update center information to an existing or new module. Once this module is installed, the registered update centers become automatically available. As a result, a module may be provided that adds new update centers to an already distributed application.

To this end, choose File

<folder name="Services">
   <folder name="AutoupdateType">
      <file name="my_module_update_center.instance">
         <attr name="SystemFileSystem.localizingBundle"
                 stringvalue="com.galileo.netbeans.module.Bundle"/>
         <attr name="enabled" boolvalue="true"/>
         <attr name="instanceCreate" methodvalue=
                 "org.netbeans.modules.autoupdate.updateprovider.
                 AutoupdateCatalogFactory.createUpdateProvider"/>
         <attr name="instanceOf"
                 stringvalue="org.netbeans.spi.autoupdate.UpdateProvider"/>
         <attr name="url_key" stringvalue="my_module_update_center"/>

</file>
   </folder>
</folder>

Data referenced in the registration entries is saved centrally in the resource bundle for localizing purposes:

my_module_update_center = http://heikoboeck.de/updates.xml
Services/AutoupdateType/my_module_update_center.instance = My Update Center

This chapter has introduced you to the update facilities in the NetBeans Platform. Firstly, you saw how the Auto Update service works. An NBM file is an update package and can be created from your module by the NetBeans IDE. Next, you learned how to provide and configure update centers. You also saw how a module is configured to provide a localized version of an existing module. Finally, we dealt with the configuration of update centers on the client side and how updates can be installed automatically.