[hibernate-commits] Hibernate SVN: r13955 - in search/trunk/doc/reference/en: modules and 1 other directory.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Tue Aug 28 15:35:51 EDT 2007
Author: hardy.ferentschik
Date: 2007-08-28 15:35:50 -0400 (Tue, 28 Aug 2007)
New Revision: 13955
Modified:
search/trunk/doc/reference/en/master.xml
search/trunk/doc/reference/en/modules/getting-started.xml
Log:
HSEARCH-98 Minor changes and more explicit code examples.
Modified: search/trunk/doc/reference/en/master.xml
===================================================================
--- search/trunk/doc/reference/en/master.xml 2007-08-28 15:39:14 UTC (rev 13954)
+++ search/trunk/doc/reference/en/master.xml 2007-08-28 19:35:50 UTC (rev 13955)
@@ -39,8 +39,8 @@
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. <sbr/>
- Hibernate Search indexes your domain model thanks to a few annotations,
- takes care of database/index synchronization and brings you back
+ Hibernate Search indexes your domain model with the help of a few annotations,
+ takes care of database/index synchronization and brings back
regular managed objects from free text queries. To achieve this Hibernate Search
is combining the power of <ulink url="http://www.hibernate.org">Hibernate</ulink> and
<ulink url="http://lucene.apache.org">Apache Lucene</ulink>.
Modified: search/trunk/doc/reference/en/modules/getting-started.xml
===================================================================
--- search/trunk/doc/reference/en/modules/getting-started.xml 2007-08-28 15:39:14 UTC (rev 13954)
+++ search/trunk/doc/reference/en/modules/getting-started.xml 2007-08-28 19:35:50 UTC (rev 13955)
@@ -69,17 +69,18 @@
If you are using Hibernate via JPA you can also add the properties to <literal>persistence.xml</literal>.
The good news is that for standard use most properties offer a sensible default.
</para>
- <para>
- In this tutorial we will start off <classname>FSDirectoryProvider</classname> which will give us
- the ability to physically inspect the Lucene indexes (eg via
- <ulink url="http://www.getopt.org/luke/">Luke</ulink>) created by
- Hibernate Search. Once you have a working configuration you can start experimenting with
- other directory providers (see <xref linkend="search-configuration-directory"/>).
+ <para>
+ Apache Lucene has a notion of <literal>Directory</literal> to store the index files. Hibernate Search handles
+ the initialization and configuration of a Lucene <literal>Directory</literal> instance via a <literal>DirectoryProvider</literal>.
+ In this tutorial we will use a subclass of <literal>DirectoryProvider</literal> called
+ <classname>FSDirectoryProvider</classname>. This will give us the ability to physically inspect the Lucene
+ indexes created by Hibernate Search (eg via <ulink url="http://www.getopt.org/luke/">Luke</ulink>).
+ Once you have a working configuration you can start experimenting with other directory providers (see <xref linkend="search-configuration-directory"/>).
</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.
+ Lets assume that your application contains the Hibernate managed class <classname>example.Book</classname> and
+ you now want to add free text search capabilities to your application
+ in order to search body and summary of the books contained in your database.
</para>
<programlisting>
package exmaple.Book
@@ -105,7 +106,7 @@
<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> property.
- You also want to specify the default root directory for all indexes via <literal>hibernate.search.default.indexBase</literal>.
+ You also have to specify the default root directory for all indexes via <literal>hibernate.search.default.indexBase</literal>.
</para>
<programlisting>
@@ -122,7 +123,7 @@
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.
+ index unicity for a given entity. <literal>@DocumentId</literal> marks the property to use for this purpose.
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
@@ -132,7 +133,7 @@
<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" />
+ the indexed data in order to avoid database roundtrips refer to projections in <xref linkend="projections" />
</para>
<programlisting>
@@ -177,7 +178,7 @@
<programlisting>
FullTextSession fullTextSession = Search.createFullTextSession(session);
Transaction tx = fullTextSession.beginTransaction();
-... // retrieving the all books from the database using HQL
+List books = session.createQuery("from Book as book").list();
for (Book book : books) {
fullTextSession.index(book);
}
@@ -189,7 +190,7 @@
<programlisting>
EntityManager em = entityManagerFactory.createEntityManager();
FullTextEntityManager fullTextEntityManager = Search.createFullTextEntityManager(em);
-... // retrieving the all books from the database using JPA-QL
+List books = em.createQuery("select book from Book as book").getResultList();
for (Book book : books) {
fullTextEntityManager.index(book);
}
@@ -204,16 +205,14 @@
<title>Searching</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
+ the fields <literal>summary</literal> and <literal>body</literal>, execute it and return
a list of <classname>Book</classname>s:
</para>
<para>
Example using Hibernate Session:
</para>
<programlisting>
-// the use of HibernateUtil is only an example of how to get hold of the current session!
-Session session = HibernateUtil.getCurrentSession();
-FullTextSession fullTextSession = Search.createFullTextSession();
+FullTextSession fullTextSession = Search.createFullTextSession(session);
Transaction tx = fullTextSession.beginTransaction();
@@ -247,12 +246,22 @@
Assume that one of your indexed book entities contains the text "Java rocks" and you want to get
hits for all of the following queries: "rock", "rocks", "rocked" and "rocking". In Lucene this
can be achieved by choosing an analyzer class which applies word stemming during the indexing process.
- Hibernate Search exposes this Lucene functionality and allows to specify the analyzer class via the
- property <literal>hibernate.search.analyzer</literal> in the configuration file or via an annotation
- on entity or field level (see <xref linkend="analyzer"/>).
+ Hibernate Search offers several ways to configure the analyzer to use (see <xref linkend="analyzer"/>):
- The following example uses an annotation on the entity level to apply a English language analyzer
- which would help you to achieve your goal:
+ <itemizedlist>
+ <listitem>Setting the <literal>hibernate.search.analyzer</literal> property in the configuration file.
+ The specified class will then be the default analyzer.
+ </listitem>
+ <listitem>Setting the <literal>Analyzer</literal> annotation on entity level.
+ </listitem>
+ <listitem>Setting the <literal>Analyzer</literal> annotation on field level.
+ </listitem>
+ </itemizedlist>
+
+ The following example uses the entity level annotation to apply a English language analyzer
+ which would help you to achieve your goal. The class <classname>EnglishAnalyzer</classname>
+ is a custom class using the Snowball English Stemmer from the
+ <ulink url="http://lucene.apache.org/java/docs/lucene-sandbox/">Lucene Sandbox</ulink>.
<programlisting>
package example.Book
...
@@ -303,7 +312,7 @@
The above paragraphs hopefully helped you getting started with Hibernate Search. You
should by now have a simple file system based index and be able to search and retrieve a list of
managed objects via Hibernate Search. The next step is to get more familiar with the
- overall architecture and explore the basic features in more detail.
+ overall architecture ((<xref linkend="search-architecture"/>)) and explore the basic features in more detail.
</para>
<para>
Two topics which where only briefly touched in this tutorial were analyzer configuration
@@ -311,7 +320,7 @@
features required for more fain grained indexing.
</para>
<para>
- More advanced topics cover topics like clustering (<xref linkend="jms-backend"/>) and large indexes
+ More advanced topics cover clustering (<xref linkend="jms-backend"/>) and large indexes
handling (<xref linkend="search-configuration-directory-sharding"/>).
</para>
</section>
More information about the hibernate-commits
mailing list