The Java Beans specification defines how components should interact with an integrated development environment (IDE), and various classes that both an IDE and a component vendor will use to communicate with the IDE and vice-versa. The fundamental problem with the beans specification is that, when it was created and cast in stone, there were no Java IDEs. The specification tends to be in some cases naively defined (BeanInfo), and in other cases woefully underspecified (PropertyEditor) with respect to what an IDE or a component will actually need to provide a good user experience.

It is possible to create generic property editors that will integrate with an IDE without depending on that IDE — and where this makes sense, it is encouraged to do that. However, there are many cases where that is not sufficient. For example, the specification for java.beans.PropertyEditor simply allows a property editor to return a java.awt.Component to provide a custom editor dialog. In practice, that component will be shown to the user in a dialog - and if it is possible for the user to provide invalid input, good UI design dictates that the OK button for that dialog should be disabled when the input is not usable. But there is no communication path for a component to tell an IDE about such a situation. Similarly, a property editor that lets the user supply an image needs to allow the user to choose a file on disk to use. If the image is not on the classpath of the project, it needs to be copied into some directory where it can be found at runtime — but there is no way for an IDE to communicate to a third party property editor anything about files or directories or classpaths.

For these cases, NetBeans provides APIs that fill some of the gaps in the beans spec. NetBeans also provides sophisticated user interface controls that can save time and create a better user experience if used.

_ NetBeans' custom editor for Borders uses NetBeans' Nodes and Explorer API to provide the list of available borders in an embedded property sheet. _

The first step in packaging up some components is creating some components, so we will start by creating a simple Java project.

