Tips for Module Authors - NetBeans API Javadoc 4.1.0

Tips for Module Authors

This document provides a few tips for module authors, centering around the basic steps that you need to take to get a hello-world module up and running, and how to progress from there.

Installing the Module into the IDE

Under Tools | Options | Modules you will find a list of all modules installed in the IDE. Some "test" modules are distinguished with a red T superimposed on the module icon, meaning that they are reloadable. All modules can in principle be reloaded after they are installed if you just disable them, change their JAR file, and enable them again; in practice, various IDE and JDK bugs can make this not work reliably. If a module's Reloadable property is set to True (this property only appears with the special startup option -J-Dnetbeans.module.test=true, set also by the API Support), then the IDE will treat it in a special way making it reliable to reload it while the IDE is still running.

Do not place your module's classes into the IDE's startup classpath. If you do so, it may seem to work, but the classes will be loaded from the wrong classloader: the startup loader and not the module loader (for regular modules) or the user loader (for test modules). Various subtle errors can occur in this case. For this reason, the IDE will try to detect this situation and warn you about what is wrong.

Support module: the default executor for module JARs installs the module into the running IDE in test (reloadable) mode. If you execute it again, the JAR will be reloaded so normally there is no need to restart the IDE while testing! This is merely a presentation variant of using test modules from the Modules node. Note that you can make a regular module reloadable and reload it without restarting the IDE.

The support module also defines a special Ant task, <nbinstaller/>, which can be used to install module JARs in test mode from within an Ant script.

The Update Center feature (from the Tools menu) also permits you to dynamically publish module updates and upgrade them from an update server, which might live on netbeans.org, or on the Forte Portal, or on your own special server. Please see the Update Center's home page for more details on making NBM (NetBeans Module) packages and publishing them.

Testing the Module

The main device for testing modules is to develop them in test mode, as above. This permits you to make changes and try the changes within seconds of recompiling.

There is not much to say specifically about how to test modules once you are sure they got installed, other than trying out their functionality. Mainly, keep your console window open! If running on Unix, make sure you ran NetBeans from a command window (e.g. xterm) so that its output is visible. If there are any serious errors or diagnostics, they may be printed to the console, so you should check this window if in doubt.

If messages overrun the available space on screen, you must make sure the console window is scrollable. On Unix, this is usually true by default. On Windows, you should give the console window a scroll buffer - right-click on the "MSDOS" icon in the upper-left corner of the window, select "Properties...", go to the "Layout" tab, and make sure "Screen Buffer Size" is set to something appropriate (e.g. a few hundred wide, and a thousand or two tall). Save your settings, and agree to apply them to the shortcut so that they will take effect the next time you restart.

You may want to turn on various ErrorManager flags, though exactly which ones will depend on what you want to know. For example, to debug the modules infrastructure, add to your command-line options (or ide.cfg file): -J-Dorg.netbeans.core.modules=0

Support module: If your manifest file syntax is incorrect, a red X will appear superimposed on the JAR or manifest icon. You can check the property sheet to see the exact errors. Of course, other parts of the module are not checked by this, just the manifest syntax.

Testing Code Outside of Modules

To just test out functionality of the Open APIs, without necessarily wrapping everything up in a module, you can just write Java main classes that set up some test code, and use System.out.println (e.g.) to display the results. You must set such a file to use internal execution; then the code will be run inside the IDE, so you can test it as you go. You can use the Scripting Console to use your favorite scripting language to test expressions interactively. Also, you can use the debugger to display the values of variables.

Debugging Modules

The difficulty in debugging is that it is not possible to debug a module by itself within the IDE, since it runs within the same VM as the IDE and integrates into it. The same goes for code which needs to be run in internal execution (as it makes API calls) - there is no such thing as "internal debugging" using the normal VM-supported debugger implementation. So, you will need to run the entire IDE in debugging mode, using either another copy of the IDE, or some alternate debugger such as command-line JDB, and set breakpoints on the module code of interest. (Note that module code is dynamically loaded, i.e. not statically referenced, and therefore you may need to delay settings breakpoints until the module has already been loaded.) To use (another instance of) the IDE as the debugger, you should modify the startup script of the to-be-debugged IDE to include -Xdebug (and maybe -classic for HotSpot, and some sundry other flags for JPDA as documented in general for the JPDA switches) and also include tools.jar (from the JDK) in the boot class path. Start the debuggee manually and use the connect-to feature of the IDE's debugger to connect to the process as usual with the host name and agent password (or for JPDA, socket or shared memory segment or whatever is required).

To avoid running the whole IDE in a debugger (this may be slow), you may prefer to use the fallback method of including copious debugging statements which print interesting information as the IDE runs your module code. In practice this is feasible - most API objects either have a sensible implementation of Object.toString(), or provide an obvious display name that would identify them easily when printed. Printing to System.err will not only print to the console, but will include the output in the netbeans.log file in the installation's system/ directory, for later perusal. See above for redirecting output to the Output Window. If you use test modules, it is simple enough to insert a few debug prints, reload, see what is going wrong, try to fix it, verify that it is fixed, and then remove the statements again.

The scripting module (currently on Auto Update) may be used to evaluate expressions and run commands interactively inside the IDE's VM.

The ErrorManager may be used to emit debugging information from modules at customizable output levels, so that critical diagnostic information can be left in production code and dynamically enabled when required.

If you are having problems related to Java security mechanisms, there are a couple of things you can do. First, if SecurityException is being thrown, you can add -J-Djava.security.debug=access,failure to the IDE's command-line options to show the ProtectionDomain that failed. Second, if you are getting IllegalAccessError, try printing to standard error IllegalClass.class.getProtectionDomain().getCodeSource(), which will show the URL from which the class was loaded; if this URL is outside the IDE's installation, it is likely you need to manually add permissions to the relevant classloader.

Support module: many things about the IDE that you might wish to know (current settings and status of various objects, etc.) can be seen under Runtime | Bean Browser, without running a debugger.