Overview

Javadoc

Contents

• What Are Modules?
  • Related standards
• How to Create a New Module
  • Build a JAR
  • Writing the manifest
  • Using a custom module class
    • "Installation-clean" modules
  • Using an installation layer
  • Using versioning
• Standard Module Sections
  • Action
  • Option
  • Data loader
  • Debugger
  • Service
  • File system
  • Node
  • Clipboard convertor
• JavaHelp
  • via Layer
  • via Manifest
  • Using context help
• Deployment of Modules
  • Downloading
  • Module install order
  • List of all modules
  • Security
  • JNI
• UML diagrams
  • General structure class diagram

Modules API

How to Create a New Module

For basic cases, you should need to do very little to create a module besides writing the basic source code.

Please see a list of tips on writing modules, installing them into the IDE, testing and debugging them.

Build a JAR

All module implementation classes must reside in a JAR file. If you want to split up a large application into several pieces, perhaps so as to make independent upgrades possible, you should do so by creating multiple modules and relating them using versioning.

To create the JAR, just use the standard JDK's JAR tool. You will need to add a custom manifest file, so use the -m option to specify the additional contents. (Note that -m will automatically merge the contents of your manifest file with anything it would normally add, so e.g. signatures will be automatically created properly.)

Writing the manifest

There are a few other global tags which are optional but encouraged:

OpenIDE-Module-Name

Gives a human-presentable display name for the module. The name may be localized by adding additional tags for each locale, e.g. OpenIDE-Module-Name_fr.

OpenIDE-Module-Short-Description

A short description of what the module does (about one sentence, like a tool tip). May be localized as for the display name.

OpenIDE-Module-Long-Description

A longer description of what the module does (roughly paragraph-length). May be localized as for the display name.

OpenIDE-Module-Display-Category

A phrase giving a category for the module. Modules with the same category may be visually grouped together in various parts of the UI. May be localized as for the display name.

OpenIDE-Module-Description

Allows the IDE to provide JavaHelp and context help for the module.

OpenIDE-Module-Install

The name of a custom module class.

OpenIDE-Module-Layer

The name of an installation layer.

Various versioning-specific tags

Please see the section on versioning for details on these.

OpenIDE-Module-Module-Dependency-Message and OpenIDE-Module-Package-Dependency-Message

Localizable pleasant messages to display to a user in case a module or package dependency fails. In some cases it may be quite normal for a dependency to fail and it is desirable to provide a specific and helpful message to the user explaining where to get the required dependency or why the module depending on it is not needed by this user. May be localized as for the display name. Since 1.26

Since 1.24: A more flexible way to provide human-readable information is to declare the attribute OpenIDE-Module-Localizing-Bundle. Its value should be the resource path to the (base locale of) a bundle file providing localizable attributes for the module (display name, category, short and long description). The bundle file may have localized variants as usual, and the keys should be the same as the desired manifest attribute names, e.g. OpenIDE-Module-Name. If it is necessary to localize an attribute from a section (currently only filesystem sections with their Display-Name attribute), you may again place these in the bundle, where the key will be prefixed by the section name and a slash, e.g. org/foo/MyFileSystem.class/Display-Name.

All other tags are bound to a particular module section. Naturally you may use other standard manifest attributes.

Manifest-Version: 1.0
OpenIDE-Module: com.modulemakers.clip_disp/2
OpenIDE-Module-Specification-Version: 2.0.1
OpenIDE-Module-Implementation-Version: build-213a
OpenIDE-Module-Name: Clipboard Displayer
OpenIDE-Module-Name_cs: Prohlizec schranky
OpenIDE-Module-Description: com.modulemakers.clip_disp.docs.ClipHelpSet
OpenIDE-Module-Install: com/modulemakers/clip_disp/Installer.class
OpenIDE-Module-Layer: com/modulemakers/clip_disp/Layer.xml
X-Comment-1: I am a comment (just a deliberately meaningless
X-Comment-2: header) - "Sealed" is a standard manifest attribute.
Sealed: true

