5 Working with NetBeans Modules

5.6.1 About Module Project Templates

The IDE contains a set of standard project templates for module development. The standard distribution of the IDE contains the following module project templates:

• Module. Use a module project as the place where you code your module.

• Library Wrapper Module. Use library wrapper module projects to put one or more library JAR files on a module's classpath.

• Module Suite. Use a module suite project to group and deploy a set of interdependent module projects and library wrapper module projects.

• NetBeans Platform Application. Use a NetBeans Platform Application project as the skeleton framework as the starting point of your own applications.

Important Files

Module projects, library wrapper module projects, and module suite projects have an Important Files node where the IDE stores the Ant script, layer.xml file, and other project data.

The following table lists the highlights of the Important Files node and whether each is found in a module project template, a library wrapper module project template, a module suite project, or all three:

5.6.2 How to Create a Module Project

Use a module project template to create a module project. The module project is the place where you code your module. Module projects implement the module's features and functionality that extend the NetBeans APIs, which you kickstart by using file templates. In addition, module projects include the business logic that integrate the library wrapper module projects into the module. Code housed in module projects also provides, for example, the user interface for receiving and processing user input.

To create a module project:

1. Choose File > New Project (Ctrl-Shift-N).

2. From the NetBeans Modules category, select Module. Click Next.

3. In the Name and Location panel, specify the following:

   • Project Name. Specifies the folder in which the project will be housed, prepended by the project location, which is specified in the next field.

   • Project Location. Specifies the location where you want to store the project metadata and source code.

   • Project Folder. Specifies the folder where you want to store the project metadata and source code. The folder is a concatenation of the project location and the project name.

   • Standalone Module. Specifies that the module does not belong to a module suite. In addition, you must specify which platform the module will be compiled and deployed against. To add additional platforms to the list, click Manage and use the NetBeans Platform Manager.

   • Add to Module Suite. Specifies that the module belongs to a module suite. If the module suite is not currently open in the IDE, click Browse to locate the module suite in your filesystem.

4. Click Next.

5. In the Basic Module Configuration panel, specify the following:

   • Code Name Base. Specifies a unique name for the module. A main package will be created with the same name as the code name base. If your code name base is org.modules.foo, your default package structure will be org/modules/foo.

   • Module Display Name. Specifies the name that will be displayed in the Projects window.

   • Localizing Bundle. Specifies location of the Bundle.properties file. Normally, the default suggestion should be appropriate.

   • OSGi Bundle. If the "Generate OSGi Bundle" checkbox is selected, an OSGi bundle will be created, instead of a NetBeans module. The difference will be visible in the Manifest file.

6. Click Finish.

5.6.3 How to Create a Library Wrapper Module Project

Use a library wrapper module project template to create a library wrapper module project. Library wrapper module projects put one or more library JAR files on a module's classpath. You have to export some or all of the packages as public, and you need to have a regular module depend on it, or the library wrapper module becomes useless. The wizard that you use to create the library wrapper module project automatically exports as public any packages it finds in the JARs.

To create a library wrapper module project:

1. Choose File > New Project (Ctrl-Shift-N).

2. From the NetBeans Modules category, select Library Wrapper Module.

3. In the Select Library panel, specify the following:

   • Library. Specifies one or more JAR files that make up the library. Use Shift-Click and Ctrl-Click to select more than one JAR file. You are encouraged to only include more than one JAR file if their versions are likely to increment at the same time.

   • License. Specifies the License of the JAR files.

4. In the Name and Location panel, specify the following:

   • Project Name. Specifies the folder in which the project will be housed, prepended by the project location, which is specified in the next field.

   • Project Location. Specifies the location where you want to store the project metadata and source code.

   • Project Folder. Specifies the folder where you want to store the project metadata and source code. The folder is a concatenation of the project location and the project name.

   • Add to Module Suite. Specifies that the module belongs to a module suite. If the module suite is not currently open in the IDE, click Browse to locate the module suite in your filesystem.

5. Click Next.

6. In the Basic Module Configuration panel, specify the following:

   • Code Name Base. Specifies a unique name for the module. A main package will be created with the same name as the code name base. If your code name base is org.modules.foo, your default package structure will be org/modules/foo.

   • Module Display Name. Specifies the name that will be displayed in the Projects window.

   • Localizing Bundle. Specifies location of the Bundle.properties file. Normally, the default suggestion should be appropriate.

7. Click Finish.

5.6.4 How to Create a Module Suite Project

Use a module suite project template to create a module suite. A module suite groups and deploys a set of interdependent module projects and library wrapper module projects. For rich-client applications, the module suite project is a skeleton application to which you can attach a splash screen, a progress bar, a name for the application's executable, and a title for the application's titlebar.

To create a module suite project:

1. Choose File > New Project (Ctrl-Shift-N).

2. From the NetBeans Modules category, select Module Suite.

3. In the Name and Location panel, specify the following:

   • Project Name. Specifies the folder in which the project will be housed, prepended by the project location, which is specified in the next field.

   • Project Location. Specifies the location where you want to store the project metadata.

   • Project Folder. Specifies the folder where you want to store the project metadata and source code. The folder is a concatenation of the project location and the project name.

   • NetBeans Platform. Specifies the platform against which the module will be compiled and deployed. To add additional platforms to the list, click Manage and use the NetBeans Platform Manager.

