Chapter 4. Eclipse Plugins

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™.

4.1. Introduction

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.

Note:

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.

4.1.1. Download base project

You can download the example projects that are used in this chapter.

A JPA base project is available on the documentation resources page together with a base Java project.

Also you need start the database.

Note:

The steps for running the database are documented in the Getting Started Guide.

4.2. Creating a Hibernate Mapping File

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 File → New → Hibernate 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.

Figure 4.1. Hibernate XML Mapping File Wizard

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.

Figure 4.2. Mappings to be generated

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

Figure 4.3. Preview Generated Mapping Files

Clicking the Finish button creates the files.

4.3. Creating a Hibernate Configuration File

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.

This video illustrates the creation of a Hibernate Configuration File for an existing project

Figure 4.4. Hibernate Configuration File creation video

Start the wizard by clicking File → New → Other (Ctrl+N), then select Hibernate → Hibernate Configuration File (cfg.xml) and click the Next button.

Figure 4.5. Hibernate Configuration File Wizard

Note:

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.

4.4. Hibernate 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.

4.4.1. Creating a Hibernate Console Configuration

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.

Note:

The wizard will look at the current selection in the IDE and try to auto-detect the appropriate settings, which you then can approve or modify to suit your needs.

The dialog consists of five tabs:

Main, which displays the basic and required settings

Figure 4.6. Creating Hibernate Console Configuration

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.

Table 4.1. Hibernate Console Configuration Parameters

Parameter	Description	Default value
Name	The unique name of the console configuration	Name of the selected project
Type	Choose between "Core", "Annotations" and "JPA". Note that the two latter requires running Eclipse IDE with a JDK 5 (or newer) runtime, otherwise you will get class loading and version errors. You will also need to select the version of Hibernate your application server has (3.5, 3.6 or 4.0). Select a version from the drop-down box labelled Hibernate Version.	Core and Hibernate Version: 3.5
Project	The name of a Java project whose classpath should be used in the console configuration	Name of the selected project
Database connection	DTP provided connection that you can use instead of what is defined in the `cfg.xml` and JPA `persistence.xml` files. It is possible to use an already configured Hibernate or JPA connection, or specify a new one here.	[Hibernate Configured connection]
Property file	Path to a `hibernate.properties` file	First `hibernate.properties` file found in the selected project
Configuration file	Path to a `hibernate.cfg.xml` file	First `hibernate.cfg.xml` file found in the selected project
Persistence unit	Name of the persistence unit to use	No default value (let Hibernate Entity Manager find the persistence unit or it can be defined manually using the Browse button)

Tip:

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

Figure 4.7. Options Tab of the Console Configuration Wizard

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

Table 4.2. Hibernate Console Configuration Options

Parameter	Description	Auto detected value
Database dialect	Define a database dialect. It is possible either to enter your own value or choose from list.	No default value
Naming strategy	Fully qualified class name of a custom `NamingStrategy`. Only required if you use a special naming strategy.	No default value
Entity resolver	Fully qualified class name of a custom `EntityResolver`. Only required if you have special XML entity includes in your mapping files.	No default value

Classpath for classpath

Figure 4.8. Specifying Classpath in Hibernate Console Configuration

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

Table 4.3. Hibernate Console Configuration Classpath

Parameter	Description	Auto detected value
Classpath	The classpath for loading POJO and JDBC drivers; only needed if the default classpath of the Project does not contain the required classes. Do not add Hibernate core libraries or dependencies, they are already included. If you get ClassNotFound errors then check this list for possible missing or redundant directories or JAR files.	Empty
Include default classpath from project	When enabled the project classpath will be appended to the classpath specified above	Enabled

Mappings for additional mappings

Figure 4.9. Specifying additional Mappings in Hibernate Console Configuration

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

Table 4.4. Hibernate Console Configuration Mappings

Parameter	Description	Auto detected value
Mapping files	List of additional mapping files that should be loaded. Note: A `hibernate.cfg.xml` or `persistence.xml` can also contain mappings. Thus if these are duplications here, you will get "Duplicate mapping" errors when using the console configuration.	empty

and the last tab Common

Figure 4.10. Common Tab of the Console Configuration Wizard

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.

Figure 4.11. Console Overview

4.4.2. Modifying a Hibernate Console Configuration

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

Right-click on the configuration in the Hibernate Configurations View and select Edit Configuration, or just double-click on the Console Configuration item.
Figure 4.12. Opening Edit Configuration Wizard