Name: com/modulemakers/clip_disp/DisplayClipboardAction.class
OpenIDE-Module-Class: Action

Using a custom module class

To use a main install class, just extend the ModuleInstall base class. Your class must be able to be instantiated as a JavaBean. There are several methods which you may override, and may do anything which is required to make the module cleanly enter and exit the IDE.

package com.modulemakers.clip_disp;
import org.openide.modules.ModuleInstall;
import org.openide.filesystems.FileUtil;
import java.net.*;

public class ModuleHandler extends ModuleInstall {
  public void installed() {
    // This module has been installed for the first time! Notify authors.
    HttpURLConnection conn = (HttpURLConnection)
      (new URL ("http://www.modulemakers.com/clip_disp/installed.cgi").openConnection ());
    conn.getResponseCode ();
    conn.disconnect ();
    // Handle setup within this session too:
    restored ();
  }

  public void restored() {
    FileUtil.setMIMEType("test", "text/x-clipboard-content-test");
  }

  // Do not need to do anything special on uninstall.
  // Tools action will be removed automatically.
  // public void uninstalled() {
  // }

  public boolean closing() {
    // Ask the user to save any open, modified clipboard contents.
    // If the user selects "Cancel" on one of these dialogs, don't exit yet!
    return DisplayClipboardAction.askAboutExiting ();
  }
}

The installed handler may do more or less what it wishes - it will be called in a running IDE. The same applies to uninstalled and closing. However, restored is more delicate in that it may be called during earlier phases of IDE initialization. Therefore, it should not use presentation-oriented features of the IDE, such as the Explorer or Window System APIs. However, the other APIs are acceptable to use in restored, including the TopManager's dialog notification methods.

The ModuleInstall.updated(...) method will be called just once when a module is updated to a new version - when the new version is loaded into the IDE for the first time (in a new session), the method is called and the previous version number is accessible. Neither installed nor uninstalled will be (automatically) called in this case. It is a module author's responsibility to make sure that new versions of a module are capable of "cleaning up" obsoleted installations created by older versions, as far back as a user is likely to be directly upgrading.

Some module installer classes may desire to keep state across IDE sessions, for example if they require specific instructions on what to uninstall that can only be gotten during the installation process. All installers are automatically Externalizable and module authors may decide to override the two methods of this interface to read and write its state from an object source. Typically you would want to serialize and deserialize shared class fields in the object using these methods. It is a good idea to call the super methods as the first action when overriding.

In some cases, a module relies on some external resource to be present in order for it to be used. For example, an external application may need to be installed in order for it to do anything. Or it may require a valid license key. In such cases, the ModuleInstall.validate() method may be overridden to check for this external resource and throw a (preferably politely localized) IllegalStateException if something is wrong. Throwing this exception will cancel the module installation (or restoration) cleanly. Note that such an installer should not expect anything related to the module to already be loaded when this method is called, as it may be done when deciding whether to even begin loading.

Using an installation layer

Starting with NetBeans 3.1, you may specify the global tag OpenIDE-Module-Layer in addition to or instead of a module main class; as a rule, use a layer for a particular task in preference to a module installer, if you can. The tag value should point to an XML file inside the module which is in the format understood by XMLFileSystem. Its contents specify some files that the module will add to the system file system controlling much of the IDE's configuration.

By default files listed in XML layers are not ordered in any particular way, just as files found on disk would not have a particular order. For purposes of some kinds of installation, it is desirable to order data objects in data folders in a particular way - for example, menus are built from their menu items in the order the instance-bearing data objects occur in the data folder. The call DataFolder.setOrder(DataObject[]) suffices to arbitrarily change folder order, but usually it is desirable to create the proper order declaratively in the XML. For this reason, DataFolder understands special attributes (set on the FileObject forming the folder) which provide relative ordering constraints on the objects in the folder. Specifically: if there are data objects A and B in the folder, represented by primary files afile and bfile, and there is an attribute on the folder containing them named afile/bfile whose value is Boolean.TRUE, then the folder will attempt to place A before B in its ordering. For example, the XML:

