JBoss.orgCommunity Documentation

Chapter 4. Eclipse Plugins

4.1. Introduction
4.1.1. Download base project
4.2. Creating a Hibernate Mapping File
4.3. Creating a Hibernate Configuration File
4.4. Hibernate Console Configuration
4.4.1. Creating a Hibernate Console Configuration
4.4.2. Modifying a Hibernate Console Configuration
4.4.3. Closing Hibernate Console Configuration
4.5. Reverse Engineering and Code Generation
4.5.1. Code Generation Launcher
4.5.2. Exporters
4.6. Hibernate Mapping and Configuration File Editor
4.6.1. Java property/class completion
4.6.2. Table/Column completion
4.6.3. Configuration property completion
4.7. Structured Hibernate Mapping and Configuration File Editor
4.8. JBoss Tools Properties Editor
4.9. Reveng.xml Editor
4.10. Hibernate Console Perspective
4.10.1. Viewing the entity structure
4.10.2. Prototyping Queries
4.10.3. Properties View
4.11. Hibernate:add JPA annotations refactoring
4.12. Enable debug logging in the plugins
4.12.1. Relevant Resources Links
4.13. Hibernate support for Dali plugins in Eclipse WTP
4.13.1. Creating JPA project with Hibernate support
4.13.2. Generating DDL and Entities
4.13.3. Hibernate Annotations Support
4.13.4. Relevant Resources Links

This chapter will introduce you to the set of wizards and editors provided by Hibernate Tools™ within Eclipse, which are designed to simplify working with Hibernate™.

Hibernate Eclipse Tools includes wizards for creating Hibernate mapping files, configuration files (.cfg.xml), reveng.xml files as well as wizards for adjusting Console Configuration and Code Generation. Special structured and XML editors and editors for executing HQL and Criteria queries are also provided in Hibernate Console. Refer to Section 1.1, “Key Features” to find all the benefits that are provided by these tools within Eclipse.


Please note that these tools do not try to hide any of Hibernates™ functionality; rather the tools make working with Hibernate™ easier. You are still encouraged to read the Hibernate Documentation in order to be able to fully utilize Hibernate Tools™ and especially Hibernate™ itself.

Hibernate mapping files are used to specify how your objects relate to database tables.

To create basic mappings for properties and associations, i. e. generate .hbm.xml files, Hibernate Tools provide a basic wizard which you can display by selecting FileNewHibernate XML mapping file.

At first you will be asked to select a package or multiple individual classes to map. It is also possible to create an empty file: do not select any packages or classes and an empty .hbm file will be created in the specified location.

Using the depth control option you can define the dependency depth used when choosing classes.

The next wizard page lists the mappings to be generated. You can see the Customers, Orders, Productlines and Products classes added under depth control driving.

This wizard page display a preview of the generated .hbm files.

Clicking the Finish button creates the files.

To be able to perform reverse engineering, prototype queries, and of course to simply use Hibernate Core a hibernate.properties or hibernate.cfg.xml file is needed. Hibernate Tools provides a wizard for generating the hibernate.cfg.xml file if you do not already have one.

Start the wizard by clicking FileNewOther (Ctrl+N), then select HibernateHibernate Configuration File (cfg.xml) and click the Next button.


The contents in the comboboxes for the JDBC driver class and JDBC URL change automatically, depending on the Dialect and actual driver you have chosen.

Enter your configuration information in this dialog. Details about the configuration options can be found in Hibernate Reference Documentation.

Click the Finish button to create the configuration file, and after optionally creating a Console configuration, the hibernate.cfg.xml file will be automatically opened in an editor. The last option, Create Console Configuration, is enabled by default and when enabled, it will automatically use the hibernate.cfg.xml file for the basis of a Console configuration.

A Console configuration describes how the Hibernate plugin should configure Hibernate and what configuration files and classpaths are needed to load the POJO's, JDBC drivers etc. It is required to make use of query prototyping, reverse engineering and code generation. You can have multiple named console configurations. Normally you would just need one per project, but it is definitely possible to create more if required.

You can create a console configuration by running the Console Configuration Wizard, shown in the following screenshot. The same wizard will also be used if you are coming from the hibernate.cfg.xml wizard and had enabled the Create Console Configuration option.

The dialog consists of five tabs:

The following table describes the available settings on the Main tab. The wizard can automatically detect the default values for most of the settings if you started the wizard with the relevant Java project or resource selected.


The two latter settings are usually not required if you specify a project that has a /hibernate.cfg.xml or /META-INF/persistence.xml file in its classpath.

  • The Options tab the optional settings

The next table describes the Hibernate Console Configuration options available on the Options tab.

  • Classpath for classpath