4. Click Finish.

5.6.5 How to Create a NetBeans Platform Application Project

Use a NetBeans Platform Application project template to create the starting point of your application on top of the NetBeans Platform. This template project provides a skeleton application to which you can attach a splash screen, a progress bar, a name for the application's executable, and a title for the application's titlebar.

To create a NetBeans Platform Application project:

1. Choose File > New Project (Ctrl-Shift-N).

2. From the NetBeans Modules category, select NetBeans Platform Application.

3. In the Name and Location panel, specify the following:

   • Project Name. Specifies the folder in which the project will be housed, prepended by the project location, which is specified in the next field.

   • Project Location. Specifies the location where you want to store the project metadata.

   • Project Folder. Specifies the folder where you want to store the project metadata and source code. The folder is a concatenation of the project location and the project name.

   • NetBeans Platform. Specifies the platform against which the module will be compiled and deployed. To add additional platforms to the list, click Manage and use the NetBeans Platform Manager.

4. Click Finish.

5.7.1 Generating Skeleton API Implementations

To simplify the process of working with the NetBeans APIs, the NetBeans IDE provides several wizards that guide you through the initial phase of working with a NetBeans API. For more information, see Section 5.7, "Using the NetBeans APIs". For example, the New Action wizard provides the basis of an implementation of the NetBeans Actions API, the New File Type wizard provides the basis of an implementation of the NetBeans Datasystems API, and so on.

The NetBeans API wizards are as follows:

• Module. Use a module project as the place where you code your module.

• Library Wrapper Module. Use library wrapper module projects to put one or more library JAR files on a module's classpath.

• Module Suite. Use a module suite project to group and deploy a set of interdependent module projects and library wrapper module projects.

• NetBeans Platform Application. Use a NetBeans Platform Application project as the skeleton framework as the starting point of your own applications.

Project Templates

Project templates come in two types:

• Templates that users build on when creating their own project. For example, in the IDE a user chooses the 'Web Application' project template in the New Project wizard, then the IDE creates a project consisting of a JSP file, a web.xml file, a server-specific deployment file, and project metadata within a specific structure that is useful for web application projects.

• Samples that illustrate some aspect of project functionality. For example, in the Samples directory within the New Project wizard, an Anagram Game is included to demonstrate Java SE functionality. Samples are a kind of project template; they have the same behavior as project templates, but they are used for a different purpose.

A project template is made available to the IDE's New Project wizard once it has been registered in the layer.xml file. For more information, see Section 5.9.2, "About XML Layer Files".

You use the New Project Template wizard to create the basic files and to register the template in the layer.xml file.

Before you can use the New Project Template wizard, you must have project in the IDE that is structured in exactly the way that you would like it to be available in the New Project wizard. For example, if you are going to create a new project sample, you must first lay it out in the IDE. Then use the New Project Template wizard to add the template to the New Project wizard.

When you make the module that contains the new project template available as an NBM file, the user can install it via the Plugins manager and then, once it has been successfully installed, select it from the New Project wizard.

The standard distribution of the IDE contains the following module file templates:

• Action. Creates an action that can be invoked from a menu item, pop-up menu, toolbar button, or keyboard shortcut.

• Code Generator. Creates a new menu item in the Insert Code popup in the editor of your choice.

• File Type. Lets the IDE recognize a new file type.

• Java SE Library Descriptor. Adds a new class library to the Ant Library Manager of the user's IDE.

• JavaHelp Help Set. Creates all the files needed for building a JavaHelp help set.

• Installer/Activator. Creates a ModuleInstall class for a NetBeans module or a BundleActivator for OSGi bundles.

• Layout of Windows. Lets you design the layout of the windows in your application.

• Options Panel. Adds a new panel to the Options window.

• Project Template. Adds a new template to the New Project wizard.

• Quick Search Provider. Creates a new entry in the Quick Search field.

• Update Center. Registers an update center in the Plugins manager. As a result, the user does not need to manually register the Update Center in the Plugins manager.

• Window. Creates a new window with an Open action invoked from a menu item.

• Wizard. Creates a new wizard for creating, for example, new files in the IDE.

• XML Layer. Creates a layer file for registering folders and files into the central registry, also known as the System FileSystem.

The NetBeans API wizards create the starting point for your development activities. Once you have worked through a wizard, you build your module's functionality on top of the files that the wizard creates for you.

Related NetBeans API Javadoc

The NetBeans API wizards create the starting point for your development activities. Once you have worked through a wizard, you build your module's functionality on top of the files that the wizard creates for you.

The following table lists the Javadoc that you will need to refer to when building on top of the skeleton API implementations:

5.7.2 Extending Skeleton API Implementations

Once you have used the NetBeans API wizards, you extend the generated code by using the NetBeans APIs. For more information, see Section 5.7.1, "Generating Skeleton API Implementations". Several tools are provided specifically to help you at this stage of your development cycle. Among them are the following:

• Access to NetBeans sources and Javadoc (for more information, see Section 5.7.4, "How to Use the NetBeans Sources and Javadoc"). After you register the NetBeans sources and Javadoc, you can access them inside the IDE (see Section 5.7.3, "How to Register the NetBeans Sources and Javadoc" for details). This gives you a quick and easy reference to the API classes and methods that you are implementing.