<folder name="SomeFolder">
    <file name="first.txt" url="first.txt"/>
    <attr name="first.txt/second.txt" boolvalue="true"/>
    <file name="second.txt" url="second.txt"/>
</folder>

1. Modules may provide layers some of whose files specify relative constraints on files in the same folder position but installed by the core, or other modules. That is fine and the constraints will be honored - assuming the files being constrained both exist. Constraints for which one or both of the affected files do not exist, are simply ignored.
2. It is fine to provide multiple constraints from a single file, for example if there are several possible files it might need to be installed after; all relevant constraints will be attempted.
3. If constraints are contradictory, they may be ignored (and a warning issued).
4. If the user reorders the folder manually or DataFolder.setOrder(DataObject[]) is called, the explicit order overrides the existing constraints. Subsequently added constraints might have an effect, however.
5. Only the names of primary files from data objects have any bearing on the ordering.
6. A constraint specifying that A comes before B does not force the folder to place it immediately before B. If you want to ensure that A in fact comes after some other files you know come before B, thus trying to make them adjacent, this must be done explicitly. Another module might explicitly interpose a file C between A and B.

The resource path pointing to the layer is automatically localized by the IDE every time the module is installed or restored; if there are locale-specific variants, they are merged with the main layer. More-specific variants can simply add files to the set installed by the module; however they take precedence over the less-specific variants, and thus can replace files, or even remove (suppress) them, using *_hidden masks as used by MultiFileSystem. In fact, if module A depends on module B, then A's layer(s) will take precedence over B's layers, and it may replace or remove files installed by B. In the same way, any module may replace or remove files installed by the core.

(Compatibility note: in NetBeans 3.1, only the most specific locale variant of a layer is used, rather than merging them all together. You may write layers which are conformant with this API and which also work correctly in 3.1 by ensuring that all variants mention all of the common files, as well as their particular overrides and masks.)

Using versioning

Modules can do three things with versioning:

1. Specify what they are. This is done by the special OpenIDE-Module tag, whose value should be a unique (programmatic) identifier for the module, as mentioned above. Not be confused with the display name, which is free-form and may be changed at will, this code name should not be changed arbitrarily - pick a name and stick with it throughout module releases.
2. Specify which version they are. In line with the Java Versioning Specification, modules can indicate two pieces of version information about themselves using the OpenIDE-Module-Specification-Version and the OpenIDE-Module-Implementation-Version tags.
3. Specify which features they depend on. Again, this is done using the Versioning Specification - modules can request general or specific versions of other modules (OpenIDE-Module-Module-Dependencies), Java packages (OpenIDE-Module-Package-Dependencies), Java itself (OpenIDE-Module-Java-Dependencies), or the IDE (OpenIDE-Module-IDE-Dependencies).

So, modules may specify either or both kinds of versions in their manifest, and correspondingly request such versions from other modules. The Versioning Specification provides similar numbering for (some, but not all) Java packages, as well as the core Java Platform APIs and Virtual Machine Specification. The IDE also has such versions which may be used to request a general level of Open API support (using specification versions) or a particular NetBeans build (using implementation versions).

Since the Versioning Specification does not address incompatible changes (those which would break existing code), but these are in practice occasionally necessary (however painful), both modules and the IDE itself may provide a separate integral number giving the incompatible release version. You may only request a particular release version, not subsequent ones, and you must specify the release version if there is one when giving any module dependency. It only differs from a complete change of the feature in that the module installer tool may prompt the user to make a "major upgrade" if a new release version of a module is available.

