[hibernate-commits] Hibernate SVN: r12902 - trunk/HibernateExt/search/doc/reference/en/modules.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Mon Aug 6 12:47:04 EDT 2007
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
+...
+ at Entity
+<emphasis role="bold">@Indexed</emphasis>
+public class Book {
+
+ @Id
+ <emphasis role="bold">@DocumentId</emphasis>
+ private Integer id;
+
+ <emphasis role="bold">@Field(index=Index.TOKENIZED, store=Store.NO)</emphasis>
+ private String body;
+
+ <emphasis role="bold">@Field(index=Index.TOKENIZED, store=Store.NO)</emphasis>
+ private String summary;
+ private Set<Author> authors = new HashSet<Author>();
+ 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
More information about the hibernate-commits
mailing list