15.4. Borland JBuilder
Prev | Chapter 15. Third Party Integration | Next

## 15.4. Borland JBuilder

Kodo JDO provides integration into JBuilder 7 and higher in the form of a JBuilder OpenTool. The integration features allow the JBuilder user to configure the Kodo runtime, edit .jdo metadata files (both as raw XML and via a specialized editor), configure mappings, and automatically run the JDO Enhancer.

### 15.4.1. Installing Kodo Into JBuilder

| Note
We highly recommend fully uninstalling previous versions of the plugin.

To install Kodo support in JBuilder, just copy all the `.jar` files from the `lib/` directory of your Kodo installation to the `lib/ext/` directory of JBuilder, and copy the `lib/KodoJDO.library` to JBuilder's `lib/` directory. For example, if Kodo is installed in `C:\development\kodo\` and JBuilder is installed in `C:\JBuilder7\`, then you would copy all the `.jar` files from `C:\development\kodo\lib\` to `C:\JBuilder7\lib\ext\`, and then copy the `C:\development\kodo\lib\KodoJDO.library` file to `C:\JBuilder7\lib\`.

To validate the installation, you should start (or restart) JBuilder. You should see the Kodo logo in the build toolbar, which is used to configure the Kodo installation.

| Note
If you use the Windows Installer program to install Kodo, and you elected to perform the "Install Kodo JBuilder extensions", then you do not need to perform the manually file copying or any other additional steps.

| Warning
The Kodo JBuilder OpenTool only works in JBuilder 7 and up. It will not work in releases of JBuilder prior to version 7.

### 15.4.2. Kodo Configuration from JBuilder

The Kodo configuration panel provides various options for configuring runtime usage of Kodo. Configuration options are saved in JBuilder's `user.properties`. The configuration panel provides an option to write out the configuration to a file named `kodo.properties`. This file, if written to, will be stored at the root of your project source directory.

| Note
To users of previous versions of this plugin, the default kodo.properties is no longer actively maintained by the configuration panel. Instead, you must actively propagate changes to your file by selecting the `Write to kodo.properties?` option.

### 15.4.3. Creating and building JDO projects in JBuilder

When right-clicking on one or more `.java` in JBuilder, you will see an option to "Create Kodo JDO Metadata". This will create a `.jdo` metadata file for all of the classes. If only one class is selected, a corresponding single class `.jdo` file is created. If multiple classes of a single package are selected, a package level .jdo file is created. Otherwise, a `system.jdo` is created. See JDO MetaData Placement for more details on metadata placement.

The JDO enhancer will be automatically run on any `.jdo` file in the project. Furthermore, `.jdo` and `.mapping` files will be copied over to the output directory, so that it will be available at runtime. This behavior can be triggered manually by compiling `.jdo` and `.mapping` files.

### 15.4.4. Editing JDO Metadata from JBuilder

The `.jdo` metadata files can either be edited in JBuilder's native XML editor, or they can be modified using a dialog by selecting "Properties" from the context menu of the `.jdo` file in the JBuilder browser. The dialog contains entries for all of the standard JDO attributes, as well as Kodo-specific vendor extensions. See the section on JDO Metadata for more details about the various properties and their meanings.

### 15.4.5. Editing Mapping Info from JBuilder

| Note
Editing mapping info requires understanding of Kodo's MappingTool and mapping process. Please read that section before manually editing mapping information.

To generate a `.mapping` source file, select a `.jdo` file and right click to raise the context menu. Select `Create Mapping`. You can now select a schema action that will happen in parallel with the mapping generation. For further details, see Mapping Tool. The plugin will then generate a `.mapping` file representing the default Kodo mapping for the metadata as a child of the `.jdo`

You can now edit this as an XML file, or edit using the plugin's GUI editor by selecting `Properties` from the `.mapping` context menu.

There are a couple more `Mapping Tool` actions available at the `.jdo` context level. `Drop Mapping Info` and `Build Schema from Mapping` will first request what schema action to take before triggering the corresponding `Mapping Tool` action.

### 15.4.6. JBuilder Project Sample

An example JBuilder Swing project is available in the Kodo JDO installation, in the samples/swing/petshop directory. To run the sample, do the following:

- Configure the Kodo plugin as described above and set the Kodo license key and connection properties appropriately. If you are using HSQL (or another file-based database), you should use an absolute path in the URL to ensure that all schema operations work on the same database.

- Double-click the `PetShop.jpx` file in the `samples/swing/petshop` directory of your Kodo JDO installation. This will load the PetShop sample in JBuilder.

- Expand the `<Project Source>` item in the top left pane of the JBuilder display. This will expose the classes in the sample and the `Animal.jdo` metadata file.

- Right-click on the `Animal.jdo` file in the top left pane, and select `Create Mapping` option from the context menu. The plugin will prompt for a schema action. Select `Refresh` to create the tables needed for the tutorial. You will see `Animal.mapping` generated as a child of the `Animal.jdo` node. In addition, the file will be opened for editing in XML.

- Build the project by selecting `Make Project "PetShop.jpx"` from the `Project` menu. This will also run the JDO enhancer on `Animal` as well as deploying the metadata files to the output directory.

- Edit petshop.properties to match your plugin configuration, including license key and database connectivity information. Set the database URL to the same value as was set in the general JBuilder Kodo properties. If you are using HSQL (or another file-based database), you should use an absolute path in the URL to ensure that all schema operations work on the same database.

- Right-click on the `PetShop.java` file in the top left pane, and select `Run using defaults` from the menu. This will run the Pet Shop example.

The Pet Shop example allows you to create and delete pets in a database. The pets have a string type -- dog, cat, giraffe, etc. -- and a price.

The Pet Shop example code demonstrates how to put together a simple Swing example, and also how to use a Kodo-specific feature to extend the `PersistenceManager` class to enable Swing updates to happen at the optimal time.

Prev | Up | Next
15.3. XDoclet | Home | 15.5. Sun ONE Studio / NetBeans IDE