To use all of these tags once you understand them is not too hard. First of all, feature names: a module is named according to the OpenIDE-Module tag, which should look like a Java package name, but may be followed by a slash and release number (e.g. com.mycom.mymodule/3); the IDE itself is named IDE, again usually with a slash and release number; Java packages are just named by the package name; the Java Platform APIs are named by Java; and the Java Virtual Machine by VM.

Now, a module may list its own specification and/or implementation versions using the tags above. To specify a dependency on other features, it may use some or all of the four dependency tags. The value of each will be a comma-separated list of dependencies of that general type, each of which can be of the form:

FEATURENAME

Just requests that the feature be present, not any particular version. Useful for modules and Java packages (usually, Java standard extensions) that need to be installed, but that is all.

FEATURENAME > SPECVERSION

Requests that the feature be present, that it state a specification version, and that this version be greater than or equal to the requested version. Note that you may not request an exact specification version. This is the preferred form for module dependencies.

Remember, if requesting a dependency on a module which has a release number, you must give that release number as part of the feature name, whether or not you also ask for a specification version.

FEATURENAME = IMPLVERSION

Requests that the feature be present, that it state an implementation version, and that this version exactly match the requested one. Note that you may not request a comparison on implementation versions, as they are generally non-numeric and not comparable.

OpenIDE-Module: com.mycom.mymodule/1
OpenIDE-Module-Specification-Version: 1.0.1
OpenIDE-Module-Implementation-Version: build99
OpenIDE-Module-Module-Dependencies:
 com.mycom.mysistermodule/1 = build99,
 com.othercom.anothermodule > 2.1,
 org.netbeans.modules.applet/1 > 1.0
OpenIDE-Module-Package-Dependencies: javax.television > 0.9
OpenIDE-Module-Java-Dependencies: Java = 1.2.1b4, VM > 1.0
OpenIDE-Module-IDE-Dependencies: IDE/1 > 1.0

There is further special treatment for handling of package dependencies for several reasons:

1. In practice, the Java Versioning Specification is not all that widely followed, and many needed extensions will not list this information in their manifest.
2. Classloaders only define packages when the first class from that package is actually loaded. This makes it more difficult to verify whether a package is really there or not.
3. The standard manifest attribute Class-Path must be recognized and used; typically this attribute is used to actually add extensions to the module classloader, while the Modules API attributes are used to ensure that specific versions are available.

You may specify a sample class name in square brackets immediately after the package name (or indeed instead of it). Giving a class name together with a package name requests that the IDE first try to load that class (it must be able to, so choose a class in the extension you know will be there); then the versioning information is checked. (If the sample class is simply in the desired package, you may omit the package qualification as a shortcut.) This addresses the second problem. Giving just a class name in square brackets with no preceding package name indicates that the IDE should only ensure that the named class is loadable, bypassing the Versioning specification mechanisms. This addresses the first problem.

OpenIDE-Module: com.mycom.mymodule/1
OpenIDE-Module-Package-Dependencies: javax.television[TunerProvider] > 0.9
Class-Path: ext/television.jar

Important! If your module has compile-time references to classes in another module, you must specify a dependency on that module. This ensures that the modules will be installed in the correct order; otherwise a NoClassDefFoundError or similar problem could result.

Standard Module Sections

Action

By using this manifest section, your action will be available as a "tool", i.e. it will appear (when enabled) in a list of all extension tools in any popup menu (etc.) using ToolsAction. Note that you do not need to use ToolsAction directly for this purpose: it should already be attached as a popup to all interesting nodes, as a menu item in the Tools menu, etc. Just using the manifest tag ensures that your action will be shown under such submenus.

Option

Installation of options from manifest is now deprecated. See the Services API instead.

Loader

There are a couple of options which may be used to specify the relative precedence of data loaders, so that a more specific loader may take precedence over a more general one:

Install-Before: classname

