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.
![[Note]](img/note.gif) | 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]](img/warning.gif) | Warning |
|---|---|
The Kodo JBuilder OpenTool only works in JBuilder 7 and up. It will not work in releases of JBuilder prior to version 7. | |
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. | |
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.
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.
| 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.
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.