Understanding AutoUpdate Descriptors

Introduction

The NetBeans platform supplies the AutoUpdate functionality. This feature makes possible to distribute new features and keep the product up-to-date. The AutoUpdate consists of Update Center and a client in NetBeans. Update Center (commonly on some web server) offers an set of updates and the AutoUpdate client connects this Update Center and allow an user select, download and install some of them.

Update Center is described by XML file (call a catalog or Update Center Descriptor). I would like to show to you the structure of catalog, meaning of its elements and attributes, optional use-cases of attributes.

Structure of the catalog

The catalog contains from modules which can be organized into groups of modules, licenses and some others elements which are not currently used.

The basic element of the catalog is module. More modules can but may not be a module group. Modules can be publish with a license thus license are also part of catalog.

The important for module description is a link to place where the module can be downloaded from and a manifest which identifies the module in NetBeans module system (module can be also a localization of some module but about this later).

I hope this caught the relevant components of Update Center Descriptor aka catalog.

See as the real-world looks like at http://www.netbeans.org/updates/dev_1.18_.xml

Description of each one attribute

Let's look on the DTD schema of catalog.xml at autoupdate-catalog-2_4.dtd

module_updates

The root element is module_updates:

<!ELEMENT module_updates ((notification?, (module_group|module)*, license*)|error)>
<!ATTLIST module_updates timestamp CDATA #REQUIRED>

The important (and only one) attribute is timestamp. The AutoUpdate client checks periodically the subscribed Update Center and compares the timestamp of the last check and Update Center's timestamp thus the attribute decide if the content of the Update Center will be read or not.

As I said above, module_updates covers elements:

• notification - only one per catalog,
• several module_group or module
• corresponding license
• error which is not currently used.

notification

