Code Generator Integration Tutorial

This tutorial shows you how to write a module that integrates new items into the NetBeans code generation feature, which appears when you click Alt-Insert in an editor.

Contents

• Introduction to Code Generator Integration
• Creating the Module Project
• Using the Code Generator Provider Wizard
• Coding the Code Generator Integration
• Installing and Trying Out the Functionality
• Creating a Shareable Binary

To follow this tutorial, you need the software and resources listed in the following table.

Software or Resource	Version Required
NetBeans IDE	version 6.5
Java Developer Kit (JDK)	Version 6 or version 5

Optionally, for troubleshooting purposes, you can download the completed sample and inspect the sources.

Introduction to Code Generator Integration

The Code Generator feature, introduced in NetBeans IDE 6.5, consists of a list of items that appears when you press Alt-Insert. Each item generates code into the editor.

Creating the Module Project

In this section, we use a wizard to create the source structure that every NetBeans module requires. The source structure consists of certain folders in specific places and a set of files that are always needed. For example, every NetBeans module requires a nbproject folder, which holds the project's metadata, and a layer.xml file, for declarative registration of items such as toolbar buttons and windows.

1. Choose File > New Project (Ctrl-Shift-N). Under Categories, select NetBeans Modules. Under Projects, select Module and click Next.
2. In the Name and Location panel, type DemoCodeGenerator in Project Name. Change the Project Location to any directory on your computer, such as c:\mymodules. Leave the Standalone Module radiobutton selected. The panel should now look as follows:

   

   Click Next.

3. In the Basic Module Configuration panel, type org.netbeans.modules.demo as the Code Name Base. Select the "Generate XML Layer" checkbox and leave the location of the localizing bundle and XML layer as they are, so that they will be stored in a package with the name org/netbeans/modules/demo. The panel should now look as follows:

   

4. Click Finish.

The IDE creates the DemoCodeGenerator project. The project contains all of your sources and project metadata, such as the project's Ant build script. The project opens in the IDE. You can view its logical structure in the Projects window (Ctrl-1) and its file structure in the Files window (Ctrl-2).

Using the Code Generator Provider Wizard

In this section, we use a wizard to create the stub class and layer entries necessary for beginning our integration with the Code Generator feature.

1. Right-click the project node and choose New > Other. In the New File dialog, choose Module Development > Code Generator, as shown below:

   

2. In the New Code Generator panel, set the following:
   • Class Name. Specifies the class name of the stub that the wizard will generate. Type "DemoCodeGenerator" in this field.
   • Package. Specifies the package where the stub class will be generated. Select "org.netbeans.modules.demo" from the drop-down.
   • MimeType. Specifies the MIME type to which the code generator integration will be applied. Type "x-java" in this field.
   • Generate CodeGeneratorContextProvider. Adds additional objects to the code generator's lookup. Leave this checkbox unselected.

   You should now see the following:

   

3. Click Finish.

   The Projects window should now look as follows:

   

In the layer.xml file, you should see the following:

<filesystem>
    <folder name="Editors">
        <folder name="text">
            <folder name="x-java">
                <folder name="CodeGenerators">
                    <file name="org-netbeans-modules-demo-DemoCodeGenerator$Factory.instance"/>
                </folder>
            </folder>
        </folder>
    </folder>
</filesystem>

The generated class should look like this:

public class DemoCodeGenerator implements CodeGenerator {

    JTextComponent textComp;

    /**
     * 
     * @param context containing JTextComponent and possibly other items 
     * registered by {@link CodeGeneratorContextProvider}
     */
    private DemoCodeGenerator(Lookup context) { 
    // Good practice is not to save Lookup outside ctor
        textComp = context.lookup(JTextComponent.class);
    }

    public static class Factory implements CodeGenerator.Factory {

        public List create(Lookup context) {
            return Collections.singletonList(new DemoCodeGenerator(context));
        }
    }

    /**
     * The name which will be inserted inside Insert Code dialog
     */
    public String getDisplayName() {
        return "Sample Generator";
    }

    /**
     * This will be invoked when user chooses this Generator from Insert Code
     * dialog
     */
    public void invoke() {
    }
    
}

Coding the Code Generator Integration

Next, we will implement the API. The API's classes are as follows:

Class	Description
JavaSource	To be done...
CancellableTask	To be done...
WorkingCopy	To be done...
CompilationUnitTree	To be done...
TreeMaker	To be done...
ClassTree	To be done...
ModifiersTree	To be done...
VariableTree	To be done...
TypeElement	To be done...
ExpressionTree	To be done...
MethodTree	To be done...

Below, we set dependencies on the required modules and then implement them in our own module.

Installing and Trying Out the Functionality

Let's now install the module and then use the code generator feature integration. The IDE uses an Ant build script to build and install your module. The build script is created for you when you create the project.

Creating a Shareable Module Binary

Now that the module is complete, you can let others use it. To do so, you need to create a binary "NBM" (NetBeans module) file and distribute it.

Next Steps

For more information about creating and developing NetBeans modules, see the following resources:

• NetBeans Platform Homepage
• NetBeans API List (Current Development Version)
• Other Related Tutorials

---