• Search facility for NetBeans APIs (for more information, see Section 5.7.5, "How to Search for NetBeans APIs"). If you know the class that you need to use, but not the module (API or non-API) to which it belongs, a search facility is provided to help you. Once you have identified the module, the IDE registers it in the module project's projext.xml file.

• Code Templates for NetBeans APIs (for more information, see Section 5.7.6, "Code Templates for NetBeans APIs"). For several common tasks, you can type an abbreviation in the Java editor, press the registered expansion key (which is the Tab key, by default), and then the abbreviation will expand to a full piece of code.

5.7.3 How to Register the NetBeans Sources and Javadoc

The NetBeans Platform Manager is a tool for registering different NetBeans platforms with the IDE. A NetBeans platform can be an installation of the NetBeans Platform (see Section 5.2, "About the NetBeans Platform" for details) or an installation of the NetBeans IDE. The default platform is always configured, and is the running IDE. Even in the case that a target platform is the complete IDE, you can easily create an application based only on the platform subset, so that there is little need to download the NetBeans Platform separately. The NetBeans Platform Manager lists all your registered NetBeans platforms in the left pane and lists the platform that the IDE currently deploys to as the default.

You can open the NetBeans Platform Manager by choosing Tools > NetBeans Platform Manager.

Using the NetBeans Platform Manager, you can:

• Register a new platform.

• View a registered platform's available modules.

• Register source code for a platform in the Sources tab. If you register the sources, you do not need to register Javadoc separately, because Javadoc is included in the sources. Either the ZIP file containing the sources or the unpacked root folder can be registered in the Sources tab. You can download the NetBeans sources from https://netbeans.org/community/sources/.

• Register Javadoc documentation for a platform in the Javadoc tab. Javadoc is available from the Plugins manager as "NetBeans API Documentation". Choose Tools > Plugins to access the Plugins manager.

Once you have registered a platform, you can configure a module project to use that platform for deployment. Go to the project's Project Properties dialog box, select the Libraries node, and choose the appropriate platform in the NetBeans Platform drop-down list.

5.7.4 How to Use the NetBeans Sources and Javadoc

Once you have registered the NetBeans Sources and Javadoc (see Section 5.7.3, "How to Register the NetBeans Sources and Javadoc" for details), you can use them as follows:

• In the Source Editor, when you use code completion (Ctrl-Space), Javadoc for the related NetBeans API class is shown in the code completion window.

  You do not need to register Javadoc for this feature to work. Just registering the NetBeans sources suffices.

• In the Source Editor, right-click on a class identifier that belongs to the NetBeans APIs and choose Show Javadoc (Alt-F1). Javadoc for the related NetBeans API class is shown in a separate pane in the Source Editor.

• In the Source Editor, hold down the Ctrl key and move the mouse over a class identifier belonging to the NetBeans APIs. A hyperlink appears. Click on the hyperlink and the cursor jumps to the related NetBeans API class.

5.7.5 How to Search for NetBeans APIs

When using the NetBeans APIs, you may know the class that you need to use, but not the API (or non-API module) to which it belongs. Until you make the API available to your module, you are unable to make use of its classes.

To search for a NetBeans API:

1. Right-click the Libraries node and choose Add Module Dependency.

   The Add Module Dependency dialog box appears

2. In the Add Module Dependency dialog box, in the Filter textbox, start typing the name of the class that you need to use. The Module list narrows, showing only the modules that satisfy the filter.

   If the Show Non-API Modules checkbox is unchecked (default), the IDE excludes any module for which the current module cannot access any packages without an implementation dependency. These are known as "non-API modules". In other words, only modules with public packages are included, or friend packages where this module is a friend.

3. When you find the module that you need to use, click OK. The IDE adds an entry to the project.xml file.

5.7.6 Code Templates for NetBeans APIs

In the Java editor in the IDE, type an abbreviation listed below, press the expansion key (which is Tab, by default), and then the expanded text shown below will be generated.

• Abbreviation: 2do

  Description: Convert FileObject to DataObject

  Expands to:

  try {
      ${dobType type="org.openide.loaders.DataObject" editable="false" 
       default="DataObject"}  
      ${dob newVarName default="dob"} = ${dobType}.find(${fo    
       instanceof="org.openide.filesystems.FileObject" default="fo"}); 
      ${cursor}
        {catch (${etype type="org.openide.loaders.DataObjectNotFoundException"  
        default="DataObjectNotFoundException" editable="false"}    
      ${exName newVarName default="ex" editable="false"}) {    
      ${exctype type="org.openide.util.Exceptions" editable="false"   
        default=""}.printStackTrace(${exName}); 
      }
  

  Example:

  try {    DataObject dataObject = DataObject.find(myFo);
  } catch (DataObjectNotFoundException dataObjectNotFoundException) {  
    Exceptions.printStackTrace(dataObjectNotFoundException);       
  }
  

• Abbreviation: 2f

  Description: Convert FileObject to java.io.File

  Expands to:

  ${fileType type="java.io.File" default="File" editable="false"}
  ${file newVarName default="f"} =
  ${FileUtilType type="org.openide.filesystems.FileUtil"
  editable="false")}.toFile(${fo 
  instanceof="org.openide.filesystems.FileObject"
  default="fo"});
  ${cursor}
  

  Example:

  File file = FileUtil.toFile(myFo);
  

• Abbreviation: 2fo

  Description: Convert java.io.File to FileObject

  Expands to:

  ${fileType type="org.openide.filesystems.FileObject"
  default="FileObject" editable="false"}
  ${file newVarName default="f"} 
  = ${FileUtilType type="org.openide.filesystems.FileUtil"
  editable="false")}.toFileObject(${FileUtilType}.normalizeFile
  (${f instanceof="java.io.File" default="f"})); ${cursor} 
  

  Example:

  FileObject fileObject = FileUtil.toFileObject(FileUtil.normalizeFile(myFile));
  

