Contributing to Hibernate using Eclipse

Importing the project

The first thing you will want to do is to import the Hibernate project into an Eclipse project.  Eclipse has support for importing Gradle projects (hibernate-orm) as well as Maven projects (other Hibernate projects). We highly suggest using the Maven importing for the Maven projects.

 

For Gradle, it depends on which version of Eclipse you use; reports say that 4.3 (Kepler) has much better support for Gradle imports, but 4.3 is non-stable at time of this writing. For 4.2 and earlier, we recommend not installing or using the Gradle Integration for Eclipse plugin.

 

For importing hibernate-orm using Gradle's eclipse plugin, from the hibernate-orm project root directory run `./gradlew clean eclipse --refresh-dependencies`.

 

No matter how you import it, hibernate-orm has dependencies that Eclipse believe to be cyclic so you will need to disable that checking by going to `Window -> Preferences -> Java -> Compiler -> Building` and setting Circular dependencies to Warning, rather than Error.

 

Code formatting

From the Eclipse menu Window, Preferences, select Java - Code Style - Formatter. Import the java-formatting.xml attached to this page to apply the style the Hibernate team uses consistently across the codebase.

Please avoid re-formatting large parts of code, especially when providing a patch we would love to have the diffs highlight the changes which matter.

 

If you feel the need to fix formatting on an existing source file, make sure your commit contains exclusively formatting changes (avoid any functional change) and make sure the commit comment mentions this.

 

Code templates

In the same Preferences menu, select Java - Code Style - Code Templates and import the code-templates.xml attached to this page. This will automatically import proper license headers into new files. Feel free to add your nick or full name as author of new files, and optionally provide an email. The copyright header is a requirement.

You can also use the attached auto-cleanup.xml to be imported into Java -> Code Style -> Clean Up.

 

Unit test

Hibernate is developed applying test-driven development. If you plan to contribute any new code, providing a test is important for many reasons, not least to help maintainers understand your code. Including appropriate tests with your patches / pull request will greatly speed-up inclusion of it.

 

We have continuous integration tests covering many many different databases; you're expected to have verified your tests where you can and at least on H2 (the default in memory database included in the testsuite) but you don't have to try it out on all possibly supported databases, we'll let the continuous integration know, and get back to you and help as we can if some compatibility problem is highlighted.

 

Make sure your tests close all resources - even in case of failures - and cleanup after themselves (e.g. delete temporary directories if you needed any).

 

See also Writing tests.

 

Running tests in Eclipse

Some tests involving integration with JGroups and/or Infinispan will start a network connection to themselves (via localhost) to simulate a cluster of computers. Many JVMs default to IPv6 for this, so either you have that configured correctly or you might want to start tests with these JVM properties set:

 

-Djava.net.preferIPv4Stack=true -Djgroups.bind_addr=127.0.0.1

 

Debugging

When debugging, Eclipse might invoke toString() methods on the objects you select for inspection. This operation could trigger initialization of proxies and so affect the debugged object state. Using Eclipse you can customize the way it shows objects: look into "Detail formatters" and the Idea wiki page for some ideas. You could avoid including lazy-loaded details in your toString() implementations: it also helps to avoid unintended loading during logging, a frequent mistake having terrible effects on performance.