You will then see the Edit Configuration Wizard, which is similar to Create Console Configuration, described in Section 4.4.1, “Creating a Hibernate Console Configuration”.

Use the Properties view to modify the Console Configuration properties.

Figure 4.13. Properties View

The following table describes the available settings in the Properties view. Most properties can be changed by left clicking on them, but some can not.

Table 4.5. Properties

Property	Description	Is Changeable
Additional mapping files	Count of additional mapping files that should be loaded.	False
Configuration file	Path to a `hibernate.cfg.xml` file	False
Connection	DTP provided connection that you can use instead of what is in the `cfg.xml` and JPA `persistence.xml` files. It is possible to use either an already configured Hibernate or JPA connection, or specify a new one here.	True
Name	The unique name of the console configuration	True
Project	The name of a Java project which classpath should be used in the console configuration	True
Properties file	Path to a `hibernate.properties` file	False
Type	Choose between "CORE", "ANNOTATIONS" and "JPA" according to the method of relational mapping you want to use. Note, the two latter requires running Eclipse IDE with a JDK 5 runtime, otherwise you will get class loading and/or version errors.	True

4.4.3. Closing Hibernate Console Configuration

To close Hibernate Console Configuration you need to right-click your configuration and choose the Close Configuration option.

Figure 4.14. Close Hibernate Console Configuration

When closing the configuration the connection with database will be closed, JAR libs will be unlock (for Windows) and other resources will set as free.

4.5. Reverse Engineering and Code Generation

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 Run → Hibernate Code Generation menu item.

4.5.1. Code Generation Launcher

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".

Figure 4.15. Getting Hibernate Code Generation Launcher

Figure 4.16. Hibernate Code Generation Launcher

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.

Tip:

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

Field	Description
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.
Package	The package name here is used as the default package name for any entities found when reverse engineering
reveng.xml	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

4.5.2. Exporters

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.

Figure 4.17. Selecting Exporters

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

Table 4.7. Code generation "Exporter" tab fields

Field	Description
Domain code	Generates POJO's for all the persistent classes and components found in the given Hibernate configuration.
DAO code	Generates a set of DAO's for each entity found.
Hibernate XML Mappings	Generate mapping (`hbm.xml`) files for each entity.
Hibernate XML Configuration	Generate a `hibernate.cfg.xml` file. Used to keep the `hibernate.cfg.xml` file updated with any newly discovered mapping files.
Schema Documentation (.html)	Generates a set of HTML pages that documents the database schema and some of the mappings.
Generic Exporter (hbmtemplate)	Fully customizable exporter that can be used to perform custom generation.
Schema Export (.ddl)	Generates the appropriate SQL DDL and allows you to store the result in a file or export it directly to the database.

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:

Table 4.8. Exporter Properties

Name	Description
jdk5	Generate Java 5 syntax
ejb3	Generate EJB 3 annotations
for_each	Specifies for which type of model elements the exporter should create a file and run through the templates. Possible values are: entity, component, configuration
template_path	Custom template directory for this specific exporter. You can use Eclipse variables.
template_name	Name for template relative to the template path
outputdir	Custom output directory for this specific exporter. You can use Eclipse variables.
file_pattern	Pattern to use for the generated files, relatively for the output dir. Example: `{package-name}/{class-name}.java`.
dot.executable	Executable to run GraphViz (only relevant, but optional for Schema documentation)
drop	Output will contain drop statements for the tables, indices and constraints
delimiter	If specified the statements will be dumped to this file
create	Output will contain create statements for the tables, indices and constraints
scriptToConsole	The script will be output to Console
exportToDatabase	Executes the generated statements against the database
outputFileName	If specified the statements will be dumped to this file
haltOnError	Halts the build process if an error occurs
format	Applies basic formatting to the statements
schemaUpdate	Updates a schema

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.

Figure 4.18. Adding the Property for Schema Export (.ddl)

Tip:

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

Figure 4.19. Specifying the Property Value

4.6. Hibernate Mapping and Configuration File Editor

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.

Figure 4.20. XML Editing Functionality

4.6.1. Java property/class completion

Package, class, and field completion is enabled for relevant XML attributes. The auto-completion tool detects its context and limits the completion for a tag (such as <property>) and only shows the properties and fields available in the enclosing <class>, <subclass> etc. It is also possible to navigate from the hbm.xml files to the relevant classes and fields in your Java code.

Figure 4.21. Navigation Functionality

