Author: hardy.ferentschik Date: 2007-08-06 12:47:04 -0400 (Mon, 06 Aug 2007) New Revision: 12902 Modified: trunk/HibernateExt/search/doc/reference/en/modules/getting-started.xml Log: HSEARCH-98 More getting strarted ... Modified: trunk/HibernateExt/search/doc/reference/en/modules/getting-started.xml =================================================================== --- trunk/HibernateExt/search/doc/reference/en/modules/getting-started.xml 2007-08-06 16:46:42 UTC (rev 12901) +++ trunk/HibernateExt/search/doc/reference/en/modules/getting-started.xml 2007-08-06 16:47:04 UTC (rev 12902) @@ -3,8 +3,6 @@ <chapter id="getting-started"> <title>Getting started</title> - <important>Under construction</important> - <para> The following chapter will guide you through the minimal steps required to integrate Hibernate Search into an existing @@ -28,37 +26,86 @@ </entry> </row> <row> + <entry>Hibernate Search</entry> + <entry> + Version 3.0.0.Beta4. + </entry> + </row> + <row> + <entry>Lucene</entry> + <entry> + Version 2.2.0. This library is contained in the Hibernate Search zip file. + </entry> + </row> + <row> + <entry>EJB3 Persistence</entry> + <entry> + Contained in the Hibernate Search zip file. + </entry> + </row> + <row> + <entry>JMS</entry> + <entry> + Contained in the Hibernate Search zip file. Needed for JMS configuration + via <classname>org.hibernate.search.store.FSMasterDirectoryProvider</classname> + resp. <classname>org.hibernate.search.store.FSSlaveDirectoryProvider</classname>. + See <xref linkend="jms-backend"/>. + </entry> + </row> + <row> <entry>Hibernate Core</entry> <entry> - Version >= 3.2.2 + Version >= 3.2.2 with all its dependencies. </entry> </row> <row> <entry>Hibernate Annotations</entry> <entry> - Version 3.3x + Version 3.3x with all its dependencies </entry> - </row> + </row> + <row> + <entry>Hibernate Commons Annotations</entry> + <entry> + Contained in the Hibernate Search zip file. + </entry> + </row> </tbody> </tgroup> </table> <para> - You can download the dependencies from the Hibernate - <ulink url="http://www.hibernate.org/6.html">download site</ulink>. The required dependency versions - can also be found in the <ulink url="http://www.hibernate.org/6.html#A3">Compatibility Matrix</ulink>. + You can download these dependencies from the Hibernate + <ulink url="http://www.hibernate.org/6.html">download site</ulink>. You can also verify the + dependency versions against the <ulink url="http://www.hibernate.org/6.html#A3"> + Hibernate Compatibility Matrix</ulink>. </para> </section> <section> <title>Hibernate Configuration</title> - Lets assume that your application contains a class <classname>Book</classname> which - is managed by Hibernate. You now want to add free text search abilities to your application - in order to search within the books body and summary. + <para> + Once you have downloaded and added all required dependencies to your application you have + to add a few properties to your hibernate configuration file. The good + news is that for initial experiments most properties offer a sensible default and can + be kept untouched. + We recommend to start with a <classname>FSDirectoryProvider</classname>. + This has the advantage that you can physically inspect (eg via + <ulink url="http://www.getopt.org/luke/">Luke</ulink>) the Lucene indeces created by + Hibernate Search. Once you have a working configuration you can start experimenting with + other <xref linkend="search-configuration-directory"/>s. + </para> + <para> + Lets assume that your application contains the Hibernate managed class <classname>example.Book</classname>. + You now want to add free text search capabilities to your application + in order to search the bodies and summaries of the books contained in your database. + </para> <programlisting> +package exmaple.Book ... @Entity public class Book { + @Id private Integer id; private String body; private String summary; @@ -72,37 +119,76 @@ // standard getters/setters follow here ... </programlisting> - <para> - Once you have downloaded and added all required dependencies to your application you have - to add some basic Hibernate Search properties to your hibernate configuration file. - We recommend to start your first experiments with a <classname>FSDirectoryProvider</classname>. - This has the advantage that you can physically inspect (eg with - <ulink url="http://www.getopt.org/luke/">Luke</ulink>) the Lucene indeces created by - Hibnerate Search. Once you have a working configuration you can start experimenting with - other <xref linkend="search-configuration-directory"/>s. - </para> <para> + First you have to tell Hibernate Search which <classname>DirectoryProvider</classname> to use. + This can be achieved by setting the <literal>hibernate.search.default.directory_provider</literal>. + You also want to specify the default root directory for all indexes via <literal>hibernate.search.default.indexBase</literal>. </para> <programlisting> ... -# the default base directory for the indecies -hibernate.search.default.indexBase = /var/lucene/indices - # the default directory provider hibernate.search.default.directory_provider = org.hibernate.search.store.FSDirectoryProvider + +# the default base directory for the indecies +hibernate.search.default.indexBase = /var/lucene/indexes ... </programlisting> + <para> + Next you have to add three annotations to the <classname>Book</classname> class. The + first annotation <literal>@Indexed</literal> marks <classname>Book</classname> + as indexable. By design Hibernate Search needs to store an untokenized id in the index to ensure + index unicity for a given entity. <literal>@DocumentId</literal> marks the property to use + as id. + Last but not least you have to index the fields you want to make searchable. In our example + these fields are <literal>body</literal> and <literal>summary</literal>. Both properties get + annotated with <literal>@Field</literal>. The property <literal>index=Index.TOKENIZED</literal> will + ensure that the text will be tokenized using the default Lucene analyzer whereas + <literal>store=Store.NO</literal> ensures that the actual data will not be stored in the index. + </para> + <para> + These settings are sufficient for an initial test. For more details on entity mapping refer + to <xref linkend="search-mapping-entity"/>. In case you want to store and retrieve + the indexed data refer to projections in <xref linkend="projections" /> + </para> + + <programlisting> +package exmaple.Book +... +@Entity +<emphasis role="bold">@Indexed</emphasis> +public class Book { + + @Id + <emphasis role="bold">@DocumentId</emphasis> + private Integer id; + + <emphasis role=&quot;bold&quot;&gt;(a)Field(index=Index.TOKENIZED, store=Store.NO)</emphasis> + private String body; + + <emphasis role=&quot;bold&quot;&gt;(a)Field(index=Index.TOKENIZED, store=Store.NO)</emphasis> + private String summary; + private Set&lt;Author&gt; authors = new HashSet&lt;Author&gt;(); + private Author mainAuthor; + private Date publicationDate; + + public Book() { + } + + // standard getters/setters follow here +... + </programlisting> + </section> <section> <title>Indexing</title> <para> - Once you have added these properties to your configuration you will have to trigger an + Once you have added the above properties and annotations it is time to trigger an initial batch index of your books. You can achieve this by adding the following lines - to your code: + to your code (see also <xref linkend="search-batchindex"/>): </para> <programlisting> FullTextSession fullTextSession = Search.createFullTextSession(session); @@ -113,12 +199,33 @@ tx.commit(); //index are written at commit time </programlisting> <para> - For more information see <xref linkend="search-batchindex"/>. + After executing the above code there should be a Lucene index under + <literal>/var/lucene/indexes/example.Book</literal>. Go ahead an inspect this index. It will + help you to understand how Hibernate Search works. </para> </section> <section> <title>First search</title> + <para> + Now it is time to execute a first search. The following code will prepare a query against + the fields <literal>summary</literal> and <literal>body</literal> , execute it and return + a list of <classname>Book</classname>s: + </para> + + <programlisting> +// get hold of the hibernate session. There are multiple ways of doing this depending on the type of application +Session session = HibernateUtil.getCurrentSession(); +FullTextSession s = Search.createFullTextSession(); +Transaction tx = s.beginTransaction(); + +MultiFieldQueryParser parser = new MultiFieldQueryParser( new String[]{"summary", "body"}, new StandardAnalyzer()); +Query query = parser.parse( "Java" ); +org.hibernate.Query hibQuery = s.createFullTextQuery( query, Book.class ); +List result = hibQuery.list(); + +tx.commit(); +session.close(); + </programlisting> </section> - </chapter> \ No newline at end of file