Hibernate Search: full-text search for domain model
Clone or download
Permalink
Failed to load latest commit information.
.empty Consider all sources as tests during Sonar analysis in integration te… Sep 12, 2018
backend HSEARCH-840 Create directory provider in LuceneBackendFactory instead… Sep 11, 2018
build-config HSEARCH-3179 Set version to '6.0.0-SNAPSHOT' Sep 5, 2018
documentation HSEARCH-3179 Set version to '6.0.0-SNAPSHOT' Sep 5, 2018
engine HSEARCH-840 Add API types for index managers Sep 11, 2018
integrationtest HSEARCH-2847 Test that bridges using markers to retrieve and access p… Sep 13, 2018
jenkins HSEARCH-3179 Merge Search 5 Jenkins configuration into Search 6 Sep 5, 2018
jqassistant HSEARCH-3139 Restore the severity of SPI leaks to "major" in JQAssistant Sep 5, 2018
legacy HSEARCH-3246 Skip coverage reporting in legacy tests Sep 10, 2018
mapper HSEARCH-840 Rename IndexManager to MappedIndexManager Sep 11, 2018
reports HSEARCH-3246 Skip coverage reporting in legacy tests Sep 10, 2018
travis HSEARCH-3179 Merge Search 5 Travis configuration into Search 6 Sep 5, 2018
util/internal HSEARCH-2847 Allow to specify multiple JIRA keys with @TestForIssue Sep 13, 2018
.gitattributes HSEARCH-1325 Control line endings with an appropriate .gitattributes … May 13, 2013
.gitignore Add *.autosave to .gitignore Apr 19, 2018
.travis.yml HSEARCH-3179 Disable the ES2 job in the Travis build Sep 5, 2018
CONTRIBUTING.md HSEARCH-2844 Remove requirement for CLA Aug 10, 2017
Jenkinsfile HSEARCH-3332 Add some documentation in the Jenkinsfile about the vari… Sep 14, 2018
README.md HSEARCH-3179 Add a warning about the master branch being work in prog… Sep 6, 2018
changelog.txt [Jenkins release job] changelog.txt updated by release build 5.10.0.F… May 16, 2018
copyright.txt HSEARCH-2612 Add Mincong Huang as an author Oct 25, 2017
dco.txt HSEARCH-2844 Remove requirement for CLA Aug 10, 2017
lgpl.txt HSEARCH-3004 Update address of Free Software Foundation Feb 14, 2018
pom.xml Consider all sources as tests during Sonar analysis in integration te… Sep 12, 2018

README.md

Hibernate Search

Build Status Coverage Status Quality gate Language Grade: Java

Warning: this is Hibernate Search 6

This branch currently contains the code of Hibernate Search version 6, a new major version which is very different from Hibernate Search 5, and is still in its early stages.

If you are looking for the code of the version of Hibernate Search you are currently using, you should try branch 5.10 instead, or any of the older branches.

If you are looking for version 6, then keep in mind that most of the old codebase has been moved to the legacy directory, creating several modules with the same artifact ID.

When importing the Maven modules in Eclipse, you are advised to use the [groupId]:[artifactId] project name template, in order to avoid conflicts. You can distinguish between old and new modules by their group ID: legacy modules use org.hibernate, while newer modules use org.hibernate.search.

Description

Full text search for Java objects

This project provides synchronization between entities managed by Hibernate ORM and full-text indexing services like Apache Lucene and Elasticsearch.

It will automatically apply changes to indexes, which is tedious and error prone coding work, while leaving you full control on the query aspects. The development community constantly researches and refines the index writing techniques to improve performance.

Mapping your objects to the indexes is declarative, using a combination of Hibernate Search specific annotations and the knowledge it can gather from your existing Hibernate/JPA mapping.

Queries can be defined by any combination of:

  • "native" Apache Lucene queries
  • writing "native" Elasticsearch queries in Json format (if using Elasticsearch, which is optional)
  • using our DSL which abstracts the previous two generating optimal backend specific queries

Query results can include projections to be loaded directly from the index, or can materialize fully managed Hibernate entities loaded from the database within the current transactional scope.

Hibernate Search is using Apache Lucene under the cover; this can be used directly (running embedded in the same JVM) or remotely provided by Elasticsearch over its REST API.