The following table specifies the parameters of the Classpath tab of the wizard.

  • Mappings for additional mappings

Parameters of the Mappings tab of the Hibernate Console Configuration wizard are explained below:

  • and the last tab Common

The Common tab allows you to define the general aspects of the launch configuration including storage location, console encoding and some others.

Clicking the Finish button creates the configuration and shows it in the Hibernate Configurations view.

When you created a Hibernate Console Configuration you can modify it in two ways:

Hibernate provides "click-and-generate" reverse engineering and code generation facilities. This allows you to generate a range of artifacts based on database or an existing Hibernate configuration, be that mapping files or annotated classes. Some of these are POJO Java source files, Hibernate .hbm.xml files, hibernate.cfg.xml generation and schema documentation.

To start working with this process, start the Hibernate Code Generation tool which is available from the toolbar via the Hibernate icon or via the RunHibernate Code Generation menu item.

When you click on the Open Hibernate Code Generation Dialog... option the standard Eclipse launcher dialog will appear. In this dialog you can create, edit and delete named Hibernate code generation "launchers".

The first time you create a code generation launcher you should give it a meaningful name, otherwise the default prefix New_Generation will be used.


The "At least one exporter option must be selected" warning indicates that for this launcher to work you need to select an exporter on the Exporter tab. When an exporter has been selected the warning will disappear.

The dialog also has the standard Refresh and Common tabs that can be used to configure which directories should be automatically refreshed and various general settings for launchers, such as saving them in a project for sharing the launcher within a team.

On the Main tab you see the following fields:

Table 4.6. Code generation "Main" tab fields



Console Configuration

The name of the console configuration that should be used when generating code

Output directory

The default location where all output will be written to. It's possible to enter absolute directory path, for example - d:/temp. Be aware that existing files will be overwritten, so be sure to specify the correct directory.

Reverse engineer from JDBC Connection

If enabled, the tools will reverse engineer the database defined in the connection information in the selected Hibernate Console Configuration, and generate code based on the database schema. If not enabled, the code generation will be based on the existing mappings specified in the Hibernate Console configuration.


The package name here is used as the default package name for any entities found when reverse engineering


Path to a reveng.xml file. A reveng.xml file allows you to control certain aspects of the reverse engineering process such as how JDBC types are mapped to Hibernate types, and which tables are included and excluded from the process (which is especially important). Clicking the Setup button allows you to select an existing reveng.xml file, or create a new one. See more details about the reveng.xml file in Chapter 6, Controlling reverse engineering.

reveng. strategy

If the reveng.xml file does not provide enough customization you can provide your own implementation of a ReverseEngineeringStrategy. The class needs to be in the classpath of the Console Configuration, otherwise you will get class not found exceptions. See Section 6.3, “Custom strategy” for details and an example of a custom strategy.

Generate basic typed composite ids

When a table that has a multi-column primary key a <composite-id> mapping will always be created. If this option is enabled and there are matching foreign-keys, each key column is still considered a 'basic' scalar (string, long, etc.) instead of a reference to an entity. If you disable this option a <key-many-to-one> instead. Note: a <many-to-one> property is still created, but is simply marked as non-updatable and non-insertable.

Detect optimistic lock columns

Automatically detect optimistic lock columns. Controllable via reveng. strategy; the current default is to use columns named VERSION or TIMESTAMP.

Detect many-to-many tables

Automatically detect many-to-many tables. Controllable via reveng. strategy.

Detect one-to-one associations

Reverse engineering detects one-to-one associations via primary key and both the hbm.xml file and annotation generation generates the proper code for it.

The detection is enabled by default (except for Seam 1.2 and Seam 2.0) reverse engineering. For Hibernate Tools generation there is a checkbox to disable this feature if it is not required.

Use custom templates

If enabled, the Template directory will be searched first when looking up the templates, allowing you to redefine how the individual templates process the hibernate mapping model.

Template directory

A path to a directory with custom templates

The Exporters tab is used to specify the type of code that should be generated. Each selection represents an Exporter that is responsible for generating the code, hence the name.

The following table provides a short description of the various exporters. Remember you can add and remove any Exporters depending on your needs.

Each Exporter listens to certain properties which can be setup in the Properties section where you can add and remove predefined or customer properties for each of the exporters. The following table lists the time of writing predefined properties:

To add a property to the chosen Exporter click the Add button in the Properties section. In the resulting dialog you should select the property from the proposed list and the value for it.


If the property is a directory, it is possible to browse directories in the Value field.

The Hibernate Mapping File editor provides XML editing functionality for the hbm.xml and cfg.xml files. The editor is based on the Eclipse WTP tools and extends its functionality to provide Hibernate specific code completion.

