Ibator Feature Debug Reference

This page contains reference information about how to build and debug the Ibator feature from source.

Feature Structure

The Ibator feature is structured as five different Eclipse projects - a feature project and four plugin projects. The feature project groups the four plugins together for easy installation. The Ibator feature project is org.apache.ibatis.ibator. This project references the four plugin projects. The plugin projects are structured as follows:

Plug-in Project Description
org.apache.ibatis.ibator.core This plugin holds the Java source for the core Ibator library. The project for this plugin contains linked folders to the Ibator source tree.
org.apache.ibatis.ibator.eclipse.core This plugin holds Java support classes for the other plugins. This plugin does not contribute to the Eclipse user interface. This plugin includes classes for Java file merging, and Eclipse implementations of the Ibator callback interfaces.
org.apache.ibatis.ibator.eclipse.doc This plug-in holds the documentation for Ibator. There is a build file in this plug-in (buildDoc.xml) that will build the documentation and package it for inclusion into the Eclipse help system.
org.apache.ibatis.ibator.eclipse.ui This plug-in holds the Java code for the Eclipse user interface for Ibator. If you are experiencing trouble with the plugin specific features (like the integrated Ant task), then the code for those features will be found in this plugin.

Other Projects

There are three other Eclipse projects that complete the feature:

Project Description
IbatorUpdateSite This project holds the artifacts for the Ibator update site. The artifacts in this project are used a new version of the feature is published at Apache. Most users will not need to access the artifacts in this project.
org.apache.ibatis.ibator This project is the Eclipse feature project for Ibator.
org.apache.ibatis.ibator.build This project holds the build script and properties for the Ibator build.

Eclipse Workspace Setup

The following instructions show how to setup an Eclipse workspace for building the Ibator feature and plug-ins from the latest source in the Subversion repository. We assume that you are somewhat familiar with Subversion and the Eclipse plug-in development environment (PDE). These instructions also assume you are using Eclipse version 3.5.1 (Galileo).

  1. Checkout the latest source code from Subversion
    1. Create a local directory where the source will be stored (for example /Apache/Ibator)
    2. Check out the source tree from the Subversion repository at http://svn.apache.org/repos/asf/ibatis/java/ibator/trunk/ Note: this will also checkout the source for the Ibator core JAR which is required.
  2. Create a new Eclipse workspace directory (for example /EclipseWorkspaces/Ibator)
  3. Start Eclipse and point it to the new workspace directory
  4. Important: make sure that a version 5.0 or higher JDK is configured as the default JRE in Eclipse (Window>Preferences>Java>Installed JREs). A JDK is required - a JRE alone will cause problems.
  5. Important: create a path variable named IBATOR_SOURCE that points to the .../core/ibator-core/src folder in the source tree from SVN (Window>Preferences>General>Workspace>Linked Resources)
  6. Important: the core Ibator project requires log4j to compile. Some eclipse distributions do not include log4j. You can get it by adding the WTP XSL Developer Tools from eclipse (Help>Install New Software, etc.)
  7. Import the plug-in projects into the workspace
    1. Start the Eclipse project import wizard (File>Import>General>Existing Projects into Workspace)
    2. Set the root directory to the "eclipse" sub-directory of the directory where you did the SVN checkout (for example, /Apache/Ibator/eclipse)
    3. Select all projects except the IbatorUpdateSite project, do not copy the projects into your workspace. Note that the Ibator Update Site is not needed unless you intending to release a new version of the the project at Apache. The filled out wizard looks like this:

      Eclipse Project Import Wizard

    4. Press "Finish", wait for the workspace to build.

Debugging

At this point the projects should be successfully compiled in Eclipse. If you want to debug something in the plug-in, you will need to start another instance of Eclipse in debug mode. The following instructions explain how to do this.

  1. Set a breakpoint in the code you would like to debug.
  2. Double click on the "plugin.xml" file in the "org.apache.ibatis.ibator.eclipse.ui" project. This should open the plug-in manifest editor. If some other editor opens, then close the editor, right click on "plugin.xml" and select the "Open With>Plug-in Manifest Editor" option.
  3. Select the "Overview" editor tab
  4. Take the option to "Launch an Eclipse Application in Debug mode". This will start a new instance of Eclipse in debug mode with the Ibator plug-ins installed.

Once you have the other instance of Eclipse started you should create a new Java project in the new workspace, create and fill out an Ibator configuration file, and then run Ibator. Ibator should eventually hit your breakpoint, and then you step through the code.

The following classes will likely be of the most interest in debugging:

Class Description
org.apache.ibatis.ibator.eclipse.ui.actions.RunIbatorThread This class is a thread that runs Ibator on the selected configuration file. You can set a breakpoint in the run method of this class to follow the Ibator code generation process from the beginning.
org.apache.ibatis.ibator.eclipse.core.merge.JavaFileMerger This class implements the Java file merge function. You can set a breakpoint in the getMergedSource method to follow the merging process.

Building the Documentation

The documentation for Ibator is integrated into the Eclipse help system. The documentation is partially generated (Javadocs), partially copied in from the core Ibator source tree, and partially maintained in the plugin itself. This full documentation set is not in Subversion because it is partially generated. If you would like to rebuild the documentation, simply execute the buildDoc.xml file in the org.apache.ibatis.ibator.eclipse.doc project (an Ant build file).

Building the Feature for Distribution

If you want to build an updated version of the feature and distribute it locally, then follow these steps:

  1. Open the file build.xml in the org.apache.ibatis.ibator.build project. There are four properties at the beginning of the file that may need to change for your local environment.

    Property Description
    baseLocation This should be set to the location on disk of an eclipse distribution that includes the plug in development environment.
    pdeBuildPluginVersion This is the version of the org.eclipse.pde.build plugin. The value in the file is the correct version for Eclipse 3.5.1
    equinoxLauncherPluginVersion This is the version of the org.eclipse.equinox.launcher plugin. The value in the file is the correct version for Eclipse 3.5.1
    buildDirectory This is the target directory for the build.

  2. Once you have verified or updated the properties, you can close the build.xml file.
  3. Execute the build.xml file (right click, Run As>Ant Build)

Once the build executes successfully, the new feature will be available on your local drive at \Temp\ibator.build\I.TestBuild\org.apache.ibatis.ibator-TestBuild.zip unless you change the buildDirectory property above. The easiest way to install this new version of the feature is to unzip the feature archive into the dropins directory of an Eclipse installation.