Installing OpenTools samples

Be sure to read JBuilder OpenTool Loader Concepts, in particular the section on naming and placing the manifest override file.

Sample Project Configuration

Each OpenTools sample project contains two things that make it easy to run the OpenTool: an archive node and the OpenTools manifest.

The Archive Node

The archive node, like the TreeFont node illustrated below, is created by the Archive Builder.

The Archive Builder is a feature of JBuilder Professional and Enterprise. If you're using JBuilder Foundation, the archive node is not recognized:

and if you want to build a JAR, you will have to make it manually.

The OpenTools Manifest

The OpenTools manifest is named classes.opentools, and lists the class (or classes) to register for the sample OpenTool. It is also used when building an OpenTools archive, whether that's done manually or with the Archive Builder. The archive node is already configured to use the manifest file.

The manifest is in the project root directory, the same directory that contains the project's .jpr (or .jpx) file. Each OpenTools sample project has its output path configured to generate classes in the classes subdirectory of the project. This means that after building the project, the project root directory will contain both a classes directory and a classes.opentools file. This fulfills the naming and placement requirements of the manifest override file. (If the output directory was named something else or placed somewhere else, the manifest file name would have to be renamed or moved to match.)

Installation Steps

You can run an OpenTool from .class files on disk, or from within a JAR. The former is generally done during their development, because making JARs is an extra step; but the Archive Builder makes it very easy to build JARs on demand.

To run an OpenTool, its classes must be placed in JBuilder's IDE classpath. Note that JBuilder is already configured to load all the JAR files in JBuilder's /lib/ext directory, so if you copy JARs there, or generate JARs directly in that directory, the OpenTool will be loaded automatically when JBuilder restarts without having to change any configuration files.

Building Classes

The first step is to build the classes. To do this, simply choose Project|Build or Project|Make from the menu.

Once the classes are built, you can add the project output directory to the IDE classpath, or build a JAR.

Archive Node JARs

If you're using JBuilder Professional or Enterprise, the archive node will cause the JAR to be built automatically if the project classes build successfully. The archive node is set to build the JAR in the project root directory. If you're unsure where that is, you can expand the archive node after the build and hover the mouse pointer over the JAR file name. As with any file node in the project view, a tooltip will appear with the full file name and path:

Once you locate the JAR, you can modify JBuilder's configuration so the JAR is in the IDE classpath, or copy the JAR to the /lib/ext directory.

Building JARs manually

If you're using JBuilder Foundation (or want the thrill of building JARs manually), you use the JDK jar utility to build JARs:

  1. Start a shell window or commmand (DOS) prompt.
  2. If the JDK is not in the PATH, add it.
  3. Go to the project root directory, the one that contains the manifest and output directory.
  4. Type the following command:
      jar -cfm pick-a-name.jar classes.opentools -C classes com
    replacing pick-a-name with -- well, you get the idea. This command:
  5. If you get the prompt back with no messages, it worked. To see the content of the JAR, you can use your favorite JAR-aware archive utility, or type the command:
      jar -tf pick-a-name.jar

Once you build the JAR, you can modify JBuilder's configuration so the JAR is in the IDE classpath, or copy the JAR to the /lib/ext directory.

Using the Library Extension Directory

If you have a JAR, the easiest way to use it is to copy it to JBuilder's /lib/ext directory. The OpenTool will be loaded automatically when JBuilder restarts without having to change any configuration files.

If you're using JBuilder Professional or Enterprise, you can configure the archive node to build the JAR directly in the /lib/ext directory, to save yourself the copy step. This is convenient during development, but not necessarily something you want to do for every OpenTool you encounter (which is why the sample projects do not come configured this way). Right-click the archive node and choose Properties from the context menu and change the File location on the first page:

No matter how the JAR gets there, remove it from the /lib/ext directory when you no longer want to use that OpenTool.

Modifying the IDE Classpath

The IDE classpath is specified in the JBuilder.config file, located in JBuilder's /bin directory. The .config file format is documented in the readme.txt file in the same directory.

Before making any changes to JBuilder.config, make a backup copy of the file.

To add a single entry for a JAR file or project's output directory:

  1. Open the JBuilder.config file with a text editor
  2. Locate the line: addjars ../lib/ext
  3. Underneath that line, use the addpath directive; some examples:
      addpath /the/path/to/your.jar
      addpath C:/JBuilder4/samples/OpenToolsAPI/commandline/CommandLine.jar
      addpath /project/output/path
      addpath C:/JBuilder4/samples/OpenToolsAPI/commandline/classes
  4. Close the file

Restarting JBuilder

After building, placing, and modifying the necessary files, restart JBuilder to load the new OpenTool.

It's a good idea to add only one OpenTool at a time. If JBuilder then fails to load or behaves strangely, you know which one caused the problem.