• Abbreviation: Lka

  Description: Find all implementations of a certain type registered in META-INF/services.

  Expands to:

  ${coltype type="java.util.Collection" default="Collection" editable="false"}  ${obj newVarName default="obj"} = 
  ${lkptype editable="false" default="Lookup" type="org.openide.util.Lookup"}.getDefault().lookupAll(${Type}.class);       ${cursor}
  

  Example:

  Collection<? extends Type> collection = Lookup.getDefault().lookupAll(Type.class);
  

• Variation: lka (i.e., the first character is lowercase)

  Description: Find all implementations of a certain type from a local lookup, e.g., TopComponent, Node, or DataObject.

  Example:

  Collection<? extends Type> collection = myNode.lookupAll(Type.class);
  

• Abbreviation: Lkp

  Description: Find a single typed implementation registered in META-INF/services.

  Expands to:

  ${Type} ${obj newVarName default="obj"} = ${lkptype editable="false" default="Lookup" type="org.openide.util.Lookup"}.getDefault().lookup(${Type}.class);       ${cursor}
  

  Example:

  Type type = Lookup.getDefault().lookup(Type.class);
  

  Variation: lkp (i.e., the first character is lowercase)

  Description: Find a single implementation of a certain type from a local lookup, e.g., TopComponent, Node, or DataObject.

  Example:

  Type type = myNode.lookup(Type.class);
  

• Abbreviation: Lkr

  Description: Assign a single typed instance from META-INF/services to a Result object, to which you can listen for changes.

  Expands to:

  ${coltype type="org.openide.util.Lookup.Result" default="Lookup.Result" editable="false"}  ${obj newVarName default="res"} = ${lkptype editable="false" default="Lookup" type="org.openide.util.Lookup"}.getDefault().lookupResult(${Type}.class);       ${cursor}
  

  Example:

  Lookup.Result<? extends Type> res = Lookup.getDefault().lookupResult(Type.class);
  

  Variation: lkr (i.e., the first character is lowercase)

  Description: Assign a single typed instance from a local lookup to a Result object, to which you can listen for changes.

  Example:

  Result<? extends Type> all = myNode.lookupResult(Type.class);
  

• Abbreviation: lko

  Description: Create a lookup for a local object, e.g., TopComponent, Node, or DataObject.

  Expands to:

  ${Type} ${obj newVarName default="obj"} = ${prov instanceof="org.openide.util.Lookup.Provider"}.getLookup().lookup(${Type}.class);       ${cursor}
  

  Example:

  Type type = myNode.getLookup().lookup(Type.class);
  

• Abbreviation: stat

  Description: Create code for writing text obtained from a Bundle.properties file into the status bar.

  Expands to:

  ${coltype type="org.openide.awt.StatusDisplayer" default="StatusDisplayer" editable="false"}.getDefault().setStatusText(${bundletype type="org.openide.util.NbBundle" default="NbBundle" editable="false"}.getMessage(getClass(), "${KEY}"));${cursor}
  

  Example

  StatusDisplayer.getDefault().setStatusText(NbBundle.getMessage(getClass(), "KEY"));
  

• Abbreviation: nb

  Description: Get a text from a Bundle.properties file.

  Expands to:

  ${coltype type="org.openide.util.NbBundle" default="NbBundle" editable="false"}.getMessage(${classVar editable="false" currClassName default="getClass()"}.class, "${KEY}")
  

  Example:

  NbBundle.getMessage(DemoAction.class, "KEY")
  

  Variation: nbb (i.e., add an additional 'b' character)

  Description: Pass in parameters for formatting the text.

  Example:

  NbBundle.getMessage(DemoAction.class, "KEY", params)
  

5.8.1 How to Bundle a Library

You bundle libraries with your module by using the New Java SE Library Descriptor wizard. This wizard creates a new Java SE library descriptor, which registers the library in the Ant Library Manager. For more information, see Section 5.8, "Bundling Supporting Items".

Java SE Library Descriptor

A Java SE library descriptor is an XML file that, when registered in the layer.xml file, adds a new class library to the IDE's Ant Library Manager. Whenever the module containing the library descriptor is enabled, the library is present in the Ant Library Manager. For example, Struts support provides the Struts libraries in the Ant Library Manager.

To create a new Java SE Library Descriptor:

1. Right-click a module project and choose New > Java SE Library Descriptor.

2. In the Select Library page, you have to specify the library that you want to make available in the Ant Library Manager via the module. You can select a library that is available in the Ant Library Manager or you can click Manage Libraries to use the Ant Library Manager to add the library that you want to make available via the module.

3. Click Next.

4. In the Name, Icon, and Location page, set the following:

   • Library Name. Specifies the name of the new library descriptor.

   • Display Name. Specifies the descriptor's label.

