Updating a NetBeans Platform Application Let’s Allow the ...

thrillukrainianΛογισμικό & κατασκευή λογ/κού

7 Ιουν 2012 (πριν από 5 χρόνια και 5 μήνες)

929 εμφανίσεις

219
■ ■ ■
C H A P T E R 1 2
Updating a NetBeans Platform
Application
Let’s Allow the User to Add
Features at Runtime!
T
his chapter covers updating applications already distributed to end users. This is done by
providing new or updated modules in one of several different ways. The focus of this chapter is
on the creation, architecture, and distribution of update packages.
Overview
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 architec-
tures 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.
The Auto Update Service
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
220 CHAPTER 12

UPDATI NG A NETBEANS PLATFORM APPLI CATI ON
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
The NBM File
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 configura-
tion 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.
CHAPTER 12

UPDATI NG A NETBEANS PLATFORM APPLI CATI ON 221
Figure 12-2. Content of an NBM file
Listing 12-1. The NBM information 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 ➤ Plugins).
Open the Keystores Manager via Tools ➤ Keystores. Next, create a keystore file via Add
Keystore, including a file name and location where the keystore is located. A recommended
location is the nbproject/private folder of your module (see Figure 12-3). After entering a
password of at least six characters, click OK to create the keystore.
222 CHAPTER 12

UPDATI NG A NETBEANS PLATFORM APPLI CATI ON
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
CHAPTER 12

UPDATI NG A NETBEANS PLATFORM APPLI CATI ON 223
➤ Project Properties). If this file does not exist, create it. Use the keystore key to define the path
to the keystore relative to the module project folder. Use the nbm_alias key to set the alias for
the key pair to be used, since one keystore may contain multiple key pairs.
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 ➤
Per-user Project Properties) as follows:
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.
Update Centers
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.
Listing 12-2. Update center descriptor
<?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"
224 CHAPTER 12

UPDATI NG A NETBEANS PLATFORM APPLI CATI ON
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 abso-
lute 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.
Localized NBM Files
In Chapter 10, localizing the language-specific content of modules was explained. Two varia-
tions 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.
CHAPTER 12

UPDATI NG A NETBEANS PLATFORM APPLI CATI ON 225
Configuring and Installing on the Client
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 ➤
Plugins. There, in the Settings tab (see Figure 12-5), update centers are defined. The URL of an
update center must point to the location of the update center descriptor (see Figure 12-3). In
the same way, update centers may be deactivated, thereby excluding them from the update
process.
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.
226 CHAPTER 12

UPDATI NG A NETBEANS PLATFORM APPLI CATI ON
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 ➤ New File ➤ Module Development ➤ Update Center. The wizard
registers update center information, consisting of the name and URL of the update center
descriptor. This information is registered in the layer file, within the Services/AutoupdateType
folder. Registration entries of this kind appear as follows:
<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"/>
CHAPTER 12

UPDATI NG A NETBEANS PLATFORM APPLI CATI ON 227
</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
Automatically Installing Updates
An NBM file may also be installed without requiring user interaction. Put the NBM file in the
update/download folder of a cluster. The update is installed when the application is next started,
after which the NBM file is removed and the application is started afresh. Backups of original
versions of the updated modules are found in the update/backup/netbeans folder. Remember,
the update is always installed in the cluster where the update is stored, even if the module that
should be updated is installed in a different cluster.
As of NetBeans 6.0, the Auto Update Services API and SPI are public and can be used by
your own Platform Application to programmatically automate and adapt module installations,
as well as the related update processes. More information on this NetBeans API can be found
in the Javadoc.
Summary
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.