From hibernate-commits at lists.jboss.org Thu Nov 13 05:56:39 2008 Content-Type: multipart/mixed; boundary="===============2606446158479486495==" MIME-Version: 1.0 From: hibernate-commits at lists.jboss.org To: hibernate-commits at lists.jboss.org Subject: [hibernate-commits] Hibernate SVN: r15559 - in search/trunk/doc/reference/en: modules and 1 other directory. Date: Thu, 13 Nov 2008 05:56:39 -0500 Message-ID: --===============2606446158479486495== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: hardy.ferentschik Date: 2008-11-13 05:56:39 -0500 (Thu, 13 Nov 2008) New Revision: 15559 Modified: search/trunk/doc/reference/en/master.xml search/trunk/doc/reference/en/modules/getting-started.xml search/trunk/doc/reference/en/modules/mapping.xml Log: started a full review of the online docs - more to come ;-) Modified: search/trunk/doc/reference/en/master.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/master.xml 2008-11-12 22:24:55 UTC (rev 1= 5558) +++ search/trunk/doc/reference/en/master.xml 2008-11-13 10:56:39 UTC (rev 1= 5559) @@ -23,12 +23,12 @@ ~ 51 Franklin Street, Fifth Floor ~ Boston, MA 02110-1301 USA --> - - - + + + ]> - Hibernate Search @@ -51,30 +51,42 @@ Preface = - Full text search engines like Apache - Lucene are very powerful technologies to add efficient f= ree - text search capabilities to applications. However, they suffer several= mismatches when - dealing with object domain models. Amongst other things indexes have t= o be kept up to date and - mismatches between index structure and domain model as well as query m= ismatches = - have to be avoided. - - - Hibernate Search indexes your domain model with the help of a few anno= tations, - takes care of database/index synchronization and brings back - regular managed objects from free text queries. To achieve this Hibern= ate Search - is combining the power of Hibe= rnate and = - Apache Lucene. - + Full text search engines like Apache Lucene are very powerful + technologies to add efficient free text search capabilities to + applications. However, they suffer several mismatches when dealing with + 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. = + Hibernate Search indexes your domain model with the help of a few + annotations, takes care of database/index synchronization and brings b= ack + regular managed objects from free text queries. To achieve this Hibern= ate + Search is combining the power of Hibernate and Apache Lucene. = - - - - - - - - + = + + + + + + + + + + + + + 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-11-12 22= :24:55 UTC (rev 15558) +++ search/trunk/doc/reference/en/modules/getting-started.xml 2008-11-13 10= :56:39 UTC (rev 15559) @@ -48,8 +48,7 @@ = A JDK or JRE version 5 or greater.= You can download a Java Runtime for Windows/Linux/Solaris here - . + url=3D"http://java.sun.com/javase/downloads/">here. = @@ -57,7 +56,7 @@ = hibernate-search.jar and all the dependencies from the lib directory of the - Hibernate Search distribution, especially lucene :) + Hibernate Search distribution, especially lucene. = @@ -120,7 +119,7 @@ <dependency> <groupId>org.hibernate</groupId> <artifactId>hibernate-search</artifactId> - <version>3.1.0.Beta2</version> + <version>3.1.0.CR1</version> </dependency> <dependency> <groupId>org.hibernate</groupId> @@ -151,18 +150,18 @@ = Not all dependencies are required. Only the hibernate-search dependeny is mandatory. This - dependeny, together with its required transitive dependencies, contains - everything needed to use Hibernate Search. + dependency, together with its required transitive dependencies, contain + all required classes needed to use Hibernate Search. hibernate-annotations is only needed if you want = to use annotations to configure your domain model as we do in this tutori= al. - However, even if you choose not to use Hibernate Annotations you will - still have to use the Hibernate Search specific annotations to configu= re - your Lucene index. Currently there is no XML configuration option - available for Hibernate Search. + However, even if you choose not to use Hibernate Annotations you still + have to use the Hibernate Search specific annotations, which are bundl= ed + 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 only needed if you want to utilize Solr's analyzer - framework. More about this later. + dependencies are needed if you want to utilize Solr's analyzer framewo= rk. + More about this later. =
@@ -175,8 +174,8 @@ hibernate.cfg.xml. If you are using Hibernate via J= PA you can also add the properties to persistence.xml.= The good news is that for standard use most properties offer a sensible - default. Within persistence.xml this could look l= ike - this: + default. An example persistence.xml configuration + could look like this: = ... @@ -188,8 +187,8 @@ 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 a notion of Directory to - store the index files. Hibernate Search handles the initialization and + property. Apache Lucene has the notion of a Directory + to store the index files. Hibernate Search handles the initialization = and configuration of a Lucene Directory instance via a DirectoryProvider. In this tutorial we will use a subclass of DirectoryProvider called @@ -202,8 +201,8 @@ for all indexes via hibernate.search.default.indexBase. = - Lets further assume that your application contains the Hibernate - managed classes example.Book and + Lets assume that your application contains the Hibernate managed + classes example.Book and example.Author and you want to add free text se= arch capabilities to your application in order to search the books containe= d in your database. @@ -262,8 +261,10 @@ Book as indexable. By design Hibernate Search n= eeds 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. + this purpose and is in most cases the same as the database primary key= . In + fact since the latest release of Hibernate Search + @DocumentId is optional in the case where an + @Id annotation exists. = Next you have to mark the fields you want to make searchable. Le= t's start with title and subtitle and @@ -275,16 +276,15 @@ 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 settings and probably a good choice + 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. - Is it not better then to always use projections? The answer is no, sin= ce - projections only returns object arrays and not managed entities. The - decision for or against projection has to be made on a case to case - basis. + 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. = After this short look under the hood let's go back to annotating= the Book class. Another annotation we have not yet @@ -404,8 +404,9 @@ = After executing the above code, you should be able to see a Luce= ne index under /var/lucene/indexes/example.Book. Go ah= ead - an inspect this index. It will help you to understand how Hibernate Se= arch - works. + an inspect this index with Luke. It will help you to + understand how Hibernate Search works.
=
@@ -422,10 +423,10 @@ = Transaction tx =3D fullTextSession.beginTransaction(); = -MultiFieldQueryParser parser =3D new MultiFieldQueryParser( new String[]{"= title", "subtitle", "authors.name", "publicationDate"}, = - new StandardAnalyzer()); +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!" ); -org.hibernate.Query hibQuery =3D fullTextSession.createFullTextQuery( quer= y, Book.class ); +org.hibernate.Query hibQuery =3D fullTextSession.createFullTextQuery(query= , Book.class); List result =3D hibQuery.list(); = tx.commit(); @@ -439,10 +440,10 @@ = FullTextEntityManager fullTextEntityManager =3D = org.hibernate.hibernate.search.jpa.Search.getFullTextEntityManager(em); -MultiFieldQueryParser parser =3D new MultiFieldQueryParser( new String[]{"= title", "subtitle", "authors.name", "publicationDate"}, = - new StandardAnalyzer()); +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!" ); -org.hibernate.Query hibQuery =3D fullTextEntityManager.createFullTextQuery= ( query, Book.class ); +org.hibernate.Query hibQuery =3D fullTextEntityManager.createFullTextQuery= (query, Book.class); List result =3D hibQuery.list();
@@ -450,14 +451,14 @@
Analyzer = - Assume that one of your indexed book entities has the title - "Refactoring: Improving the Design of Existing Code" and you want to g= et - hits for all of the following queries: "refactor", "refactors", - "refactored" and "refactoring". In Lucene this can be achieved by choo= sing - 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 ): + Let's make things a little more interesting now. Assume that one= of + your indexed book entities has the title "Refactoring: Improving the + 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 ): = @@ -488,7 +489,7 @@ Wiki. Note that depending on the chosen factory class addition= al libraries on top of the Solr dependencies might be required. For examp= le, the PhoneticFilterFactory depends on commons-codec. + url=3D"http://commons.apache.org/codec">commons-codec. = In the example below a StandardTokenizerFactory is used followed by two @@ -561,7 +562,7 @@ mvn archetype:create \ = -DarchetypeGroupId=3Dorg.hibernate \ -DarchetypeArtifactId=3Dhibernate-search-quickstart \ = - -DarchetypeVersion=3D3.1.0.Beta2 \ + -DarchetypeVersion=3D3.1.0.CR1 \ -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 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-11-12 22:24:55 U= TC (rev 15558) +++ search/trunk/doc/reference/en/modules/mapping.xml 2008-11-13 10:56:39 U= TC (rev 15559) @@ -183,8 +183,10 @@ Finally, the id property of an entity is a special property us= ed by Hibernate Search to ensure index unicity of a given entity. By design, an id has to be stored and must not be tokenized. To mark a - property as index id, use the @DocumentId - annotation. + property as index id, use the @DocumentId annotat= ion. + If you are using Hibernate Annotations and you have specified @Id you + can omit @DocumentId. The chosen entity id will also be used as docu= ment + id. = @Entity @Indexed(index=3D"indexes/essays") @@ -206,13 +208,7 @@ These annotations define an index with three fields: id , Abstract and text . Note that by default the field name is - decapitalized, following the JavaBean specification. - - - You must specify - @DocumentId on the identifier property of your - entity class. - + decapitalized, following the JavaBean specification
=
@@ -1208,7 +1204,7 @@ private String network; private String branchHead; private String branch; - private Integer maxEmployees; + private Integer maxEmployees ... } = @@ -1275,21 +1271,13 @@ sure however, to not use this annotation with @DocumentId as your system will break. = - - = - @ProvidedId (bridge =3D org.my.own.package.MyCustomBridge) - @Indexed - public class MyClass{ - = - @Field - String MyString; - = - ... - = - } - = - = - + @ProvidedId (bridge =3D org.my.own.package.MyCustomB= ridge) +(a)Indexed +public class MyClass{ + @Field + String MyString; + ... +}
--===============2606446158479486495==--