5. Click Finish.

5.8.2 How to Bundle a Project Template or Sample

The New Project Template wizard creates a new project template or project sample. For more information, see Section 5.8, "Bundling Supporting Items".

You can create an NBM file that contains your template or sample. For more information, see Section 5.11.1, "About NBM Files".

When the user installs the NBM file, the template or sample will be available in the New Project wizard.

To create a new project template or sample:

1. Right-click a module project and choose New > Project Template.

2. In the Select Project page, you have to specify the project that you want to make available as a project template or sample. You can use the Project drop-down list to select an open project or you can click Browse to browse to a project in your filesystem.

3. Click Next.

4. In the Name, Icon, and Location page, you have to set the following:

   • Template Name. Specifies the name of the new project template.

   • Display Name. Specifies the template's label. For example, you will see this label in the Plugins manager. (Optional)

   • Category. Specifies the template's category. For example, this will enable the user to find the template more easily in the New Project wizard. (Optional)

   • Package. Specifies the name of the package where the classes will be housed.

5. Click Finish.

6. After completing the wizard, you can do one or more of the following:

   • Tweak the layer.xml file to change the icon or rearrange the position of the template in the New Project wizard.

   • Change the description that will appear in the New Project wizard's Description box.

5.8.3 How to Bundle an Update Center's URL

The New Update Center wizard lets you create a module that registers a update center in the user's Plugins manager. For more information, see Section 5.13.1, "About Update Centers".

In effect, the module bundles the URL to the update center so that the user does not need to register the URL manually. For more information, see Section 5.13.4, "Manually Registering an Update Center URL".

To bundle an update center's URL:

1. Right-click a module project and choose New > Other. In the New File wizard, choose Update Center from the Module Development category. Click Next.

2. In the Update Center Declaration page, you have to set the following:

   • URL to Update Descriptor. Specifies the URL to the autoupdate descriptor.

     You can let the IDE generate the autoupdate descriptor for you. For more information, see Section 5.13.2, "How to Generate an Autoupdate Descriptor".

   • Display Name. Specifies the name that you would like the user to see in their Plugins manager.

3. Click Finish.

5.8.4 How to Bundle a JavaHelp Help Set

A JavaHelp help set provides help files that explain the features and functionality of your module. For more information, see Section 5.8, "Bundling Supporting Items".

To create a new JavaHelp help set:

1. Right-click a module project and choose New > Other. In the New File wizard, choose JavaHelp Help Set under the Module Development category.

2. In the Location page, note the files that will be created and also note that they will be housed in a new folder called docs:

   • -about.html. A sample HTML file that is registered in the idx.xml file, map.xml file, and toc.xml file.

   • -hs.xml. Helpset file.

   • -idx.xml. Index file. Using the map ID created in the map.xml file, you add items to the idx.xml file, with the name of the topic that you want displayed in the index.

   • -map.xml. Map file. Each HTML file must be registered in the map file. The map ID that you create for the HTML file is used in the toc.xml file and idx.xml file.

   • -toc.html. Table of contents file. Using the map ID created in the map.xml file, you add items to the toc.xml file, with the name of the topic that you want displayed in the table of contents.

   • -helpset.xml. The reference file that is registered in the layer.xml file.

   Note: Each of the names above is prefixed by the name of the project. For example, if the project name is myproject, the files above would be myproject-about.html, myproject-hs.xml, etc.

Optionally, if you do not want to include the IDE's default JavaHelp help sets with your module, you can hide them. Particularly when you are creating a rich-client application on top of the NetBeans Platform, it is unlikely that you will want the IDE's JavaHelp help sets to be included with your application.

To hide a JavaHelp help set:

1. In the Projects window, expand the Important Files node.

2. In the Important Files node, expand the XML Layer node, and then wait a moment while the subnodes are loaded.

3. Expand the <this layer in context> node.

4. Within the Services/JavaHelp node, select the nodes of the JavaHelp sets that you want to delete. Choose Delete.

In the layer.xml file, notice that tags have been added, each with a _hidden flag. When your module is installed, the _hidden flag tells the IDE, or the application built on the NetBeans Platform, to exclude the specified items.

5.8.5 How to Bundle a License

Especially when you want to distribute a module, bundling a license is standard procedure. For more information, see Section 5.8, "Bundling Supporting Items".

A license is typically a plain text file.

To bundle a license:

1. Right-click the module project node and choose Properties.

2. In the Project Properties dialog box, click Packaging.

3. Specify the packaging information, which includes the license.

5.9.1 About the System Filesystem

The system filesystem is the central repository for configuration data in NetBeans. It is composed at runtime of a stack of XML layer files supplied by modules in the system. For more information, see Section 5.9.2, "About XML Layer Files".

It is a virtual filesystem that contains configuration information. NetBeans stores a wide variety of configuration information in the system filesystem. For example, the system filesystem contains a folder called Menu, which contains subfolders with names such as File and Edit. These subfolders contain files that represent Java classes which implement the actions that appear in the File and Edit menus.

When you create a module, you are free to create your own folders in the system filesystem to store data that relate to your module. You can also add objects to existing folders. One of the reasons to use the system filesystem is that it enables an application to be constructed piecemeal from pluggable components (modules) without requiring the use of a monolithic "master controller" that knows about everything.