Instructs the IDE to try to install this data loader before another, so as to give it higher precedence: it will be given the opportunity to scan over potential data objects first. The classname should specify the representation class of the other loader's data object type; see the DataLoader constructor for an explanation of how to use representation classes. You may supply multiple class names separated by commas.

Install-After: classname

Exactly like Install-Before, except that the IDE will attempt to install this loader after another, so as to give it lower precedence.

You need not specify module dependencies on other modules simply because you use the names of data objects in those modules in your install before and after tags; the ordering hints will simply be ignored unless and until the other module is installed, at which time they will take effect.

Debugger

Installation of debuggers from manifest is now deprecated. See the Services API instead.

Service

Installation of services from manifest is now deprecated. See the Services API instead.

File system

You may specify a couple of options for a file system:

Display-Name: some text

This sets the display name of the file system type, which will be used (for example) when creating an "Add some text" menu item under the Tools menu, and a corresponding popup on the Repository node. Localized variants of the name may be provided, e.g. by adding an attribute Display-Name_de (in this case, for a German locale).

Help: help ID

Provides context help for this type of file system, in case some of its configuration or use is not apparent. Should be a JavaHelp help ID, as described in the section on context help.

Note that this help ID is provided in the manifest, rather than on the file system itself, since it should not be necessary to actually create a file system instance to get it (which could have undesirable side effects), and it may be used in (e.g.) popup menus on the Repository permitting the user to add a new file system.

Rather than installing a filesystem type via manifest, however, you are encouraged to instead provide a service template according to the FileSystems API.

Node

• Environment installs a node in the Explorer's Environment hierarchy. This may be used for modules which need to provide user-level access to some transient aspect of the module's operation not otherwise apparent. For example, an HTTP filesystem might want to provide a node under the Environment displaying information about its cache, and permitting operations such as clearing the cache.
• Roots installs a new root node for a whole new hierarchy. These roots may be displayed as switchable tab panes in the Explorer, to visually represent each root in parallel. Please do not create a new root without a compelling UI justification.
• Session installs a new node in the Session Settings area.

Refer to the Nodes API for details on constructing an appropriate node.

Clipboard convertor

Installation of convertors from manifest is now deprecated. See the Services API instead.

JavaHelp

JavaHelp via layer

As of APIs 1.6

The most flexible way to add JavaHelp is via your XML layer. First you need to add the helpset to the IDE. This has several effects: it ensures that context help can use your helpset; it enabled help links to use help IDs defined in this helpset; and assuming the helpset is marked to be merged into the master helpset, this means that the menu item Help | Contents will show any navigators you define in your helpset, merged into others.

To add a helpset, you must register an object implementing javax.swing.HelpSet into the IDE's lookup system. The normal way to do this is to create an XML file with a special DTD which you place into the Services/JavaHelp/ folder of the system file system via layer. This file specifies the URL to the help set, for example:

<?xml?>
<!DOCTYPE helpsetref PUBLIC
          "-//NetBeans//DTD JavaHelp Help Set Reference 1.0//EN"
          "http://www.netbeans.org/dtds/helpsetref-1_0.dtd">
<helpsetref url="nbresloc:/org/netbeans/modules/foo/help/HelpSet.hs"/>

By default such a helpset will be merged into the IDE's master help navigators. You may opt out of this by specifying merge="false" on the <helpsetref/>. If providing a custom help set instance via lookup, in order to turn off merging you should set the "key data" on the helpset with the context OpenIDE and key mergeIntoMaster to Boolean.FALSE.

Using nbresloc implies that the helpset can be found in the module's classloader, for example in its main JAR or in an extension ZIP or JAR referenced via the Class-Path manifest attribute. There is a URL protocol nbdocs which is similar to nbresloc, but the current NetBeans core implementation recognizes this URL and permits the help set and associated files to reside in a package hierarchy underneath the docs/ folder (of the IDE installation or user directory), if not in the module classloader.

