The following guide will help you to get started with Hibernate Search in case you want to contribute or just build from source yourself.

Requirements

• Java JDK 8
• Maven ( >= 3.3.3 )

Source access

To get a read only version of the source you can use clone the GIT repository available on GitHub: http://github.com/hibernate/hibernate-search

The branch of current development is - as by convention - "master". There might be other branches as maintenance branches of older releases, but we expect most work to happen in master unless discussed on the mailing list.

> git clone GitHub - hibernate/hibernate-search: Hibernate Search: full-text search for domain model

The suggested approach is to use the GitHub fork capability via forking and pull requests: create an account on Github, then from the webpage http://github.com/hibernate/hibernate-search hit the "fork" button and start hacking on your personal copy. There is also a Git tips and tricks blog on in.relation.to: Hibernate Moves To Git - Git Tips And Tricks.

Compiling the source

Prior to setting the project up in any IDE it is recommended to trigger a command line build to verify that everything builds. You can build out of the box using the following command

> mvn clean install -s settings-example.xml

This will download all dependencies, compile and test each module.

Once you are confident that everything works you can add the required maven settings (repository information) to your ~/.m2/settings.xml file and skip the -s option. You find more information about the JBoss maven configuration at Maven Getting Started - Users.

It is possible that the latest committed version of Hibernate Search sometimes depends on non released versions of Hibernate ORM. In this case you will have to checkout and build the latest version of Hibernate ORM in order to get the latest snapshots into your local maven repository, or you can ask another developer to deploy an updated snapshot to Maven repositories. We usually deploy snapshot versions regularly, so that shouldn't be a problem.

Build targets

Running tests

To run the tests just type

> mvn test

Bydefault this will run all the tests against an in memory database (H2). All tests should pass against the in memory database. The project POM also defines a whole range of profiles to run the tests against different databases. However, the settings in the POM are specific to the Hudson setup within the QA labs of JBoss. Instead of editing pom.xml and maybe accidentally committing the wrong settings, here is an example to override your settings for mysql, just add the following profile to your settings.xml:

  mysql-local
  
    org.hibernate.dialect.MySQL5InnoDBDialect
    com.mysql.jdbc.Driver
    jdbc:mysql://localhost/hibernate
    hibernate
    hibernate
    
  

Then run:

mvn test -P mysql,mysql-local

The idea is to still rely on the profile specified in the POM (especially the dependencies to the JDBC driver) and just override the values which differ in your local environment.

Testing in the IDE

During development it is quite nice to be able to just right click on org.hibernate.search.test and select "run all tests" from the context menu. Ideally this should run all tests successfully. However, some tests have special requirements, or they will fail.

Running JGroups tests from the IDE

You can see which properties need to be set by looking how the surefire plugin is configured in hibernate-search/pom.xml .

At the moment the the surefire plugin is configured with these properties:

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

If you want to run the tests which are affected by these settings (JGroups tests) you need to set the same settings in your IDE configuration for these tests. You can do it on a per test basis, or you can change the default for all tests (at least you can do this in Idea and Eclipse) to set the properties accordingly. These options are not strictly needed on all platforms, as some normally default to these, but better be safe.

Running Byteman tests from the IDE

We're using BMUnit to attach Byteman's agent on the running JVM; this will only work when using a JDK (not a JRE) to run the tests: it needs the tools.jar which is not included in the standard JRE classpaths (it might be on some environments, like OSX). To be on the safe side, always run the testsuite using the JDK.

Building the documentation

The documentation is maintained in the source tree itself, versioned with the source code.

It's written using Docbook and can be found in the maven module hibernate-search-documentation of your checkout. You can build the documentation by executing mvn install from within this module. In order to build the documentation you need the publican toolchain installed on your system (see also documentation note on BuildingHibernateFromSource35). In case you are not going to patch the documentation you won't need these tools, as the documentation is not built by default.

To build and preview the documentation you can run, from the

> cd hibernate-search-documentation
> mvn package
> firefox ./target/docbook/publish/en-US/html_single/index.html

When writing the documentation your should follow the JBoss Documentation Guide. This guide gives valuable recommodations about styling as well as general writing tips.

IDE Setup

Eclipse

Being a Maven project, you will need to import it using m2e. This plugin is usually included in Eclipse, or can be found in the marketplace.

The logger implementation classes are generated via an annotation processor; this is automatically configured correctly if you install this m2e extension: https://github.com/jbosstools/m2e-apt (add this Eclipse update site: http://download.jboss.org/jbosstools/updates/m2e-extensions/m2e-apt ). After installing the plugin, open Preferences > Maven > Annotation Processor and set it to "Automatically Configure JDT".

Alternatively you can setup the annotation processor manually: run the compile step from commandline and add the generated logging implementation to your classpath; it's usually in target/generated-sources/apt , but you'll have to repeat this step for each module, and recompile from commandline when you make changes to the Logger interfaces.

Code formatting and templates can be found here.

Idea

The latest versions of Idea come with builtin support for Maven projects. Just import your project as Maven project and let Idea figure it out.

Formatting settings and usage tips for Idea can be found here.

Providing a patch

Pull Requests

Patches including a test and fix for an issue are always welcome, preferably as GitHub pull request. We are following the Fork + Pull Model as described here. In oder to be able to integrate your patch we need you to accept the JBoss Contributor License Agreement!

Expected patch format

• All files should have Unix-style line endings, and use UTF-8 encoding. All mayor IDEs have options to set this up properly even if you're using Windows.
• You're welcome to add your name as @author when making significant changes (not mandatory).
• All new files added to the project should have the copyright header; take one from an existing file as a template and update the year.
• Please don't change formatting, whitespaces, or anything else on code lines which are not related to your patch.
• We're quite picky and peculiar on code style: please use tabs and spaces as you see in the rest of the code, or see the IDE section below to import styles and template settings for IDEA or Eclipse.
• Javadoc is welcome but not mandatory if the method is trivial. Take your time to pick method names and variable names. Ideally the code should be self-explanatory, otherwise  comments explaining the code are very welcome.

Writing tests

With any non-trivial patch we would always expect a funtional or unit test:

• New features: requires at least one test to verify it's working as expected (and will work in the future)
• Bugfixes: to reproduce bugs, help with debugging, prevent regressions in the future

You are also welcome to just contribute patches to introduce failing unit tests for some bug you have found but you' re not sure how to fix: that's extremely helpfull for other team members to understand a problem being reported.

To write a new functional test you should extend SearchTestCase. This will allow you to focus on writing the actual test functionality while reusing all the boilerplate code to build the Hibernate Configuration and SessionFactory. It also allows you to make use of several annotations which allow you to temporarily skip a test, or limit it's execution to spefici databases only. See also Hibernate Writing Tests.

Resources