One important aspect of a NetBeans virtual filesystem is that it can fire events to notify the rest of the system when something in it changes. NetBeans listens for changes in the system filesystem, and if, for example, something creates a new object in one of the menu folders, that new item will appear in the menu.

5.9.2 About XML Layer Files

Layer files (layer.xml) are small XML files provided by modules, which define a virtual filesystem. The layer file defines folders and files that will be merged into the system filesystem that makes up the runtime configuration information that the NetBeans Platform and its derivatives (such as the IDE) use. For more information, see Section 5.9.1, "About the System Filesystem".Layer files help to make it possible for modules to be dynamically installed. The components of the IDE whose content is composed from folders in the system filesystem listen for changes in folders and files in a filesystem. If a module is added at runtime, the system filesystem fires changes; the user interface notices that the contents of the folder has changed and updates the user interface to reflect the changes. New modules created using a module project template (for details, see Section 5.6.2, "How to Create a Module Project") do not have an XML layer, but you can add one with the New XML Layer wizard in the New File dialog. You can then expand the node for it under Important Files in your module project to see and modify its contents. The way it is declared is simple:

• In your jar, provide the layer file, for example, com/foo/mymodule/resources/layer.xml

• In your module's manifest, include the following line somewhere in the top section:

  OpenIDE-Module-Layer: com/foo/mymodule/resources/layer.xml

Just as the New XML Layer wizard creates an empty layer.xml file, so some module file templates may add entries, creating a new layer if necessary (for details, see Section 5.7.1, "Generating Skeleton API Implementations"). Other templates just add Java annotations and so do not need an XML layer.

You can use the System Filesystem Browser to tweak the layer.xml file, or you can do so manually using code completion in the Source Editor.

5.9.3 How to Edit an XML Layer File

When editing an XML layer file, you can use code completion (Ctr-Space) in the Source Editor. Alternatively, you can use nodes in a tree view—each node represents an item that a module makes available to the system.

To edit an XML layer file:

1. In the Projects window, expand the Important Files node.

2. Expand the XML Layer node. After a moment, two subnodes appear:

   • <this layer>. The folders and files provided by the current module project's layer file.

   • <this layer in context>. All the folders and files provided by all the layer files in all modules available in the system.

3. Expand a subnode to explore the folders and files within it. When you right-click a subnode, you can, for example, rename it. You can also use actions such as "Cut", "Copy", and "Paste". In addition, you can drag a subnode and drop it elsewhere, to reorder a folder or a file. All of these actions will result in XML entries being added to your module project's layer file.

5.9.4 How to View the System Filesystem

The system filesystem is the general registry for publicly accessible data and objects. For more information, see Section 5.9.1, "About the System Filesystem". It is a virtual filesystem that contains configuration information. Layer files (layer.xml) define folders and files that will be merged into the system filesystem. For more information, see Section 5.9.2, "About XML Layer Files".

To view the system filesystem:

1. Create a module project. For more information, see Section 5.6.2, "How to Create a Module Project".

2. In the Projects window, expand the Important Files node.

3. Expand the XML Layer node. After a moment, two subnodes appear:

   • <this layer>. The folders and files provided by the current module project's layer file.

   • <this layer in context>. All the folders and files provided by all the layer files in all modules available in the system.

4. Expand a subnode to explore the folders and files within it.

   When you right-click a subnode, you can, for example, rename it. You can also use actions such as "Cut", "Copy", and "Paste". In addition, you can drag a subnode and drop it elsewhere, to reorder a folder or a file. All of these actions will result in XML entries being added to your module project's layer file.

5.10.1 About Service Providers

In version 1.3, the JDK started to use a concept called service providers. This concept introduces a completely declarative style of registration, which is based just on the current classpath of a Java virtual machine and nothing else. This has an important advantage greatly contributing to the ease of use of this registration style: in order to change the set of registered providers, just pick up a JAR file that offers such a provider and include it in application classpath. Immediately its provider will be accessible to all code that searches for it.

The basic idea is that each JAR file (in NetBeans terminology, each module) that wishes to provide an implementation of some interface, for example javax.xml.parsers.DocumentBuilderFactory, can create its own implementation of the interface, say org.sakson.MyFactory, and expose it to the system as a service by creating a META-INF/services/javax.xml.parsers.DocumentBuilderFactory file inside of its own JAR file. The file then contains a name of the implementation class per line. In this example it would contain one line registering the sakson factory: org.sakson.MyFactory.

The DocumentBuilderFactory.newInstance method then searches for all META-INF/services/javax.xml.parsers.DocumentBuilderFactory files by using ClassLoader.getResources("META-INF/services/javax.xml.parsers.DocumentBuilderFactory"), reads their content, and instantiates the class(es) found there by calling their default constructors. The first implementation of the DocumentBuilderFactory is then returned from the newInstance method.

While you can manually create the registration of a service in your module, usually you will use the org.openide.util.lookup.ServiceProvider annotation, which creates such a registration for you automatically.

As already mentioned, this style has been in place since JDK 1.3 and is a standard way to deal with service providers. Not only has NetBeans adopted this style, it is also gaining in popularity among other Java developers. As a result, JDK 1.6 has introduced the new utility class java.util.ServiceLoader.

5.11.1 About NBM Files