To add a shortcut to a specific help ID in your help set, there is a different XML DTD you can use. Normally such shortcuts would go into the folder Menu/Help/HelpShortcuts/ so as to appear in Help | Help Sets. The shortcut XML specifies the help ID to display (which must be present in some registered help set of course), for example:

<?xml?>
<!DOCTYPE helpctx PUBLIC
          "-//NetBeans//DTD Help Context 1.0//EN"
          "http://www.netbeans.org/dtds/helpcontext-1_0.dtd">
<helpctx id="org.netbeans.modules.foo.some-topic"/>

By default such a link will display a help window containing navigators only for the help set from which it was taken. If you prefer to display navigators for all merged help sets, specify showmaster="true" on the <helpctx/>.

This XML file's only use is that it has a menu/toolbar presenter which opens the specified help page. (You can customize its display name and icon using the normal means available to templates etc.) You could provide an alternate means of displaying help shortcuts, however the functionality of showing the master navigators is only accessible via the presenters of this kind of XML file.

JavaHelp via manifest

If you are using a version of the APIs older than 1.6, or simply prefer the default mode of displaying JavaHelp and do not require any customization, you may also install JavaHelp via module manifest.

The tag OpenIDE-Module-Description specifies a help-set file according to the standard JavaHelp specification. The tag value gives the location of the help set within the module JAR, and supports localization; for example, the description com.mycom.mymodule.docs.TheHelpSet might look for JAR entries such as:

1. /com/mycom/mymodule/docs/TheHelpSet_en_US.hs
2. /com/mycom/mymodule/docs/TheHelpSet_en.hs
3. /com/mycom/mymodule/docs/TheHelpSet.hs

First of all, providing a help set means the IDE will permit users to see it via the normal JavaHelp viewer, and employ standard merging of navigational views. If you provide a home ID, a menu item linking to that home page will be added to the Help menu automatically, named according to the help set title; if it ends with an asterisk (*) it will be treated as a distinguished help set covering a prominent area of documentation. If you provide various navigational views, they will appear in merged form. Modules are strongly encouraged to provide a home ID, and views in the table of contents, index, and full-text search modes, making for a well-integrated help system.

Context Help

When the help set is specified in the module, this permits the IDE to associate context help with various features associated with the module (or, technically, other modules - if you know their help IDs and they do not themselves bind them). There are several ways to associate help IDs with module features so that they may be used by the IDE, mostly revolving around the API class HelpCtx.

This class has several constructors for different purposes; the constructor which takes a Class is convenient for some purposes, or the one taking a String is also fine. The constructor with a string directly uses that help ID, which may be any string uniquely identifying the feature, and associated with an HTML page using the map file; when passing in a class object, this should typically be the class returning the help object, and the ID will be the fully-qualified class name, which avoids the need to separately choose a good help ID.

public HelpCtx getHelpCtx () {
  return new HelpCtx (ThisAction.class);
}

<mapID target="com.mycom.mymodule.ThisAction" url="this-action.html" />

There are a number of different points in the APIs where you may specify a HelpCtx in this fashion:

• Node.getHelpCtx()
• DataObject.getHelpCtx()
• TopComponent.getHelpCtx()
• SystemAction.getHelpCtx()
• NewType.getHelpCtx()
• PasteType.getHelpCtx()
• DialogDescriptor.getHelpCtx()
• WizardDescriptor.Panel.getHelpCtx()
• SystemOption.getHelpCtx()
• ServiceType.getHelpCtx() (applies equally to executors, debugger types, and compiler types)

• In a module file system section.
• On any (Swing lightweight) component you use in a GUI, by means of HelpCtx.setHelpIDString(...). This is especially useful for custom property editor components.
• On any JavaBean, by adding the help ID as a (string) value to the (FeatureDescriptor) attribute named helpID in a BeanDescriptor, as described by the JavaHelp specification in regards to beans. This will be interpreted by any bean container (e.g. InstanceDataObject or BeanNode or *.ser files) that uses InstanceSupport.findHelp(...).

  This technique may also be used to add context help support to the editor kits used in the Editor API; create the bean info for the subclass of EditorKit, and this help will be used for the editor pane.