<!ELEMENT notification (#PCDATA)>
<!ATTLIST notification url CDATA #IMPLIED>

Why the Notification would be needed for? Not much, it's more like a workaround how to promote users about a special content of the catalog. Or additional information how to handle the updates. How it works? AutoUpdate client reads the notification element and immediately displays the Notification dialog with text from this element. The Show URL button in Notification dialog invokes the URL given by url attribute. As I said before, it's a workaround, not pretty well UI designed. It better avoid this way if possible.

module_group

The modules can be organized in groups, one module group can contain an another module group. Module groups can create a tree structure.

<!ELEMENT module_group ((module_group|module)*)>
<!ATTLIST module_group name CDATA #REQUIRED>

The name is name of the group, displayed in Update Center Wizard.

module

The module is basic element of Update Center Descriptor. This element can represent either module update or module's localization. Module update is described by manifest element, a module localization is described by special l10n element. Other additional module sub-element are:

• description - only one attribute commonly in use - describes the module in Update Center Wizard,
• module_notification - an special module's notification, something such as <notification> element but on module's level,
• external_package - AFAIK not currently used. Undocumented and unsupported.

<!ELEMENT module (description?, module_notification?, external_package*, (manifest | l10n) )>
        
<!ATTLIST   module codenamebase CDATA #REQUIRED
            homepage     CDATA #IMPLIED
            distribution CDATA #REQUIRED
            license      CDATA #IMPLIED
            downloadsize CDATA #REQUIRED
            needsrestart CDATA #IMPLIED
            moduleauthor CDATA #IMPLIED
            releasedate  CDATA #IMPLIED
            global       CDATA #IMPLIED
            targetcluster CDATA #IMPLIED>

• codenamebase - the code name of the module, required to identification of updates within AutoUpdate framework.
• homepage - URL to module's homepage. When an user invokes More button in Update Center Wizard - Select Modules to Install then this URL is opened in Web browser. Not mandatory, if is empty then More buttom is disabled.
• distribution - URL to an place where the update (its NBM file) is stored. AutoUpdate client will download the update from this place. It's mandatory attribute. The URL can link to any server w/o restrictions.
• license - name of a license file. The license is displayed in the separate window and user has to agree with to continue with corresponding update. If more module are under same license (ie. have the same license file name) then an user should agree with only once within currently running Update Center Wizard.
  • Pay attention to have as same license file name for identical licenses.
  • The text of license is search through the current catalog (by lincence attribute). External links is not supported for license files.
• downloadsize - the declared size of {NBM file} in Bytes, shown in the wizard and used by progress bar while downloading.
• needsrestart - boolean attribute which can control if the IDE has to be restarted or not after download this update.
  • the attribute is not required. If it is not present then the AutoUpdate client doesn't restart IDE after download updates except as follows:
    • update of some of the already installed module,
    • install into the installation directory (not into default user dir)
  • true value forces restart the IDE regardless if needed or not
  • false is the default and behaves as same as not present
• moduleauthor - free name of author of module, shown in the *description area* of Update Center Wizard - Select Modules to Install if the attribute moduleauthor present and not null. Default: empty
• releasedate - generated date of module/update release. Shown in as same area as moduleauthor above.
• global - boolean attribute which can control if the module/update will be installed into the installation directory or into user's dir

  Note: the NetBeans installation layout consists from several clusters (ie. subdirectories of the NetBeans top level installation home - also called as shared dirs) and a special cluster for user's settings - called userdir. Each module is installed to one of them. The global attribute controls where install: userdir or shared dir

  • the attribute is not required. If it is not present then the AutoUpdate client installs all modules or updates into userdir except as follows:
    • the module/update will write into special directories lib or core - it forces installation into the shared platform cluster ie. global installation
    • an user can choose in Update Center Wizard if install global or not
  • true value forces global installation, an user cannot change it
  • false value forces local installation in the user dir, an user cannot change it too
  • What Is Target Cluster?
  
  
• targetcluster (Since NB6.0) - name of cluster where new module/update will be installed if installation into shared dir is chosen
  • the attribute is ignored if local installation (i.e. into userdir) chosen
  • the attribute is not required. If it is not present then the AutoUpdate client installs all modules or updates into the first cluster in list of netbeans.dirs

Note: Clusters in NetBeans installation structure are defined in the launcher, the list of cluster can be extended with netbeans_extraclusters property in netbeans.conf.
New Module or Update can declare a target cluster where should be installed. Determination which cluster is determine by these rules:

• module/update are installed in userdir as default (exceptions are described above), in this case the target cluster is ignored

The rest rules are valid only for global installation (needs to speficy by global attribute):
• a update of already installed module will be install in as same cluster as original module
• new module will installed in the target cluster
• if target cluster is one of defined clusters, if the cluster is defined but doesn't exist then the cluster will be created
• if target cluster is not defined cluster then it's ignored and the module will be installed into first defined cluster

description

<!ELEMENT description (#PCDATA)>

Text of description showing in Description area in the wizard. It this element is missing or it's empty, not worry the long description from the manifest element is used.

module_notification

<!ELEMENT module_notification (#PCDATA)>

Contains text which is shown in a separate window when this module is added between module to install. Can be used to promote any extra module's functionality or alert possible problems with module or such information. Not wide used in NetBeans Update Center.

manifest

The key part of each module/update specification. It determines if a module will available in the wizard, if can or cannot be installed separately, module's dependencies and so on.

The first important update property is specification version, is determining for updates, new module needn't handle it much. The update is available if (and only if) have a bigger specification version then its module.

If a module have any dependencies then this dependent modules are automatically selected together with the module. This feature is useful if we want install more modules in a pack e.g. a master module and its libraries. If any of declared dependencies cannot satisfied by currently installed module nor by another modules from catalog then the AutoUpdate Wizard show a warning about this problem, the wizard allows to install this module but it cannot be loaded and enable till missing module is available.

The manifest element is based on NetBeans Module System, the attributes corresponds to identical with attributes in NetBeans Modules API, see how-manifest

<!ELEMENT manifest EMPTY>
<!ATTLIST manifest OpenIDE-Module CDATA #REQUIRED
                   OpenIDE-Module-Name CDATA #REQUIRED
                   OpenIDE-Module-Specification-Version CDATA #REQUIRED
                   OpenIDE-Module-Implementation-Version CDATA #IMPLIED
                   OpenIDE-Module-Module-Dependencies CDATA #IMPLIED|
                   OpenIDE-Module-Package-Dependencies CDATA #IMPLIED
                   OpenIDE-Module-Java-Dependencies CDATA #IMPLIED
                   OpenIDE-Module-IDE-Dependencies CDATA #IMPLIED
                   OpenIDE-Module-Short-Description CDATA #IMPLIED
                   OpenIDE-Module-Long-Description CDATA #IMPLIED
                   OpenIDE-Module-Display-Category CDATA #IMPLIED
                   OpenIDE-Module-Provides CDATA #IMPLIED
                   OpenIDE-Module-Requires CDATA #IMPLIED>

Notes:

• The manifest element is nearly a duplicate of the really manifest in module's jar file (from the corresponing NBM file), but this manifest element is used by AutoUpdate client and manifest from the jar file is used by NetBeans Module System. It is not forced to be fully identical, if I want to do a little hacking the catalog then I just change some attribute to get what I want.
• OpenIDE-Module-Requires - it's useful if want to distribute a OS specific modules (i.e. operating system specific). If I have a module which is aplicable only of Mac platform, just write org.openide.modules.os.MacOSX in this element. AutoUpdate client reads this and shows a module if this requirement is satisfied. For more info see how-os-specific.
• Long-descrption - it's show in the Description area in the wizard if description element is empty. If do you want to add a HTML tag into description then add it but remember to escape the <, >, " etc.

l10n

Support for module localization, about this later. See How to Localize.

license

The license associated to module or update. An user has to agree with this license when install it.

<!ELEMENT license (#PCDATA)>
<!ATTLIST license name CDATA #REQUIRED>

• name - name of license, used to mapping to module|license attribute.

errors

Undocumented, unsupported, not used.

<!ELEMENT error (auth_error|other_error)>

<!ELEMENT auth_error EMPTY>

<!ELEMENT other_error EMPTY>
<!ATTLIST other_error message CDATA #REQUIRED>

---

Versioning