The basic steps required to create, compile, and install a JBuilder Foundation OpenTool are unveiled.  This tutorial assumes that the developer has a solid Java background.

OpenTools Overview

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^TM and can do just about anything, though typically they will take advantage of methods exposed as a part of JBuilder Foundation'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
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

1. 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.  Press the Finish button to create the project.

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

2. Add the OpenTools SDK Library

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.  Press 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.

3. Create a New Java Class

Select File|New Class... and replace the default package with example and the class name with HelloOpenTool .  Press 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.

4. Import Referenced Classes

In the course of 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.

Trivia: 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.

5. 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.

6. 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.

7. Create an OpenTools Manifest File

In order for JBuilder to find your OpenTool, you need to 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 on the newly created file in the project view, 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.

8. 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 a batch 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.

9. Create an OpenTools JAR

There are tools in the forthcoming Professional extension to JBuilder Foundation 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...

10. Add an OpenTools JAR to JBuilder

JBuilder Foundation 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.

This is Just the Beginning

I hope you can begin to glimpse some of the flexibility afforded by the OpenTools mechanism.  As we dig deeper into the OpenTools API you'll see how you can:

• Customize menu items and toolbars
• Add new file types
• Overhaul the editor's keybindings
• Define your own viewers, editors, and structure panes
• Extend the global properties system
• Associate property pages with individual files
• Create new run and debug systems
• Tweak the compilation process
• Enhance the context menus for individual files
• and much, much, more..