The structured editor represents a file in a tree form. It also provides a way to modify the structure of the file and its elements with the help of tables provided on the right-hand area.

To open any mapping file in the editor, select Open WithHibernate 3.0 XML Editor from the context menu of the file. The editor is shown in the following image:

For the configuration file you should select Open WithHibernate Configuration 3.0 XML Editor.

The editor is designed to edit .properties files. It contains two tabs: the Properties (UI) tab and the Source tab for manual editing.

For hibernate.properties files the JBoss Tools Properties Editor provides content assist for both Hibernate properties and values. You can make use of the content assist while editing the file in the Source view and in the Properties view of the editor.

To add the property in the Properties view, click the Add button.

In the Name field press Ctrl+Space to invoke the content assist. It will suggest 'hibernate.' which is the prefix for all hibernate properties. After selecting 'hibernate.' and invoking the content assist again, other prefixes and properties are displayed as the proposals, with a description for each one.

When invoking the content assist in the Value field, it also provides a list of proposals.

In the Source view of the editor, content assist can also be invoked both for properties names and values:

A reveng.xml file is used to customize and control how reverse engineering is performed by the tools. The plugins provide an editor to assist in editing this file.

The editor is intended to allow easy definition of type mappings, table include and excludes, and specific override settings for columns, e.g. define an explicit name for a column when the default naming rules are not applicable.

The editor is activated as soon as a .reveng.xml file is opened. To create an initial reveng.xml file the Reverse Engineering File Wizard can be started by pressing Ctrl+N and then selecting HibernateHibernate Reverse Engineering File (reveng.xml).

Or you can get it via the Code Generation Launcher by checking the appropriate section in the Main tab of the Getting Hibernate Code Generation Wizard (see Figure 4.15, “Getting Hibernate Code Generation Launcher”).

The following screenshot shows the Overview page where the appropriate console configuration is selected (it is auto-detected if Hibernate 3 support is enabled for the project).

The Table Filter page allows you to specify which tables to include and exclude. Clicking the Refresh button shows the tables from the database that have not yet been excluded.

The Type Mappings page is used to specify type mappings from JBDC types to any Hibernate type (including user types) if the default rules are not applicable. To see the database tables press the Refresh button underneath. For more information on type mappings please see the Section 6.2.2, “Type mappings (<type-mapping>)” section.

The Table and Columns page allows you to explicitly set which details (e.g. which hibernatetype and propertyname) should be used in the reverse engineered model. For more details on how to configure the tables while reverse engineering read Section 6.2.4, “Specific table configuration (<table>)”.

The Hibernate Console Perspective combines a set of views which allow you to see the structure of your mapped entities and classes, edit HQL queries, execute the queries, and view the results. To use this perspective you need to create a Hibernate Console Configuration (see Section 4.4, “Hibernate Console Configuration” for more information).

To view your new configuration and entity or class structure, switch to the Hibernate Configurations View. Expanding the tree allows you to browse the class or entity structure, as well as view the relationships.

The Console Configuration does not dynamically adjust to changes performed in mappings and Java code. To reload the configuration select the configuration and click the Reload button in the view toolbar or in the context menu.

It is possible to open source and mapping files for objects showed in the Hibernate Configurations View. Just bring up the context menu for an object and select Open Source File to see the appropriate Java class or Open Mapping File to open a .hbm.xml file.

In order to visualize how entities are related, as well as view their structures, a Mapping Diagram is provided. It is available by right clicking on the entity you want view a mapping diagram for and then selecting Mapping Diagram.

To make Mapping Diagram usage easier you can use the Rules, Grid, Snap to Geometry checkboxes in the View menu.

If you select the Rulers checkbox, the view print page scale will be added to the page. The numbers on the scale displays its size in inches. If you click on the scale a Ruler Guide will appear on the diagram. You can connect any diagram item to it. To connect the items you should move their tops to the Ruler Guide. And while moving the ruler guide, the items will be moved together with it as a whole.

If you select the Grid checkbox, a grid will appear on the diagram.

The Snap to Geometry checkbox allows you to align the diagram items with the grid.

For better navigating through the diagram use the Outline view, which is available in the structural and graphical modes.

To switch between the view modes, use the buttons in the top-right corner of the Outline view.

The options in the context menu of the mapping diagram are listed in the next table.

When you open the context menu for an item in the diagram, it differs quite significantly from the one described before.

The next table describes the additional options found in the mapping items context menu:


All these context menu options are also available in the Outline view.

The following table lists the available keyboard shortcuts.