Getting started

All necessary information is available on the Hibernate Search website:

For offline use, distribution bundles downloaded from SourceForge also include the reference documentation for the downloaded version in PDF and HTML format.

Building from source

> git clone git@github.com:hibernate/hibernate-search.git
> cd hibernate-search
> mvn clean install

Build options (profiles and properties)

Documentation

The documentation is based on Asciidoctor. By default only the HTML output is enabled; to also generate the PDF output use:

> mvn clean install -Pdocumentation-pdf

+You can then find the freshly built documentation in the following location:

> ./documentation/target/asciidoctor/en-US

Distribution

To build the distribution bundle run:

> mvn clean install -Pdocumentation-pdf,dist

Elasticsearch

The Elasticsearch module tests against one single version of Elasticsearch at a time, launching an Elasticsearch server automatically on port 9200. You may redefine the version to use by specifying the right profile and using the test.elasticsearch.host.version property, while disabling the default profile:

> mvn clean install -P!elasticsearch-5.2,elasticsearch-2.0 -Dtest.elasticsearch.host.version=2.1.0

The following profiles are available:

  • elasticsearch-2.0 for 2.0.x and 2.1.x
  • elasticsearch-2.2 for 2.2.x and later 2.x
  • elasticsearch-5.0 for 5.0.x and 5.1.x
  • elasticsearch-5.2 for 5.2.x and later 5.x (the default)

A list of available versions for test.elasticsearch.host.version can be found on Maven Central.

Alternatively, you can prevent the build from launching an Elasticsearch server automatically and run Elasticsearch-related tests against your own server using the test.elasticsearch.host.provided and test.elasticsearch.host.url properties:

> mvn clean install -Dtest.elasticsearch.host.provided=true -Dtest.elasticsearch.host.url=http://localhost:9200

If you want to run tests against an older Elasticsearch version (2.x for instance), you will still have to select a profile among those listed above, and disable the default profile:

> mvn clean install -P!elasticsearch-5.2,elasticsearch-2.2 -Dtest.elasticsearch.host.provided=true -Dtest.elasticsearch.host.url=http://localhost:9200

You may also use authentication:

> mvn clean install -Dtest.elasticsearch.host.provided=true -Dtest.elasticsearch.host.url=https://localhost:9200 -Dtest.elasticsearch.host.username=ironman -Dtest.elasticsearch.host.password=j@rV1s

Also, the elasticsearch module (and only this one) can execute its integration tests against an Elasticsearch service on AWS. You will need to execute something along the lines of:

> mvn integration-test -pl elasticsearch -Dtest.elasticsearch.host.provided=true -Dtest.elasticsearch.host.url=<The full URL of your Elasticsearch endpoint> -Dtest.elasticsearch.host.aws.access_key=<Your access key> -Dtest.elasticsearch.host.aws.secret_key=<Your secret key> -Dtest.elasticsearch.host.aws.region=<Your AWS region ID>

Contributing

New contributors are always welcome. We collected some helpful hints on how to get started on our website at Contribute to Hibernate Search

Source code structure

The project is split in several Maven modules:

  • backends: Remote backends receiving an indexing job and executing it via different protocols.

  • build-config: Code-related artifacts like checkstyle rules.

  • distribution: Builds the distribution package.

  • documentation: The project documentation.

  • elasticsearch: The core of the Elasticsearch integration.

  • elasticsearch-aws: Specific bits enabling connection to an AWS-hosted Elasticsearch cluster

  • engine: The engine of the project. Most of the beef is here.

  • integrationtest: Integration tests with various technologies like WildFly, Spring and Karaf. Also includes performance tests.

  • jbossmodules: Integration with WildFly using JBoss Modules.

  • jsr352: JSR 352 - Batch Applications for the Java Platform integration.

  • orm: Native integration for Hibernate ORM, and also home of most public API code.

  • reports: Last-built module, producing reports related to test coverage in particular.

  • serialization: Serialization code used by remote backends.

  • sharedtestresources: Internal module providing various test resources to our integration tests.

  • testing: Various helper classes to write tests using Hibernate Search. This module is semi private.

Contact

Latest Documentation:

Bug Reports:

Free Technical Support:

License

This software and its documentation are distributed under the terms of the FSF Lesser GNU Public License (see lgpl.txt).