This is done via the standard hyperlink navigation functionality in Eclipse. By default this is done by pressing F3 while the cursor is on a class or field, or by pressing Ctrl and the mouse button.

For Java completion and navigation to work the file needs to reside inside an Eclipse Java project, otherwise the feature is not available.

Note:

Java completion does not require a Hibernate console configuration to be used.

4.6.2. Table/Column completion

Table and column completion is also available for all table and column attributes.

Figure 4.22. Table and Column Completion

Important:

Table and Column completion requires a properly configured Hibernate console configuration, and this configuration should be the default for the project where the hbm.xml resides.

You can check which console configuration is selected in the Properties of a project under the Hibernate Settings page. When a proper configuration is selected it will be used to fetch the table and column names in the background.

Note:

Currently it is not recommended to use this feature on large databases since it does not fetch the information iteratively. This will be improved in future versions.

4.6.3. Configuration property completion

Code completion for the value of <property> name attributes are available when editing the cfg.xml file.

Figure 4.23. Property Completion

4.7. Structured Hibernate Mapping and Configuration File Editor

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 With → Hibernate 3.0 XML Editor from the context menu of the file. The editor is shown in the following image:

Figure 4.24. Structured hbm.xml Editor

For the configuration file you should select Open With → Hibernate Configuration 3.0 XML Editor.

Figure 4.25. Structured cfg.xml Editor

4.8. JBoss Tools Properties 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.

Figure 4.26. Adding the Property

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.

Figure 4.27. Content Assist for Properties Names

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

Figure 4.28. Content Assist for Properties Values

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

Figure 4.29. Content Assist in the Source view

Figure 4.30. Content Assist in the Source view

4.9. Reveng.xml Editor

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.

Note:

Not all the features of the .reveng.xml file are exposed or fully implemented in the editor, but the main functionality is there. To understand the full flexibility of the reveng.xml file, please see Section 6.2, “hibernate.reveng.xml file”

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 Hibernate → Hibernate Reverse Engineering File (reveng.xml).

Figure 4.31. ChooseReverse Engineering File Wizard

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).

Figure 4.32. Overview Page

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.

Figure 4.33. Table Filters Page

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.

Figure 4.34. Type Mappings Page

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>)”.

Figure 4.35. Table and Columns Page

4.10. Hibernate Console Perspective

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).

4.10.1. Viewing the entity structure

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.

Figure 4.36. Hibernate Console Perspective

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.

Figure 4.37. Opening Source for Objects

4.10.1.1. Mapping Diagram

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.

Figure 4.38. Mapping Diagram

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

Figure 4.39. 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.

Figure 4.40. Moving the Ruler guide

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

Figure 4.41. Grid on Mapping 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.

Figure 4.42. Navigating in the Structural Mode

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

Figure 4.43. Navigating in the Graphical Mode

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

Table 4.9. Context Menu Options of the Mapping Diagram

Icon	Command	Description
	Show\|Hide connections	Allows you to select what types of connections should be shown on the diagram: Property Mappings Class Mappings Associations Foreign key constraints
	Select All	Selects all the diagram elements
	Auto layout	Used to dispose all the items in the diagram in a standard manner
	Export as Image	Allows the diagram to be exported as a `PNG`,`JPEG` or `BMP` file

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

Figure 4.44. Context Menu in Mapping Item

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

Table 4.10. Extra Options in the Context Menu of Mapping Item

Icon	Command	Description
	Open Source File	Opens the source file for a chosen object or element. The selected element will be highlighted in the open file.
	Open Mapping File	Opens a mapping file for a chosen object or element. The selected element will be highlighted in the open file.
	Show\|Hide shape(s)	Used to hide or show an item on the mapping diagram
	Expand\|Collapse shape(s)	Used to expand and collapse fields displayed by the item

Tip:

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

The following table lists the available keyboard shortcuts.

Table 4.11. Hibernate Mapping Diagram Shortcut Keys

Command	Binding
Scroll the diagram content	Ctrl+Shift+arrows
Collapse or Expand selected item(s)	Enter
Show or Hide selected item(s)	+
Sort items in alphabetical order or return to the initial state	Space
Navigate between the items	Arrows

It is possible to save the diagram in the Eclipse workspace. Select File → Save 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.

Figure 4.45. The Diagram saved in the Workspace

Note:

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.

Figure 4.46. The Diagram after Restarting the Eclipse

Figure 4.47. The Diagram after Refreshing

There are some useful commands in the toolbar.

Figure 4.48. The Diagram View Toolbar

They are described in the table below.