It is possible to save the diagram in the Eclipse workspace. Select FileSave As, and the wizard will ask you to specify the location within you project where you wish to save the file, and provide the name for the diagram. The default name is the item's names concatenated with the ampersand symbols. The file is saved with the .hibernate extension.


If you restart Eclipse with the mapping diagram opened, the mapping diagram will be restored with the message like on the figure below. To view the diagram content, you should refresh the view.

There are some useful commands in the toolbar.

They are described in the table below.

Queries can be prototyped by entering them into the HQL or Criteria Editor. To execute a query click the green run button in the editor toolbar, or press Ctrl+Enter.

To open the query editors right-click your projects Console Configuration and select HQL Editor (or Hibernate Criteria Editor).


If the context menu items are disabled then you need at first to create a Session Factory. That is done by expanding the Session Factory node.

When they are opened, the editors they should automatically detect the chosen Console Configuration.

To generate a predefined query for any entity (or any entity child node) listed in the Session Factory you should double-click it. This will open the HQL Editor with the associated query.

Choosing HQL Editor in the context menu for any entity (or any entity child node) will also open the HQL Editor with the associated query. If you select Hibernate Criteria Editor in the context menu, it will open Hibernate Criteria Editor with the associated criteria.

It is also possible to copy a portion of code from a .java file into the HQL or Criteria editor. To do this make use of the Quick Fix option (Ctrl+1).

You can also update the original Java code with changes made in the HQL or Criteria editor. For that you should save your HQL/Criteria query and submit the replacement code when prompted by the confirmation dialog.

In addition, you can pin the HQL editor and Criteria editor as a tab in the Hibernate Query Result view. For that you need click on the Stick result to one tab button (). In this state query executions results will be shown in one tab (no more will be opened).

You are able to rename the Hibernate Query Result tab. Click the tab, and type a new name in the Property ViewTab name field.

Using this wizard you can add the following Hibernate annotations to a class: @Column, @Entity, @ManyToOne, @OneToMany, @OneToOne, @ManyToMany, @MappedSuperclass, @Id, @GeneratedValue, @Version


This section doesn't cover the definitions of the Hibernate annotations. For more information read the Hibernate Annotations Documentation.

To open this wizard you should right click the class you want to add the annotations to and select SourceGenerate Hibernate/JPA annotations from the context menu. You will see the Hibernate: add JPA annotations dialog.

The top section of this dialog lists all the classes that will be passed through refactoring. Next to the class you have selected, this list also displays its superclasses and the classes that the objects present in the current class as properties. If you want to add new classes or packages to the list, you should click the Back button. This will display the Add classes and packages page.

Here you can add additional classes or entire packages, and you can limit the dependencies depth by selecting the depth control option (you can find more information on this option in Section 4.2, “Creating a Hibernate Mapping File”). When you are finished click the Next button and you will be returned to The following classes will be changed page.

By default the tags are added to the fields of selected classes. You can change this option to Getters in the Preferred location of Annotations drop down list, which results in the annotations being added to the getter methods. If you choose Auto select from class preference then the annotations are added according to the position of the majority of the existing annotations.

If it is necessary to map your String properties to the columns that length differ from the default value (255), change the Default string length field and the @Column(length = your length) annotation will be created for every String property.

You can add optimistic locking capabilities to an entity bean by selecting the Enable optimistic locking checkbox. This operation will add the version property to all the selected classes. The property will be also annotated with @Version, and a getter and setter will be created. If the property is already exists, it won't be created, but the getters and setters will be generated. If there is already @MappedSuperclass annotation with @Version in the base class of the current class, @Version is not inserted into the current class.

After defining all the required settings click the Next button.

The view represents two windows: one with the source code and and the second with refactored one. With the help of the , , , buttons you can quickly navigate between the differences in the code. If you don't agree with some changes you can't undo them but you can remove the class from the list of classes that need refactoring.

To apply the changes click the Finish button.

It is possible to configure the Eclipse plugin to route all logging performed by the plugins and Hibernate code it self to the Error Log view in Eclipse.

The Error Log view is very useful tool to use when solving any problems which appear in the Hibernate Tools plugins. You can use it if there are troubles setting up a Hibernate Console Configuration.

This is done by editing the hibernate-log4j.properties file in the org.hibernate.eclipse/ directory or JAR. This file includes a default configuration that only logs WARN and above to a set of custom appenders (PluginFileAppender and PluginLogAppender). You can change these settings to be as verbose or silent as you please. See the Hibernate Documentation for more information on logging categories and Log4j documentation.

Starting from version 3.0.0 Alpha1, JBoss Tools™ Hibernate plugins support Eclipse Dali integration, which makes it possible to use a Hibernate as a complete JPA development platform.