• As the helpID value of a Node.PropertySet or Node.Property.
• For services on the system filesystem (typically installed via layer) and the folders they are in (typically beneath Services/), you may use the file attribute helpID to specify the help ID right in the layer. See the Services API for details.
• In the <homeID> tag of a help set file; in this case, the specified help ID is understood as applying generally to the module. Typically it should be some sort of index page. The IDE will automatically display such pages as the help for a whole module, currently under Help | Contents.
• In various navigational views used by JavaHelp, such as the table of contents or the index.

The proper help page for the selected component, if there is one, is displayed by the IDE by default using F1, which calls HelpAction. This applies to various visual components (when they have focus), the current TopComponent, and nodes (or the objects they represent) when the node is selected in an Explorer window (or custom windows based on ExplorerPanel). Programmatically, you may also display help by calling TopManager.showHelp(HelpCtx).

Deployment of Modules

This section describes how a module may be deployed to a user's IDE.

Module install order

First of all, when the IDE starts up, all previously-installed modules are restored, calling the restored methods on their install classes if present. (Sections are installed before this method is called.) If multiple modules are being restored (which is normally the case), the IDE installs them in an arbitrary order. However, if some of them specify dependencies on other modules, the order may be adjusted so as to make sure that the one specifying the dependency is installed after the one it depends on.

Now, when the IDE is running, modules may be installed into it, possibly a cluster of them at once. In such a case, the IDE first checks to make sure that all the prospective modules satisfy their dependencies, either on system or Java features; already-installed modules; or other modules in the prospective cluster. If any modules fail their dependencies (or had syntactical errors in their manifest files, etc.), they are removed from the list and the user is given an explanation of what is missing. The remainder are then ordered according to dependencies as above, and then installed in that order.

Caution: it is forbidden to install modules which have cyclic dependencies on one another, as the IDE would be unable to determine which order to install them in! In fact, it will signal an error and not install such modules. Generally such a situation means that you should "factor out" the common required functionality into a new module which the original ones will then specify legal dependencies on.

List of all modules

Lookup.Template templ = new Lookup.Template(ModuleInfo.class);
Lookup.Result result = Lookup.getDefault().lookup(templ);
Collection modules = result.allInstances(); // Collection<ModuleInfo>

A limited ability to modify the installation status of modules is provided by the APIs as of version 1.31. In the folder Modules/ on the system file system, there will be XML files corresponding to all known modules. In each case the name of the XML file is derived from the code name base of the module with . replaced by -, and followed by .xml; for example, org-netbeans-modules-properties.xml. The contents of the XML file are given by a fixed DTD.

For purposes of the API, only parts of these files are defined. The root element must be <module> and its name attribute must be the code name base of the module. Inside the root element are various <param> elements, each with a name and some textual contents. The APIs define only one parameter, enabled, which if present must be either true or false.

The APIs do not currently permit arbitrary changes to these files. Specifically, addition or deletion of these files, or modification of other files that may be in the same folder, is not permitted. Modification of these files is permitted in only one way: if a module XML file already contains the parameter enabled, you may rewrite the file to be identical except with the opposite value of this parameter. The module system will then make a best effort to enable or disable the module accordingly (subject to dependencies and other constraints).

Doing this is not recommended except in unusual circumstances, and is intended primarily for session support to be able to enable and disable modules via layer. If your module just needs to prevent itself from being turned on under some circumstances (for example if it is missing a valid license key), simply use ModuleInstall.validate.

When rewriting the module XML be sure to use FileSystem.runAtomic(FileSystem.AtomicAction) to wrap the reading of the old XML and the writing of the new, to prevent file changes from being fired halfway through.

UML Diagrams

Modules API general structure class diagram