Table 4.12. Command in Diagram View Toolbar

Icon	Command	Description
	Refresh Visual Mapping	It will update the Mapping Diagram the if Console Configuration was changed.
	Zoom Box	Used to define scale of the diagram. It is also used for printing Mapping Diagrams. If you want to print the whole diagram to one page, you need select the Page option in the Zoom Box drop down list.
	Auto layout	Used to arrange all diagram items in a standard manner.
	Show\|Hide connections	Used to show or hide a connection on the diagram. You can also choose what type of connections must be present on the diagram (Property Mappings, Class Mappings, Associations or Foreign key constraints).
	Expand\|Collapse	Used for expanding or collapsing fields of the item.
	Show\|Hide shape(s)	Used to hide or show an item on the mapping diagram.

4.10.2. Prototyping Queries

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.

4.10.2.1. HQL Editor and Hibernate Criteria Editor

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

Figure 4.49. Opening HQL Editor

Tip:

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.

Figure 4.50. Generating Simple Queries

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).

Figure 4.51. Quick Fix Option Demonstration

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.

Figure 4.52. Updating Java Code

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 View → Tab name field.

Figure 4.53. Tab Renaming

4.10.2.2. Error Handling

Errors raised during the creation of the Session Factory, or when executing the queries (e.g. if your configuration or query is incorrect), will be shown in a message dialog or inclined in the view that detected the error. You may get more information about the error in the Error Log view on the right pane.

Results of a query will be shown in the Hibernate Query Result view and details of possible errors (syntax errors, database errors, etc.) can be seen in the Error Log view.

Note:

HQL queries are executed by default using the list() function, and without any row limit could return a large result set. You may run out of memory. To avoid this you can enter a value in the Max results field to reduce the number of elements that are returned.

4.10.2.3. Dynamic Query Translator

If the Hibernate Dynamic Query Translator view is visible, it will show the generated SQL for a HQL query while you write in the HQL Editor .

Figure 4.54. Hibernate Dynamic Query Translator View

The translation is performed each time you stop typing in the editor. If there are errors in the HQL code the parse exception will be shown embedded in the view.

4.10.3. Properties View

As you can see in the figure below, when clicking on class or entity the Properties view shows the number of query results as well as the execution time.

Figure 4.55. Properties View

It also displays the structure of any persistent object selected in the Hibernate Query Results View. Editing is not yet supported.

Figure 4.56. Properties View for Selected Object

You can also use Properties view when clicking on the configuration itself in Hibernate Configuration view (see Section 4.4.2, “Modifying a Hibernate Console Configuration ”).

4.11. Hibernate:add JPA annotations refactoring

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

@Column is added to all String properties.
@Entity is always declared before any class where it has not yet been defined.
@ManyToOne, @OneToMany, @OneToOne, @ManyToMany - these annotations are declared according to the classes hierarchy.
@MappedSuperclass is added to abstract superclasses.
@Id, @GeneratedValue are only added automatically to the properties under the name "Id", where they have not yet been defined.
@Version is declared in case you select optimistic locking (see Section 4.11, “Hibernate:add JPA annotations refactoring ”).

Note:

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 Source → Generate Hibernate/JPA annotations from the context menu. You will see the Hibernate: add JPA annotations dialog.

Figure 4.57. Starting 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.

Figure 4.58. 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.

Figure 4.59. Hibernate:add JPA annotations view

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.

Figure 4.60. List of classes that need refactoring

To apply the changes click the Finish button.

4.12. Enable debug logging in the plugins

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.

4.12.1. Relevant Resources Links

More information on how to to configure logging via a Log4j property file can be found in the Log4j documentation.

4.13. Hibernate support for Dali plugins in Eclipse WTP

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.

4.13.1. Creating JPA project with Hibernate support

When starting a new JPA project by selecting New → Other → JPA → JPA Project (or simply New → JPA Project in the JPA Perspective), the first wizard page is shown in the image below.

Figure 4.61. Starting JPA Project

You can select a target runtime and change the project configuration, or you can leave everything as it is.

On the JPA Facet page you should choose Hibernate as a target platform. Also select the proper database connection, if it is defined, or add a new one by clicking the Add connection link.

Clicking the Finish button will generate the project.

Figure 4.62. Targeting at Hibernate Platform

Note:

If you choose Hibernate as a platform while creating a JPA/Dali project, a Hibernate Console Configuration for the project is created automatically when the wizard is finished. It allows all the Hibernate Tools features to be used without any additional setup.