JBuilder OpenTools basics

Every time JBuilder starts it dynamically discovers the available OpenTools and gives each one a chance to perform its own initialization at the appropriate time. There are no limits to what an OpenTool can do - it could register a new menu item, a new file type, a new viewer, or search the web for email and display its own user interface. OpenTools are written in Java and can do just about anything, though typically they will take advantage of methods exposed as a part of JBuilder's OpenTools API to add features to the IDE.

You'll need to follow these steps to create your first OpenTool:

  1. Create a new project.
  2. Add the OpenTools SDK library to your project.
  3. Create a new Java class.
  4. Import referenced classes.
  5. Define an initOpenTool() method.
  6. Compile the OpenTool class.
  7. Create an OpenTools manifest file.
  8. Test your new OpenTool.
  9. Create an OpenTools JAR.
  10. Add an OpenTools JAR to JBuilder.

Create a new project

Select the File|New Project menu item and specify the location of your new project. For the purposes of this tutorial we will assume that c:/HelloOpenTool/HelloOpenTool.jpr is the location of the project file. Click the Finish button to create the project.

You can actually define any number of OpenTools in a single project.

Add the OpenTools SDK library to your project

Select Project|Project Properties, click on the Required Libraries tab, and press the Add button. Select the OpenTools SDK library, and press OK to add it to your project. Click OK again to save your changes.

This library contains all of the classes that comprise the OpenTools API, so any meaningful OpenTool will need to use at least some of these definitions to extend the IDE.

Create a new Java class

Select File|New Class and replace the default package with example and the class name with HelloOpenTool. Click OK to create the new class definition and add it to your project.

A single OpenTool can make as many, or as few, changes to the IDE as desired. Whether you create a single OpenTool class or many is up to you, but these tutorials will focus on adding selected functionality with individual OpenTools.

Import referenced classes

During normal development you'd add the appropriate imports when you find a need for classes defined outside your package, but it just happens that we know what classes we will need ahead of time for this tutorial. To compile the source code we'll create later you will need to add the following set of import statements to your source code:
import com.borland.primetime.*;
import com.borland.jbuilder.*;
import com.borland.primetime.ide.*;

import javax.swing.*;
import java.awt.event.*;

The Swing and AWT classes are self-explanatory, but the other packages are probably unfamiliar. All packages under com.borland.primetime define a general-purpose framework for writing an IDE in Java, regardless of the target language. Packages under com.borland.jbuilder are specific to JBuilder, our IDE for Java development. These two hierarchies contain many subpackages that will be introduced in later tutorials.

The name PrimeTime was our original code name for the pure Java IDE project, and it lives on as a package name in the OpenTools SDK.

Define an initOpenTool() method

Add the following method definition in the source for your HelloOpenTool class:
public static void initOpenTool(byte major,
       byte minor) {

    // Check OpenTools version number
    if (major != PrimeTime.CURRENT_MAJOR_VERSION)
        return;

    // Add a new menu item to the Help menu
    JBuilderMenu.GROUP_Help.add(new BrowserAction(
        "Say Hello") {
         public void actionPerformed(Browser browser) {
             JOptionPane.showConfirmDialog(null,
                  "Hello, World!");
         }
     });
}

The first statement ensures that your OpenTool is being used with a compatible version of the OpenTools API before performing any initialization. The second statement adds a new menu item to the JBuilder help menu.

If you aren't familiar with inner classes in general, and anonymous classes in specific, this code may look unusual to you. The code creates an instance of a subclass of AbstractAction and overrides an abstract method to define the behavior of the new action. This newly created action is then added to JBuilder's help menu group.

A later tutorial will showcase JBuilder's menus and toolbars in more depth, but a quick look at the JBuilderMenu and JBuilderToolBar classes in the com.borland.jbuilder package will give you a starting point for experimentation.

Compile the OpenTool class

Select Project|Make Project to compile your project and ensure that there are no syntax errors in your code. You may also want to save your work at this point.

Create an OpenTools manifest file

For JBuilder to find your OpenTool, you must provide a description that includes the class name. Select Project|Add to Project|Add File from the menu and specify the filename c:/HelloOpenTool/classes.opentools for your newly created file. (Note that if you created your project elsewhere you will want to adjust for the path you chose. Also note that the name "classes.opentools" assumes that your project's outpath is named "classes" and must be adjusted if you use a different outpath name.) Press OK on the resulting dialog to indicate that you want to create a new file.

Note: You've just taken advantage of a feature that allows you to create any file, including projects or Java source code, without using the Wizards in JBuilder. This can be extremely useful once you get used to it.

Double-click the newly created file in the project pane and add the following line to it:

OpenTools-UI: example.HelloOpenTool

Manfiest files must include a newline character at the end of every line, so be sure to press enter when you are done! This file will serve as the manifest file for a JAR created in the next step. You can place as many fully-qualified OpenTools classes on a single line as you like, using spaces to separate the class names.

Test your new OpenTool

Save everything you've been working on before proceeding. This step can be somewhat awkward as it involves editing the script used to launch JBuilder. It's great for development purposes, but not necessary for deployment of a finished OpenTool.

Exit JBuilder and edit the launch script in JBuilder's bin directory. This will be the JBuilder.config file on Windows, or a shell script on Linux or Solaris. Change the CLASSPATH definition to add c:/HelloOpenTool/classes. (Note that if you created your project elsewhere you will want to adjust for the path you chose.)

Now launch JBuilder again, and look for the Help|Say Hello menu item. If it doesn't appear, check to make sure you've followed these steps carefully. Your OpenTools classes must be in the directory added to the classpath, and the manifest file created in step 7 must be in a file whose name is the same as the directory on the classpath with an additional ".opentools" suffix.

Once you've verified that everything works as expected, remove your changes to JBuilder's CLASSPATH definition.

Create an OpenTools JAR file

There are tools in the Professional version of JBuilder that automate the creation of a JAR containing your classes, but for this tutorial we'll use the command-line tools provided with the JDK.

Open a shell window or DOS prompt, make sure the JDK's bin directory is in your path, and make c:/HelloOpenTool your current directory. (Note that if you created your project elsewhere you will want to adjust for the path you chose.) Now type the following command and press enter:

jar -cfm HelloOpenTool.jar classes.opentools 
    -C classes example

Voila. You've created an OpenTools JAR that contains everything needed to extend JBuilder with the thrilling "Say Hello" menu item. Now to install it the professional way...

Add an OpenTools JAR to JBuilder

JBuilder makes it easy to add OpenTools extensions. Just copy the HelloOpenTool.jar file you created in the last step into JBuilder's lib/ext directory, and you're done! The next time you start JBuilder it will automatically discover your OpenTool when it starts.

Just the beginning

You should begin to glimpse some of the flexibility afforded by the OpenTools mechanism. As you dig deeper into the OpenTools API, you'll see how you can