NetBeans Ruminations

During an average day working on an Ant-based NetBeans Platform application, a developer would constantly use the project actions such as “Build”, “Clean” and “Test” in the NetBeans IDE. But when the application needs to be built on a build server, a way needs to be found to perform these actions from the command line. Since the projects are already Ant-based, and the actions in the IDE are linked to Ant build scripts, this is luckily straight forward. The only question is which target(s) to call.

For more information about the Ant-based build harness and how it is structured, have a look at this article. (Note that there are multiple parts, and part 2 is especially useful in this context.) But for now the only really important part to note is that all Ant-based NetBeans Platform Applications (suites) and modules have a build.xml file.

Before listing the Ant targets that are generally useful, I would like to explain how to find them yourself. The first and most difficult way is to find the action in the IDE source code. I have done this before, but it is in almost all cases complete overkill. The second option is to expand the Build Script under Important Files in the project, to see a complete list of all the targets that are available. While this is much easier, it is still not the most direct route.

The best option in almost all cases is to perform the action and then look at the title of the Output window. The name of the project appears there, followed by the target(s) in brackets.

Targets applicable to NetBeans module projects

• netbeans – Build action in the IDE – compile the module, creating artifacts in the build folder of the module as well as the build folder of the suite
• clean – Clean action in the IDE – removes the contents of the module’s build folder
• nbm – Create NMB action in the IDE – creates an nmb file for the module in its build folder
• test-unit – Test action in the IDE – executes the unit tests in the module and creates artifacts in the build/test folder of the module

Note: For standalone modules, the same targets apply. The difference is that for the netbeans target, all the artifacts are placed in the module’s build folder.

Targets applicable to NetBeans Platform application suites

• build – Build All action in the IDE – builds all the modules contained in the suite
• clean – Clean All action in the IDE – cleans all the modules in the suite and removes the build and dist folders of the suite
• build-zip – Package as > ZIP Distribution action in the IDE – builds all the modules in the suite and then creates a .zip file in the dist folder of the suite
• nbms – Package as > NBMs action in the IDE – builds all the modules in the suite and then creates a .nbm for each of the modules in the suite’s build/updates folder
• test – Test All action in the IDE – executes the unit tests in each of the modules contained in the suite and creates artifacts in the build/test folder of each module

A recent question on the NetBeans Platform Users forum made me think again about the layer file and its current place in the platform. And so I decided to write this post. Note that this post is about the NetBeans Platform, and specifically version 7.1.

The layer file used to be the place where almost all extensions to the NetBeans Platform got registered. So what do I mean by extensions? When you are developing a NetBeans module, some of the typical things you might want to do is create new windows and menu items and toolbar buttons. These all plug into and extend the platform’s window system. The wizards provided by the IDE to simplify the creation of these extensions, created the layer file entries as well as the classes containing the actual functionality. At runtime the platform reads all the information in the layer file and uses those registrations to load the right classes and use them in the appropriate ways.

And then came the annotations. This is another way of representing the same information by applying annotations directly on the classes instead of keeping the registrations in a separate file. As far back as version 6.7 some annotations were introduced. (See Geertjan’s blog post about the annotations implemented back then.) Slowly but surely the layer file entries in the platform were replaced by the much more maintainable annotations. And in version 7.1 the platform is now at the point where pretty much all the extensions are no longer directly based on layer file registrations.

On a side note. I say ‘directly based’ because there is still a layer file in the background. Many (but not all) of the annotations have a source level retention (for example TopComponent.Registration). These annotations are processed at compile time, and one of the possible outputs is a generated layer file. The generated file will appear in the module’s .jar file once it is built, in the META-INF folder and will be called generated-layer.xml.

With the advent of this moment, another small but noticeable change was made. The new module wizard no longer allows the user to choose to create a layer file. It was the logical thing to do, since in almost all cases the layer file would remain empty and having an empty layer file contributing to the file system is inefficient. And for the rare cases where you still need a layer file, there is now a new file wizard that allows you to create one. It can be found at File > New File… under the Module Development category.

The layer file is dead… long live the layer file!

The NetBeans Platform allows you to define file types. Each file type has its own behaviour associated with it. The File Type Integration Tutorial provides a lot of information about how the file types can be created and customised.

With NetBeans Platform 7.1, it is now possible to register a file type with the @TemplateRegistration annotation instead of using the layer file. To manually convert an existing file type (read the tutorial to find out how to create one) to use the new annotation, follow these steps:

1. Remove the contents of the layer file.
2. Add a package-info.java file to the module, containing the following:

@org.netbeans.api.templates.TemplateRegistration(folder="Other",
    content="ABCTemplate.abc", displayName="Empty ABC file")
package org.myorg.abcfiletype;

Clean and build the module, and inspect the generated layer file to see the result. The generated layer file will be located at build/cluster/modules/AbcFileType.jar/META-INF/generated-layer.xml.