We will start with a fairly simple (if slightly artificial) class. We need to create the ColorValue class which is the type of one of `Bean1’s properties (later we will handle a much more complex data type requiring a more sophisticated custom editor).

Now we need to create a NetBeans plug-in (module) which will do three things:

NetBeans comes with built-in support for creating modules, so setting up a new module project is quite simple:

Modules which install Java libraries — particuarly ones which add components to the component palette should always require a restart of the IDE. There are two reasons for this:

Causing a module to request that the IDE restart itself before it is installed is as simple as checking a checkbox:

We now have a plug-in. However, we will want it to bundle the Bean project. So before going further, it would be useful to do the following:

Doing these things involves overriding two targets in our module project’s build script. Ant supports a crude sort of target inheritance, in which we replace a target from one build script, but call the original target by referring to [projectname].[targetname] (the project name in this case is the name defined in the <project> tag at the top of any Ant build script).

===Listing 3: Module Build Script Changes

Most of the targets in the build.xml for a module project are in other files — specifically, in nbproject/build-impl.xml and in $HARNESS/build.xml and $HARNESS/common.xml ($HARNESS is a directory under the copy of NetBeans you are building against, which may or may not be your IDE). To find out what file a target you are calling or overriding is in, find the build.xml in the Files tab in the IDE. Expand its node and you will see all of the targets (even ones in other files). Right click the target you are wondering about and choose Open to open the file which contains that target in the IDE. The path on disk to the file will be shown in the tooltip of its tab in the editor.

This code will build the Bean project, and copy the resulting JAR file to BeanLibraryModule/release/libs. The build script will bundle anything under the release subdir of a module into the NBM file you will deliver to your users (for example, via an update server found via Tools > Plugins).

At this point, it is a good time to make sure everything is working correctly. You can test this by right clicking BeanLibraryModule in the Projects tab, and choosing Build from the popup menu (or by pressing F11).

Now we need to add some metadata to our module — no code yet — to make Bean.jar appear in the list of libraries for users who have installed our module. This involves two steps:

===Listing 4: Adding Library Metadata to a Module’s XML Layer

The url attribute of the file tag is important — the XML we have entered defines a virtual file — but a file name is usually useless without some content. The URL attribute is a path, relative to the layer file, in the location where it really lives on disk. The next step is to actually create a file called Bean.xml.

===Listing 5: An XML Library Definition for Bean.jar

Note that there are placeholders in this file for Javadoc documentation and source files. If you want to include these later, just create targets in Bean/build.xml to build and zip the javadoc and sources into zip files, and modify BeanLibraryModule to call those targets in the Bean project and copy the additional files into the same directory as Bean.jar; then add <resource> tags similar to the one already in this file, but pointing to the zip files. Such files are helpful for users who want instantly available documentation, or wish to step through your component’s code in a debugger.

All user-visible strings in NetBeans are localized — put into resource-bundle files, so they can be translated into other human languages. Things which are installed declaratively via layer.xml files are no exception. You may have noticed that a localizing bundle is mentioned in some of the XML we have already entered. This is a pointer to a file named Bundle.properties, which should live in the package org.netbeans.demo.form.beanlib alongside our other files. If it does not exist, create it as follows:

We are bundling the JAR file as a library. However, if we want property editors which can talk to both our Java Bean classes and to NetBeans itself, we will need to put Bean.jar onto our module’s classpath as well. NetBeans is very strict about what JARs a module can see classes from, and by default, a library is for use in the projects a user creates, not for loading in to the VM NetBeans is running in. So we need to explicitly include Beans.jar in our module’s classpath if we want to be able to use classes from it in our module — and if we want to provide NetBeans-aware property editors we need to do that.

Not everybody needs property editors that interact with the IDE beyond the very limited ways the Java Beans specification allows. If you are writing ordinary property editors, you can simply skip the rest of this step, then follow the later steps to add your beans to the component palette and stop there:

To add Bean.jar to the classpath of classes in your module, do the following:

We have our library embedded in our module — next we need to put our component on the Component Palette, so users will be able to drag and drop it into their user interfaces. Doing that is quite simple, and very similar to the way we added Bean.jar as a library — it will again involve editing the layer.xml file, adding a reference to an external XML file and then creating that file.

Now we are ready to create a property editor. We will put our editors in another package, org.netbeans.demo.form.beanlib.editors — in accordance with the Java Beans specification, that package will be registered with java.beans.PropertyEditorManager. We don’t need PropertyEditorManager to be able to find other classes that are part of our module, but are not our property editors or classes our property editors use. So keeping unrelated classes invisible to our property editors is good sense both from a perfomance and a security perspective.

We now have a property editor for ColorValue objects. The next step is to register our property editor package, so that, when our module is run in the IDE, java.beans.PropertyEditorManager can find our editor and it will be used in the Property Sheet of the Form Editor.

While most of the time, the way you install things in NetBeans, so that the IDE can find your module’s classes at runtime, is declarative — using the layer.xml file and similar mechanisms — PropertyEditorManager is not part of NetBeans, it is part of the JDK. It expects registration to be done programmatically, via Java code that runs during IDE startup. Running code during startup is generally to be avoided, since it means the user will be looking at the startup splash-screen for longer, but in this case there is no other way.

To register our property editor, we need to create a subclass of org.openide.modules.ModuleInstall, and add a reference to it to our module’s JAR manifest. Fortunately, there is a file template built into NetBeans' module-writing tools that will take care of creating the subclass and adding the manifest entry — we can use that and then just add the code we need to the resulting ModuleInstall. To do that:

At this point we are almost ready to run our module with our property editor. There is one bit of arcana left to take care of. As mentioned earlier, NetBeans does various tricks with classloaders — in particular, limiting classes a module can see to only those ones it says it needs access to.

A Swing GUI and its libraries are classes that belong to the user — they are not parts of NetBeans. The form editor takes a similar approach — Java classes used in a Swing UI are loaded into the Java Virtual Machine NetBeans is running in; however, they are loaded in their own classloader, which normally does not allow random components access to classes from a module. This has two beneficial effects:

We have already set up the classpath so that our module can see classes from Bean.jar. We need to set up the reverse situation — allow our properties to call into classes in our module and the rest of NetBeans when they are loaded inside the sandbox of the classloader the form editor uses for loading the user’s components.

This is accomplished via a bit of black magic with the form editor’s classloader. The form editor allows us to define a special text file in our layer.xml file, which contains a list of classes and/or packages that should be visible to components living inside a Swing form. To accomplish this:

To really interact with the IDE, we should add support for a custom (pop-up window) editor for our ColorValue property. To do that:

Figure 2: Color Value Custom Editor User Interface

Table 1: Component Variable Names and Types in ColorValueCustomEditor

The last thing we may want to do is more about plumbing than anything the user sees directly: When you are editing a Swing form in the NetBeans Form Editor, you are really editing two files (though you only see the Java file in the projects tab). The form editor is really an editor for an invisible (in NetBeans) XML file that sits next to the Java source file. The form editor is really an editor of that XML file. Whenever you make a change in the form editor, the data about how components are positioned and their properties is saved in that file. That file is then used to generate the initComponents() method and other code inside the non-editable blue code blocks in your Java source. Whenever the XML file changes (because you made a change in the form editor and saved the file), those blue guarded blocks are regenerated into the Java source file.

It is worth taking a look at the .form file after you have modified a ColorValue and saved the form (make sure you save it!). To do this, you will need to go outside of NetBeans and use a text editor (if on Windows, use a text editor that understands lines that end with just a carriage return character — WordPad, usually located in C:\Program Files\Windows NT\Accessories on Windows will do). What you will see is something like this:

What are all of these numbers? This is a serialized object. The form editor knows nothing about your component, but needs some way to save the state of our ColorValue object. The only built-in way Java has to do that is to use serialization to save the in-memory representation of your object as an array of bytes. The form editor then translates that array of bytes into a terribly inefficient comma-delimited string of numbers.

There are four big problems with using serialization to write out an object into the form file:

There is another way. Although nobody truly loves writing DOM code, you can implement XMLPropertyEditor. What happens then is:

By using XML instead of serialization, we get to choose what data we store in the .form file, how it is stored, and our code is in charge of reading it back. If new properties or fields have been added to ColorValue and we are reading an old form, we can just ignore missing values and use some reasonable default value. The result is that our users are protected from having corrupted, unopenable forms caused by upgrading to a new version of Bean.jar. To use this approach instead,

Once you have your module the way you like it, the next step is to package it up so that others can install it. In NetBeans, this is extremely simple: Just right click the module project and choose Create NBM. This will create an NBM (NetBeans Module) file which includes your module and your library in a single file any user can install using Tools > Plugins. Users of your component do not have to deal with separate JAR and documentation downloads, and if they want an updated version of your components, all they have to do is install a new NBM to get them.

A useful way to deliver components is to set up your own update center. An update center has a list of NBM files for download. Users of NetBeans can just add the URL for your update center on the Settings tab in Tools > Plugins. The IDE will automatically check with your server on a regular basis to see if there are updates available.

You can make this process even easier by doing two things:

NetBeans provides a powerful way to deliver Java components to your users, including all of the documentation and sources to your users and potential users in a single easy-to-use deliverable. By creating property editors that integrate tightly with NetBeans, you can further enhance the ease of use of working with your components.