An NBM file is a NetBeans module packaged for delivery via the web. For more information, see Section 5.1, "About NetBeans Modules". The principal differences between NBM files and module JAR files are:

• An NBM file can contain more than one JAR file—modules can package any libraries they use into their NBM file.

• An NBM file contains metadata that NetBeans will use to display information about it in the Plugins manager, such as the manifest contents, the license, etc.

• An NBM file may be signed for security purposes.

• NBM files are just ZIP files with a special extension. They use the JDK's mechanism for signing JAR files. Unless you are doing something unusual, you need not worry about the contents of an NBM file—just let the standard Ant build script for NBM creation take care of it for you.

5.11.2 How to Build an NBM File

An NBM file is a NetBeans module in binary format, packaged for delivery via the web. For more information, see Section 5.11.1, "About NBM Files".

To build an NBM file:

1. In the Projects window, right-click the node of the module project you want to build.

2. Choose Create NBM.

To build all NBM files in a module suite:

1. In the Projects window, right-click the node of the module suite project you want to build.

2. Choose Create NBMs.

   When you choose Create NBMs in a module suite's contextual menu, an autoupdate descriptor is generated by the IDE. The autoupdate descriptor describes all the NBM files. When you put the autoupdate descriptor on a server, your users can access it and retrieve your NBM files via the autoupdate descriptor. For more information, see Section 5.13.2, "How to Generate an Autoupdate Descriptor".

5.12.1 Deploying Modules

When an application based on a NetBeans Platform is run, the NetBeans Platform's Main class is run. It then finds the available modules and builds an in-memory registry of them, and performs any tasks they specify for startup. Generally, a module's code is loaded into memory as it is needed.

5.13.1 About Update Centers

An update center is nothing more than an XML file that is known as the ”autoupdate descriptor”, together with the modules that it describes. The autoupdate descriptor lists all the modules that you would like to make available. For each module, the autoupdate descriptor provides information such as a name, a description, and a list of modules that it depends on.

Most importantly, the autoupdate descriptor specifies a URL for each module that it describes. Each module, in binary NBM file format, must live on a server. For more information, see Section 5.11.1, "About NBM Files".

The autoupdate descriptor itself must also live on a server. The server where the autoupdate descriptor lives need not be the same server as where the modules live. The modules can live together on the same server or be spread across different servers.

After the autoupdate descriptor and its associated modules are on a server, you must let your end users know that they are there. The URL to the autoupdate descriptor must be registered in the end users' IDEs. This can be done in one of two ways:

• Automatically. You can provide a module that registers the URL to the update center for them. This module can be generated in the IDE, without any coding on your part.

• Manually. You must tell your end user what the URL to your autoupdate descriptor is. Then, the end users need to register the URL to your autoupdate descriptor. They must then do so manually in the Plugins manager.

Once the URL to the update center is registered, your end users can access your modules via the Plugins manager, which they can find under the Tools menu. Not only new modules, but new versions of existing modules can be distributed in this way.

5.13.2 How to Generate an Autoupdate Descriptor

An autoupdate descriptor is an XML file that describes the NBM files that you want to make available to your users. For more information, see Section 5.11.1, "About NBM Files".

For example, an autoupdate descriptor specifies a name, a description, and a URL for each module that it describes.

When you put an autoupdate descriptor on a server, and make its URL available to your users, your users are able to register the URL in your IDE. After registering the URL, they can access your NBM files via the Plugins manager, under the Tools menu.

To generate an autoupdate descriptor:

1. If you have not already done so, create a module suite project. For more information, see Section 5.6.4, "How to Create a Module Suite Project".

2. In the Projects window, right-click the node of the module suite project you want to build.

3. Choose Create NBMs.

   The IDE builds the NBM files in the module suite project. The IDE also creates a file called updates.xml, which is the autoupdate descriptor. To see it, look in the Files window (Ctrl-2).

4. Tweak the autoupdate descriptor, if needed. For example, customize the distribution element for each module, so that the URL to the NBM file is correct.

5.13.3 How to Bundle an Update Center's URL

The New Update Center wizard lets you create a module that registers a update center in the user's Plugins manager. For more information, see Section 5.13.1, "About Update Centers". In effect, the module bundles the URL to the update center so that the user does not need to register the URL manually. For more information, see Section 5.13.4, "Manually Registering an Update Center URL".

To bundle an update center's URL:

1. Right-click a module project and choose New > Other. In the New File wizard, choose Update Center from the Module Development category. Click Next.

2. In the Update Center Declaration page, you have to set the following:

   • URL to Update Descriptor. Specifies the URL to the autoupdate descriptor.

     You can let the IDE generate the autoupdate descriptor for you; for details, see Section 5.13.2, "How to Generate an Autoupdate Descriptor".

   • Display Name. Specifies the name that you would like the user to see in their Plugins manager.

3. Click Finish.

5.13.4 Manually Registering an Update Center URL

If you have not been provided with a module that bundles an update center's URL, you need to register the update center manually. For more information, see Section 5.8.3, "How to Bundle an Update Center's URL".

Once you have registered the update center, you can access its modules via the Plugins manager, which you can access under the Tools menu.

To manually register an update center's URL:

1. Choose Tools > Plugins.

   The Plugins manager opens.

2. Click the Settings tab at the top of the Plugins manager.

