diff --git a/hibernate-search/src/main/docbook/en-US/hsearch.ent b/hibernate-search/src/main/docbook/en-US/hsearch.ent
index e7bdc7ead4a..80d31ae5e3f 100644
--- a/hibernate-search/src/main/docbook/en-US/hsearch.ent
+++ b/hibernate-search/src/main/docbook/en-US/hsearch.ent
@@ -23,6 +23,7 @@
-->
+
\ No newline at end of file
diff --git a/hibernate-search/src/main/docbook/en-US/master.xml b/hibernate-search/src/main/docbook/en-US/master.xml
index a3c76665389..812873aa829 100644
--- a/hibernate-search/src/main/docbook/en-US/master.xml
+++ b/hibernate-search/src/main/docbook/en-US/master.xml
@@ -22,7 +22,8 @@
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
-
%BOOK_ENTITIES;
]>
@@ -36,17 +37,15 @@
&version;
+
+
+
+
-
-
-
-
-
-
-
-
-
-
+
+
+
+
@@ -57,7 +56,7 @@
Full text search engines like Apache Lucene are very powerful
technologies to add efficient free text search capabilities to
applications. However, Lucene suffers several mismatches when dealing with
- object domain model. Amongst other things indexes have to be kept up to
+ object domain models. Amongst other things indexes have to be kept up to
date and mismatches between index structure and domain model as well as
query mismatches have to be avoided.
@@ -92,7 +91,7 @@
-
+
diff --git a/hibernate-search/src/main/docbook/en-US/modules/getting-started.xml b/hibernate-search/src/main/docbook/en-US/modules/getting-started.xml
index b400450de63..c5f1c212f70 100644
--- a/hibernate-search/src/main/docbook/en-US/modules/getting-started.xml
+++ b/hibernate-search/src/main/docbook/en-US/modules/getting-started.xml
@@ -34,7 +34,7 @@
through the initial steps required to integrate Hibernate Search into an
existing Hibernate enabled application. In case you are a Hibernate new
timer we recommend you start here.
+ url="http://hibernate.org/quick-start.html">here.
System Requirements
@@ -49,48 +49,48 @@
A JDK or JRE version 5 or greater. You
can download a Java Runtime for Windows/Linux/Solaris here.
+ url="http://www.oracle.com/technetwork/java/javase/downloads/index.html">here.
Hibernate Search
- hibernate-search.jar and all runtime
- dependencies from the dist/lib directory of the
- Hibernate Search distribution.
+ hibernate-search-&version;.jar and all
+ runtime dependencies. You can get the jar artifacts either from
+ the dist/lib directory of the Hibernate
+ Search distribution or you can download them from the
+ JBoss
+ maven repository.
Hibernate Core
This instructions have been tested against Hibernate 3.6.
- You will need hibernate-core.jar and its
- transitive dependencies from the lib directory
- of the distribution. Refer to README.txt in the
- lib directory of the distribution to determine
- the minimum runtime requirements.
+ You will need
+ hibernate-core-&hibernateVersion;.jar and its
+ transitive dependencies (either from the distribution
+ bundle or the maven repository).
- Hibernate Annotations
+ JPA 2
- Even though Hibernate Search can be used without Hibernate
- Annotations the following instructions will use them for basic
+ Even though Hibernate Search can be used without JPA
+ annotations the following instructions will use them for basic
entity configuration (@Entity, @Id,
@OneToMany,...). This part of the configuration could
- also be expressed in xml or code. However, Hibernate Search itself
- has its own set of annotations (@Indexed, @DocumentId,
- @Field,...) for which there exists so far no
- alternative configuration. The tutorial is tested against version
- 3.6 of Hibernate Annotations (part of the Hibernate Core
- distribution).
+ also be expressed in xml or code. Hibernate Search, however,
+ has itself its own set of annotations (@Indexed,
+ @DocumentId, @Field,...) for which there exists so far
+ no alternative configuration.
-
- You can download all dependencies from the Hibernate download
- site.
@@ -98,7 +98,7 @@
Instead of managing all dependencies manually, maven users have the
possibility to use the JBoss
+ url="http://repository.jboss.org/nexus/content/groups/public-jboss/ ">JBoss
maven repository. Add the following to your Maven
settings.xml file (see also Maven
@@ -170,7 +170,7 @@
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-entitymanager</artifactId>
- <version>3.6.0.Final</version>
+ <version>&hibernateVersion;</version>
</dependency>
@@ -226,11 +226,11 @@
DirectoryProvider. In this tutorial we will use a a
directory provider storing the index in the file system. This will give us
the ability to physically inspect the Lucene indexes created by Hibernate
- Search (eg via Luke).
+ Search (eg via Luke).
Once you have a working configuration you can start experimenting with
other directory providers (see ). Next to the directory
- provider you also have to specify the default root directory for all
+ provider you also have to specify the default base directory for all
indexes via hibernate.search.default.indexBase.
Lets assume that your application contains the Hibernate managed
@@ -291,10 +291,9 @@ public class Author {
Book as indexable. By design Hibernate Search needs
to store an untokenized id in the index to ensure index unicity for a
given entity. @DocumentId marks the property to use for
- this purpose and is in most cases the same as the database primary key. In
- fact since the 3.1.0 release of Hibernate Search
- @DocumentId is optional in the case where an
- @Id annotation exists.
+ this purpose and is in most cases the same as the database primary key.
+ The @DocumentId annotation is optional in the case
+ where an @Id annotation exists.
Next you have to mark the fields you want to make searchable. Let's
start with title and subtitle and
@@ -309,16 +308,16 @@ public class Author {
in the index. Whether this data is stored in the index or not has nothing
to do with the ability to search for it. From Lucene's perspective it is
not necessary to keep the data once the index is created. The benefit of
- storing it is the ability to retrieve it via projections ().
Without projections, Hibernate Search will per default execute a
Lucene query in order to find the database identifiers of the entities
matching the query critera and use these identifiers to retrieve managed
objects from the database. The decision for or against projection has to
- be made on a case to case basis. The default behaviour -
- Store.NO - is recommended since it returns managed
- objects whereas projections only return object arrays.
+ be made on a case to case basis. The default behaviour is recommended
+ since it returns managed objects whereas projections only return object
+ arrays.
After this short look under the hood let's go back to annotating the
Book class. Another annotation we have not yet
@@ -431,7 +430,7 @@ fullTextEntityManager.createIndexer().startAndWait();
After executing the above code, you should be able to see a Lucene
index under /var/lucene/indexes/example.Book. Go ahead
an inspect this index with Luke. It will help you to
+ url="http://code.google.com/p/luke/">Luke. It will help you to
understand how Hibernate Search works.
@@ -439,11 +438,13 @@ fullTextEntityManager.createIndexer().startAndWait();
Searching
Now it is time to execute a first search. The general approach is to
- create a native Lucene query and then wrap this query into a
- org.hibernate.Query in order to get all the functionality one is used to
- from the Hibernate API. The following code will prepare a query against
- the indexed fields, execute it and return a list of
- Books.
+ create a Lucene query (either via the Lucene API () or via the Hibernate Search query
+ DSL ()) and then wrap this query
+ into a org.hibernate.Query in order to get all the
+ functionality one is used to from the Hibernate API. The following code
+ will prepare a query against the indexed fields, execute it and return a
+ list of Books.
Using Hibernate Session to create and execute a search
@@ -451,7 +452,9 @@ fullTextEntityManager.createIndexer().startAndWait();
FullTextSession fullTextSession = Search.getFullTextSession(session);
Transaction tx = fullTextSession.beginTransaction();
-// create native Lucene query
+// create native Lucene query unsing the query DSL
+// alternatively you can write the Lucene query using the Lucene query parser
+// or the Lucene programmatic API. The Hibernate Search DSL is recommended though
QueryBuilder qb = fullTextSession.getSearchFactory()
.buildQueryBuilder().forEntity( Book.class ).get();
org.apache.lucene.search.Query query = qb
@@ -459,8 +462,7 @@ org.apache.lucene.search.Query query = qb
.onFields("title", "subtitle", "authors.name", "publicationDate")
.matching("Java rocks!");
.createQuery();
-//alternatively you can wa\rite the Lucene query using the Lucene query parser
-//or their programmatic API. The Hibernate Search DSL is recommended though
+
// wrap Lucene query in a org.hibernate.Query
org.hibernate.Query hibQuery =
@@ -481,7 +483,9 @@ FullTextEntityManager fullTextEntityManager =
org.hibernate.search.jpa.Search.getFullTextEntityManager(em);
em.getTransaction().begin();
-// create native Lucene query
+// create native Lucene query unsing the query DSL
+// alternatively you can write the Lucene query using the Lucene query parser
+// or the Lucene programmatic API. The Hibernate Search DSL is recommended though
QueryBuilder qb = fullTextSession.getSearchFactory()
.buildQueryBuilder().forEntity( Book.class ).get();
org.apache.lucene.search.Query query = qb
@@ -489,8 +493,6 @@ org.apache.lucene.search.Query query = qb
.onFields("title", "subtitle", "authors.name", "publicationDate")
.matching("Java rocks!");
.createQuery();
-//alternatively you can wa\rite the Lucene query using the Lucene query parser
-//or their programmatic API. The Hibernate Search DSL is recommended though
// wrap Lucene query in a javax.persistence.Query
javax.persistence.Query persistenceQuery =
@@ -513,8 +515,9 @@ em.close();
queries: "refactor", "refactors", "refactored" and "refactoring". In
Lucene this can be achieved by choosing an analyzer class which applies
word stemming during the indexing as well
- as search process. Hibernate Search offers several ways to
- configure the analyzer to use (see ):
+ as the search process. Hibernate Search offers several ways to
+ configure the analyzer to be used (see ):
@@ -614,10 +617,10 @@ public class Book {
linkend="search-architecture" />) and explore the basic features in more
detail. Two topics which were only briefly touched in this tutorial were
analyzer configuration () and field bridges
- (), both important features
+ (). Both are important features
required for more fine-grained indexing. More advanced topics cover
- clustering (, )
- and large indexes handling
- ().
+ clustering (, ) and large index handling ().
diff --git a/hibernate-search/src/main/docbook/en-US/modules/query.xml b/hibernate-search/src/main/docbook/en-US/modules/query.xml
index d23825ef37f..66075a339c1 100755
--- a/hibernate-search/src/main/docbook/en-US/modules/query.xml
+++ b/hibernate-search/src/main/docbook/en-US/modules/query.xml
@@ -159,8 +159,8 @@ List result = fullTextQuery.getResultList(); //return a list of managed objects
org.hibernate.Query as your primary query
manipulation API.
-
- Building a Lucene query from scratch
+
+ Building a Lucene query using the Lucene API
You have several options: use the query parser (fine for simple
queries) or the Lucene programmatic API (for more complex use cases).
@@ -174,7 +174,8 @@ List result = fullTextQuery.getResultList(); //return a list of managed objects
- Building a Lucene query with Hibernate Search query DSL
+ Building a Lucene query with the Hibernate Search query
+ DSL
Writing full-text queries with the Lucene programmatic API is
quite complex. It's even more complex to understand the code once