From 1d6a43f55e5509e6ce9d3cb103cc3afba51cd165 Mon Sep 17 00:00:00 2001 From: Hardy Ferentschik Date: Fri, 3 Dec 2010 16:03:41 +0100 Subject: [PATCH] HSEARCH-637 Reviewing Getting Started chapter. Updating links and requirement section. --- .../src/main/docbook/en-US/hsearch.ent | 1 + .../src/main/docbook/en-US/master.xml | 25 ++-- .../docbook/en-US/modules/getting-started.xml | 107 +++++++++--------- .../src/main/docbook/en-US/modules/query.xml | 7 +- 4 files changed, 72 insertions(+), 68 deletions(-) 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