From hibernate-commits at lists.jboss.org Wed Dec 3 11:24:25 2008 Content-Type: multipart/mixed; boundary="===============7042389793961409197==" MIME-Version: 1.0 From: hibernate-commits at lists.jboss.org To: hibernate-commits at lists.jboss.org Subject: [hibernate-commits] Hibernate SVN: r15655 - search/trunk/doc/reference/en/modules. Date: Wed, 03 Dec 2008 11:24:24 -0500 Message-ID: --===============7042389793961409197== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: hardy.ferentschik Date: 2008-12-03 11:24:24 -0500 (Wed, 03 Dec 2008) New Revision: 15655 Modified: search/trunk/doc/reference/en/modules/getting-started.xml search/trunk/doc/reference/en/modules/mapping.xml Log: HSEARCH-303 Modified: search/trunk/doc/reference/en/modules/getting-started.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- search/trunk/doc/reference/en/modules/getting-started.xml 2008-12-03 13= :59:43 UTC (rev 15654) +++ search/trunk/doc/reference/en/modules/getting-started.xml 2008-12-03 16= :24:24 UTC (rev 15655) @@ -54,18 +54,20 @@ Hibernate Search = - hibernate-search.jar and all the + hibernate-search.jar and all runtime dependencies from the lib directory of the - Hibernate Search distribution, especially lucene. + Hibernate Search distribution. Please refer to + README.txt in the lib directory to unders= tand + which dependencies are required. = Hibernate Core = This instructions have been tested against Hibernate 3.= 3.x. - Next to the main hibernate3.jar you will ne= ed - all required libaries from the lib director= y of - the distribution. Refer to README.txt in the + You will need hibernate-core.jar and its + transitive dependencies from the lib direct= ory + of the distribution. Refer to README.txt in= the lib directory of the distribution to determ= ine the minimum runtime requirements. @@ -95,7 +97,7 @@ =
- Maven + Using Maven = Instead of managing all dependencies manually, maven users have = the possibility to use the pom.xml or settings.xml: = - + + Adding the JBoss maven repository to + <filename>settings.xml</filename> + + <repository> <id>repository.jboss.org</id> <name>JBoss Maven Repository</name> @@ -112,10 +118,14 @@ <layout>default</layout> </repository> + = Then add the following dependencies to your pom.xml: = - + + Maven dependencies for Hibernate Search + + <dependency> <groupId>org.hibernate</groupId> <artifactId>hibernate-search</artifactId> @@ -147,6 +157,7 @@ <version>2.4.0</version> </dependency> + = Not all dependencies are required. Only the hibernate-search dependeny is mandatory. This @@ -159,16 +170,17 @@ with the hibernate-search jar file, to configure your Lucene index. Currently there is no XML configuration available for Hibernate Search. hibernate-entitymanager is required if you want to - use Hibernate Search in conjunction with JPA. Finally, the Solr - dependencies are needed if you want to utilize Solr's analyzer framewo= rk. - More about this later. + use Hibernate Search in conjunction with JPA. The Solr dependencies are + needed if you want to utilize Solr's analyzer framework. More about th= is + later. And finally, the lucene-snowball dependency = is + needed if you want to utililze Lucene's snowball stemmer.
=
Configuration = Once you have downloaded and added all required dependencies to = your - application you have to add a few properties to your hibernate + application you have to add a couple of properties to your hibernate configuration file. If you are using Hibernate directly this can be do= ne in hibernate.properties or hibernate.cfg.xml. If you are using Hibernate via J= PA @@ -177,14 +189,23 @@ default. An example persistence.xml configuration could look like this: = - + + Basic configuration options to be added to + <literal><filename>hibernate.properties</filename></literal>, + <literal><filename>hibernate.cfg.xml</filename></literal> or + <filename>persistence.xml</filename> + + ... <property name=3D"hibernate.search.default.directory_provider" = value=3D"org.hibernate.search.store.FSDirectoryProvider"/> = = <property name=3D"hibernate.search.default.indexBase" value=3D"/var/luc= ene/indexes"/> = ... - First you have to tell Hibernate Search which + + + + First you have to tell Hibernate Search which DirectoryProvider to use. This can be achieved = by setting the hibernate.search.default.directory_provider property. Apache Lucene has the notion of a Directory @@ -207,7 +228,11 @@ capabilities to your application in order to search the books containe= d in your database. = - + + Example entities Book and Author before adding Hibernate Sear= ch + specific annotatons + + package example; ... @Entity @@ -234,7 +259,7 @@ } = = - + package example; ... @Entity @@ -253,7 +278,8 @@ ... } = - + + = To achieve this you have to add a few annotations to the Book and Author class. T= he @@ -262,7 +288,7 @@ 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 latest release of Hibernate Search + fact since the 3.1.0 release of Hibernate Search @DocumentId is optional in the case where an @Id annotation exists. = @@ -276,16 +302,20 @@ talk more about analyzers a little later on. The second parameter we specify within @Field, store=3DStore.NO, ensures that the actual data will not be s= tored - in the index. This is the default setting and probably a good choice - unless you want to avoid database roundtrips and retrieve the indexed = data - via projections (). Without projection= s, - Hibernate Search will per default execute the Lucene query in order to - find the database identifiers of the entities matching the query crite= ra - and use these identifiers to retrieve managed objects from the databas= e. - The decision for or against projection has to be made on a case to case - basis. The default behaviour is recommended since it returns managed - objects whereas projections only returns object arrays. + in the index. Whether this data is stored in the index or not has noth= ing + 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 manag= ed + 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. + After this short look under the hood let's go back to annotating= the Book class. Another annotation we have not yet discussed is @DateBridge. This annotation is one of= the @@ -302,7 +332,7 @@ (@ManyToMany, @*ToOne and @Embedded) as part of the owning entity. This is ne= eded since a Lucene index document is a flat data structure which does not = know - anything about object relations. To ensure that the author's name wil = be + anything about object relations. To ensure that the authors' name wil = be searchable you have to make sure that the names are indexed as part of= the book itself. On top of @IndexedEmbedded you will al= so have to mark all fields of the associated entity you want to have incl= uded @@ -312,7 +342,11 @@ These settings should be sufficient for now. For more details on entity mapping refer to . = - + + Example entities after adding Hibernate Search + annotations + + package example; ... @Entity @@ -346,7 +380,7 @@ } = - + package example; ... @Entity @@ -366,6 +400,7 @@ ... } +
=
@@ -379,28 +414,41 @@ achieve this by using one of the following code snipplets (see also ): = - Example using Hibernate Session: + + Using Hibernate Session to index data = - + FullTextSession fullTextSession =3D Search.getFullTextSession(session); Transaction tx =3D fullTextSession.beginTransaction(); + List books =3D session.createQuery("from Book as book").list(); for (Book book : books) { - fullTextSession.index(book); + fullTextSession.index(book); } + tx.commit(); //index is written at commit time = + = - Example using JPA: + + Using JPA to index data = - + EntityManager em =3D entityManagerFactory.createEntityManager(); FullTextEntityManager fullTextEntityManager =3D Search.getFullTextEntityMa= nager(em); +em.getTransaction().begin(); + List books =3D em.createQuery("select book from Book as book").getResultLi= st(); for (Book book : books) { - fullTextEntityManager.index(book); + fullTextEntityManager.index(book); } = + +em.getTransaction().commit(); +em.close(); + + + = After executing the above code, you should be able to see a Luce= ne index under /var/lucene/indexes/example.Book. Go ah= ead @@ -412,40 +460,62 @@
Searching = - Now it is time to execute a first search. The following code will - prepare a query against the indexed fields, execute it and return a li= st - of Books: + Now it is time to execute a first search. The general approach i= s 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. = - Example using Hibernate Session: + + Using Hibernate Session to create and execute a search = - + FullTextSession fullTextSession =3D Search.getFullTextSession(session); - Transaction tx =3D fullTextSession.beginTransaction(); = +// create native Lucene query String[] fields =3D new String[]{"title", "subtitle", "authors.name", "pub= licationDate"}; MultiFieldQueryParser parser =3D new MultiFieldQueryParser(fields, new Sta= ndardAnalyzer()); Query query =3D parser.parse( "Java rocks!" ); + +// wrap Lucene query in a org.hibernate.Query org.hibernate.Query hibQuery =3D fullTextSession.createFullTextQuery(query= , Book.class); + +// execute search List result =3D hibQuery.list(); = tx.commit(); session.close(); = + = - Example using JPA: + + Using JPA to create and execute a search = - + EntityManager em =3D entityManagerFactory.createEntityManager(); - FullTextEntityManager fullTextEntityManager =3D = org.hibernate.hibernate.search.jpa.Search.getFullTextEntityManager(em); +em.getTransaction().begin(); + +// create native Lucene query String[] fields =3D new String[]{"title", "subtitle", "authors.name", "pub= licationDate"}; MultiFieldQueryParser parser =3D new MultiFieldQueryParser(fields, new Sta= ndardAnalyzer()); Query query =3D parser.parse( "Java rocks!" ); + +// wrap Lucene query in a org.hibernate.Query org.hibernate.Query hibQuery =3D fullTextEntityManager.createFullTextQuery= (query, Book.class); + +// execute search List result =3D hibQuery.list(); + +em.getTransaction().commit(); +em.close(); + + +
=
@@ -456,9 +526,9 @@ Design of Existing Code" and you want to get hits for all of the follo= wing queries: "refactor", "refactors", "refactored" and "refactoring". In Lucene this can be achieved by choosing an analyzer class which applies - word stemming during the indexing and - search process. Hibernate Search offers several ways to configure the - analyzer to use (see ): + word stemming during the indexing as well + as search process. Hibernate Search offers several ways to + configure the analyzer to use (see ): = @@ -497,15 +567,19 @@ SnowballPorterFilterFactory. The standard token= izer splits words at punctuation characters and hyphens while keeping email addresses and internet hostnames intact. It is a good general purpose - tokenizer. The lowercase filter lowercases then the letters in each to= ken - whereas the snowball filter finally applies the actual language + tokenizer. The lowercase filter lowercases the letters in each token + whereas the snowball filter finally applies language specific stemming. = Generally, when using the Solr framework you have to start with a tokenizer followed by an arbitrary number of filters. = - + + Using <classname>@AnalyzerDef</classname> and the Solr framew= ork + to define and use an analyzer = + + package example; ... @Entity @@ -549,6 +623,7 @@ } = +
=
@@ -559,20 +634,25 @@ command you can create an initial runnable maven project structure populated with the example code of this tutorial. = - mvn archetype:create \ = + + Using the maven achetype to create tutorial sources + + mvn archetype:create \ = -DarchetypeGroupId=3Dorg.hibernate \ -DarchetypeArtifactId=3Dhibernate-search-quickstart \ = -DarchetypeVersion=3D3.1.0.GA \ - -DgroupId=3Dmy.company -DartifactId=3DquickstartUsing= the - maven project you can execute the examples, inspect the file system ba= sed - index and search and retrieve a list of managed objects. Just run - mvn package to compile the sources and run the un= it - tests. + -DgroupId=3Dmy.company -DartifactId=3Dquickstart + = + Using the maven project you can execute the examples, inspect the + file system based index and search and retrieve a list of managed obje= cts. + Just run mvn package to compile the sources and r= un + the unit tests. + The next step after this tutorial is to get more familiar with t= he overall architecture of Hibernate Search () and explore the basic features in = more - detail. Two topics which where only briefly touched in this tutorial w= ere + detail. Two topics which were only briefly touched in this tutorial we= re analyzer configuration () and field bridg= es (), both important features required for more fine-grained indexing. More advanced topics cover Modified: search/trunk/doc/reference/en/modules/mapping.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- search/trunk/doc/reference/en/modules/mapping.xml 2008-12-03 13:59:43 U= TC (rev 15654) +++ search/trunk/doc/reference/en/modules/mapping.xml 2008-12-03 16:24:24 U= TC (rev 15655) @@ -1274,7 +1274,7 @@
=
- @ClassBridge + ClassBridge = It is sometimes useful to combine more than one property of a given entity and index this combination in a specific way into the --===============7042389793961409197==--