3. Click Add.

4. Type the name and URL of the autoupdate center. The name can be anything you want it to be. Click Finish.

5. Click Close.

You have now manually registered the update center's URL.

5.14.1 How to Brand the Window System

You can brand an application's window system by disabling the following of its default features:

• Window Drag and Drop. The ability to reorganize the window layout by dragging windows to new positions.

• Floating Windows. The ability for windows to be undocked into a standalone frames.

• Sliding Windows. The ability to minimize (slide out) a window.

• Maximized Windows. The ability to maximize a window by clicking its header.

• Closing Windows. The ability to close a document/non-document window.

• Window Resizing. The ability to adjust the width and height of windows by dragging splitter bars.

• Respect Minimum Size When Resizing Windows. The ability to resize internal windows to zero width/height using splitter bars.

To brand the window system:

1. Right-click the application project in the Projects window and choose Branding.

2. In the Branding editor, click Window System.

3. Deselect the items listed above, depending on your needs.

4. Click OK to confirm your choices and exit the Branding editor.

5.14.2 How to Add a Splash Screen

1. Right-click the application project in the Projects window and choose Properties.

2. In the Project Properties dialog box, click Splash Screen. Do the following:

   • Define the progress bar.

   • Choose a splash screen.

3. Click OK to confirm your choices and exit the Project Properties dialog box.

5.14.3 How to Remove Unwanted Modules

You can exclude unwanted modules from a standalone application, leaving only those you really need. By default, all the modules that the IDE uses are included.

To remove unwanted modules:

1. Right-click a module-suite project and choose Properties.

2. In the Project Properties dialog box, click Libraries.

3. Uncheck all the clusters that you want to exclude from the standalone application. The only cluster that all standalone applications need is platformNNN.

4. Expand the nodes of the clusters that you want to keep, and uncheck any module that you want to exclude from the cluster.

5. Click OK.

When you brand a standalone application (for details, see Section 5.14, "Branding a Rich-Client Application"), the IDE asks you whether it should exclude IDE-related modules for you. If you do not let the IDE exclude IDE-related modules, you can do so manually using the steps above.

5.15.1 How to Build a ZIP Distribution

Once your rich-client application is complete, one way to distribute it is via a ZIP file. The IDE can create the ZIP file for you, containing the application.

To build a ZIP distribution:

1. In the Projects window, right-click the node of the application.

2. Choose Package as | ZIP Distribution.

5.15.2 How to Build a JNLP Application

Java Web Start is a helper application that becomes associated with a Web browser. When a user clicks on a link that points to a special launch file (JNLP file), it causes the browser to launch Java Web Start, which then automatically downloads, caches, and runs the given Java Technology-based application. The entire process is typically completed without requiring any user interaction, except for the initial single click.

To build a JNLP application:

1. In the Projects window, right-click the node of the module suite project you want to build.

2. Choose JNLP | Build.

3. Depending on whether you have set up the module suite project as a standalone application, do the following:

   • If you have already set up the module suite project as a standalone project, the IDE builds a jnlp folder in your build folder and adds a master.jnlp file in your main project folder. Open the Files window to see the JNLP file and the folder within the build folder.

   • If you have not set up the module suite project as a standalone application, the IDE will not be able to build the JNLP application. The IDE will tell you this by means of a dialog box.

     • Click Configure Application in the dialog box. The Project Properties dialog box opens. Click Build.

     • Select the Create Standalone Application radio button. Click OK.

     • In the Projects window, right-click the node of the module suite project you want to build.

     • Choose Build JNLP Application.

       The IDE builds a jnlp folder in your build folder and adds a master.jnlp file in your main project folder. Open the Files window to see the JNLP file and the folder within the build folder.

5.15.3 How to Run a Rich-Client Application

Unless your NetBeans modules are designed to be deployed as standalone modules, you should always deploy them by deploying the application (the module suite project) that contains them. If you run the Run Project command on an individual module that is part of an application built on top of the NetBeans Platform, the IDE only deploys that module itself.

To deploy a standalone application:

• In the Projects window, right-click the module suite project and choose one of the following:

  • Run Project. Starts the target platform, undeploys the standalone application if it is already deployed, deploys the standalone application to the target platform, starts the platform and loads the application as one unit.

  • Run JNLP Applications. Builds and runs the application as a JNLP application. For more information, see Section 5.15.2, "How to Build a JNLP Application".

5.15.4 How to Use the NetBeans Shared JNLP Repository

By default, the JNLP application generated for a module suite project always contains all the module suite project's modules as well as all the modules that the module suite project depends on. This may be useful for intranet usage, but it is a bit less practical for wide internet use. When on the internet, it is much better if all the applications built on the NetBeans Platform refer to one repository of NetBeans modules, which means that such modules are shared and do not need to be downloaded more than once.

There is such a repository for NetBeans modules. It does not contain all the modules that NetBeans IDE has, such as, for example, the ant module, which is not JNLP-ready, but it contains enough to make many JNLP applications possible.

To use the shared JNLP repository:

1. In the Projects window, expand the Important Files node.

2. Double-click NetBeans Platform Config.

3. Add the jnlp.platform.codebase property with, as its value, the URL of the 5.0 JNLP Repository:

   jnlp.platform.codebase=http://www.netbeans.org/download/5_0/jnlp