Kodo JDO can integrate with both Sun ONE Studio and NetBeans IDE as an OpenIDE module. The module requires versions 4.0 and 3.4 or higher of Sun ONE Studio and NetBeans IDE respectively. The module provides support for editing metadata files in the IDE, easy access to the MappingTool and enhancer, links into the build process to support enhancement, and wizards to help in the creation of JDO specific files.
This document will refer to your IDE's home directory, for example, C:\Program Files\s1studio or /usr/local/NetBeansIDE_3.3. If you are installing on a multi-user installation and want to install it for only a particular user, this home IDE directory can also be the user's directory chosen during the initial execution of the IDE, for example C:\ide-userdir. On Linux and Unix, this folder usually automatically set to ~/ffjuser40 and ~/.netbeans/3.4 for SunONE Studio and NetBeans IDE respectively.
Previous installations of the Kodo plugin should be disabled and uninstalled before installing this version of the plugin. Ensure that old Kodo jars, including dependent jars, have been removed.
Copy all of Kodo's jars excluding kodo-jdo.jar, kodo-workbench.jar, kodo-jdo-runtime.jar into the lib/ext directory of your IDE's home directory (note the version numbers may be different in your Kodo installation). Do not place the Kodo jars in this directory as we will install this later in the process. Unix and Linux users: do not symlink these jars as your permissions may be incorrect.
![[Note]](img/note.gif) | Note |
|---|---|
On some earlier versions of SunONE Studio (notably, version 4), you should remove Kodo's version of xercesImpl.jar as it may cause some conflicts. | |
In addition, one should copy to this directory the jar for the JDBC driver used to connect to your database. Copy kodo-jdo.jar into the modules directory of your home IDE directory.
Upon starting up the IDE, open the IDE configuration under the menu at Tools -> Options. If you have installed Kodo correctly, you should see Kodo listed as a module under Options -> JDO -> System -> Modules. If its not listed, right click on Modules -> Add -> Module... and browse to kodo-jdo.jar to manually install Kodo as a module.
To begin using the JDO API, open the Filesystems browser. Right click on filesystems, and select Mount -> Archive and browse to and select jdo-1.0.2.jar which you installed. To explictly use Kodo in your project, mount Kodo's libraries in a similar fashion.
The plugin configuration is integrated into the IDE. In the Tools -> Options dialog box, Kodo's options are listed under Options -> JDO -> Kodo Settings. Sub-settings control your Kodo development configuration, such as driver information, as well as providing defaults for the properties wizard listed below. To use the plugin, you must enter your license key and enter the connection information for your database.
Using the Kodo Settings options pane, you can configure logging verbosity of the plugin. Valid values for this setting are (from least to most verbose):
FATAL
ERROR
WARN
DEBUG
INFO
TRACE
The Kodo Module provides a pair of templates to help you get started and use Kodo and JDO. These templates are activated by right clicking on a folder in your project or filesystem, and selecting New -> Kodo sub-menu.
The Kodo Properties wizard will assist in the run-time configuration of Kodo, using your current plugin configuration settings for the default values. The wizard will create new .properties files to use with your projects. Options are separated into logical groupings. You can optionally test this new configuration by pressing the test button on the lower right corner.
The JDO Metadata wizard provides a set of dialogs to walk the developer through metadata generation. Simply select the type of metadata file to generate, add the classes you want described by the metadata, and then configure each class' metadata. The resulting jdo file(s) can now be used in your project.
Kodo provides integrated support for JDO files as OpenIDE DataObjects. You can treat them like any other file. Right clicking on a JDO file marked by the Kodo "K" will present a variety of options. To edit the file in XML view, select Edit. To open and edit the file in a JDO Metadata editor, select Open.
In addition, the module integrates support for enhancing and running Mapping Tool over classes defined in your metadata file. To accompish either task, right click on any JDO Metadata file node, or Java class node in the explorer. You can select one or more of either node as long as no invalid nodes are selected. Select Tools -> Kodo to see the available actions.
Mapping Tool actions will prompt for a schema action to do in parallel with your mapping action. In addition, one can optionally redirect the schema changes to a .schema file.
Kodo integrates mapping information as Mapping DataObjects. This will allow you to edit, view, and add source control onto the mapping information used by Kodo at runtime. Select a JDO node and select Refresh mappings to create new JDO node. To edit the file in XML view, select Edit. To open and edit the file in a complete GUI editor, select Open.
By installing the Kodo Module, Kodo will integrate into the project build process. By adding your JDO files to the project, Kodo will make sure that your dependent classes are compiled before enhancement occurs.
Kodo also integrates via Ant. See the Ant integration section for more details.
To build and run the sample, first follow the plugin installation instructions above. Mount the samples/swing/petshop directory for your Kodo JDO installation onto the Filesystem explorer pane ( right click on FileSystems, select Add Existing, and browse and select the directory). In a similar manner, mount Kodo's libraries into the project. To run the sample, do the following:
Configure the Kodo module as described above and ensure that you have 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.
Build the sample by selecting the petshop directory node (a root node), and selecting from the menu Build -> Build All This will also run the JDO enhancer on Animal.
Expand the petshop directory node in the explorer. 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 Tools -> Kodo -> Refresh mappings from the menu. Select the Refresh schema action and select OK. By selecting Refresh schema action action will create the tables necessary for the sample.
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 for the module configuration. 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 node in the explorer and select Execute 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.