9:13 a.m.
Author: epbernard
Date: 2007-05-31 10:13:25 -0400 (Thu, 31 May 2007)
New Revision: 11603
Modified:
trunk/HibernateExt/search/doc/reference/en/modules/architecture.xml
trunk/HibernateExt/search/doc/reference/en/modules/mapping.xml
trunk/HibernateExt/search/doc/reference/en/modules/query.xml
Log:
Documentation updates
Modified: trunk/HibernateExt/search/doc/reference/en/modules/architecture.xml
===================================================================
--- trunk/HibernateExt/search/doc/reference/en/modules/architecture.xml 2007-05-31
12:50:33 UTC (rev 11602)
+++ trunk/HibernateExt/search/doc/reference/en/modules/architecture.xml 2007-05-31
14:13:25 UTC (rev 11603)
@@ -188,13 +188,15 @@
<title>Reader strategy</title>
<para>When executing a query, Hibernate Search interacts with the Apache
- Lucene indexes through a reader strategy.</para>
+ Lucene indexes through a reader strategy. chosing a reder strategy will
+ depend on the profile of the application (frequent updates, read mostly,
+ asynchronous index update etc).</para>
<section>
<title>not-shared</title>
<para>Every time a query is executed, a Lucene IndexReader is opened.
- This strategy is not the most efficient, opening and warming up an
+ This strategy is not the most efficient: opening and warming up an
IndexReader can be a relatively expensive operation. This strategy is
the default, but will be changed in the future.</para>
</section>
@@ -202,11 +204,13 @@
<section>
<title>shared</title>
- <para>Hibernate Search will share the same IndexReader for a given index
- provided that the IndexReader is still up-to-date. Generally speaking,
- this strategy provides much better performance than the previous one. It
- is especially true if the number of updates is much lower than the
- read.</para>
+ <para>With this strategy, Hibernate Search will share the same
+ IndexReader, for a given Lucene index, across multiple queries and
+ threads provided that the IndexReader is still up-to-date. If the
+ IndexReader is not up-to-date, an new one is opened and provided.
+ Generally speaking, this strategy provides much better performances than
+ the <literal>not-shared</literal> strategy. It is especially true if
the
+ number of updates is much lower than the reads.</para>
</section>
<section>
Modified: trunk/HibernateExt/search/doc/reference/en/modules/mapping.xml
===================================================================
--- trunk/HibernateExt/search/doc/reference/en/modules/mapping.xml 2007-05-31 12:50:33 UTC
(rev 11602)
+++ trunk/HibernateExt/search/doc/reference/en/modules/mapping.xml 2007-05-31 14:13:25 UTC
(rev 11603)
@@ -78,7 +78,7 @@
to use the index query result. For a regular Hibernate Search usage,
storing is not necessary. However you might want to store some fields to
subsequently project them (see <xref linkend="search-query" /> for
more
- information). </para>
+ information).</para>
<para>Whether or not you want to tokenize a property depends on whether
you wish to search the element as is, or by the words it contains. It
@@ -125,7 +125,7 @@
<title>Embedded and associated objects</title>
<para>Associated objects as well as embedded objects can be indexed as
- well as part of the root entity index.</para>
+ part of the root entity index.</para>
<programlisting>@Entity
@Indexed
@@ -168,11 +168,11 @@
<literal>Place</literal> index. The
<literal>Place</literal> index
documents will also contain the fields <literal>address.id</literal>,
<literal>address.street</literal>, and
<literal>address.city</literal>
- which you will be able to query from. This is done thanks to the
+ which you will be able to query. This is enabled by the
<literal>@IndexedEmbedded</literal> annotation.</para>
<para><literal>@ContainedIn</literal> is useful on embedded
objects that
- are also entities (like <literal>Address</literal> in the example): it
+ are also entities (like <literal>Address</literal> in this example):
it
basically means that when an address entity is updated, the index
document of the associated <literal>Place</literal>(s), also have to
be
updated.</para>
@@ -414,8 +414,7 @@
alternative approach is to use a Filter query which will
filter the result query to the appropriate range.</para>
- <para><productname>Hibernate Search</productname> will
support
- a padding mechanism</para>
+ <para>Hibernate Search will support a padding
mechanism</para>
</footnote></para>
</listitem>
</varlistentry>
Modified: trunk/HibernateExt/search/doc/reference/en/modules/query.xml
===================================================================
--- trunk/HibernateExt/search/doc/reference/en/modules/query.xml 2007-05-31 12:50:33 UTC
(rev 11602)
+++ trunk/HibernateExt/search/doc/reference/en/modules/query.xml 2007-05-31 14:13:25 UTC
(rev 11603)
@@ -2,12 +2,11 @@
<chapter id="search-query" xreflabel="Querying">
<title>Querying</title>
- <para>The second most important capability of <productname>Hibernate
Search
- </productname> is the ability to execute a Lucene query and retrieve
- entities managed by an Hibernate session, providing the power of Lucene
- without living the Hibernate paradigm, and giving another dimension to the
- Hibernate classic search mechanisms (HQL, Criteria query, native SQL
- query).</para>
+ <para>The second most important capability of Hibernate Search is the
+ ability to execute a Lucene query and retrieve entities managed by an
+ Hibernate session, providing the power of Lucene without living the
+ Hibernate paradigm, and giving another dimension to the Hibernate classic
+ search mechanisms (HQL, Criteria query, native SQL query).</para>
<para>To access the <productname>Hibernate Search</productname>
querying
facilities, you have to use an Hibernate
@@ -65,9 +64,10 @@
<programlisting>FullTextSession fullTextSession =
Search.createFullTextSession( session );
org.hibernate.Query fullTextQuery = fullTextSession.createFullTextQuery( luceneQuery
);</programlisting>
- <para>If not specified, the query will be applied on all indexed,
- potentially returning all types of indexed classes. It is advised, for
- a performance point of view to restrict the returned types:</para>
+ <para>If not specified, the query will be executed all indexed,
+ potentially returning all types of indexed classes. It is advised,
+ from a performance point of view, to restrict the returned
+ types:</para>
<programlisting>org.hibernate.Query fullTextQuery =
fullTextSession.createFullTextQuery( luceneQuery, Customer.class );
//or
@@ -117,15 +117,15 @@
interface which is a sub interface of
<classname>org.hibernate.Query</classname>.</para>
- <para>Fields used for sorting ust not be tokenized.</para>
+ <para>Fields used for sorting must not be tokenized.</para>
</section>
<section>
<title>Fetching strategy</title>
<para>When you restrict the return types to one class, Hibernate
- Search load the objects and respect the static fetching strategy
- defined in your domain model using a single query.</para>
+ Search loads the objects using a single query. It also respects the
+ static fetching strategy defined in your domain model.</para>
<para>It is often useful, however, to refine the fetching strategy for
a specific use case.</para>
@@ -140,7 +140,8 @@
<para>When defining a criteria query, it is not needed to restrict the
entity types returned while creating the Hibernate Search query from
the full text session: the type is guessed from the criteria query
- itself.</para>
+ itself. Only fetch mode can be adjusted, refrain from applying any
+ other restriction.</para>
<para>One cannot use <methodname>setCriteriaQuery</methodname>
if more
than one entity type is expected to be returned.</para>
@@ -181,7 +182,8 @@
<classname>org.hibernate.search.bridge.TwoWayFieldBridge</classname>
or
<literal>org.hibernate.search.bridge.TwoWayStringBridge</literal>,
- the latter being the simpler version</para>
+ the latter being the simpler version. All Hibernate Search
+ built-in types are two-way.</para>
</listitem>
</itemizedlist>
@@ -203,7 +205,7 @@
<section>
<title>Performance considerations</title>
- <para>If you expect a reasonable result number (for example using
+ <para>If you expect a reasonable number of results (for example using
pagination) and expect to work on all of them,
<methodname>list()</methodname> or
<methodname>uniqueResult()</methodname> are recommended.
@@ -227,7 +229,7 @@
<itemizedlist>
<listitem>
- <para>for the Google-like feature 1-10 of about 888,000,000
</para>
+ <para>for the Google-like feature 1-10 of about 888,000,000</para>
</listitem>
<listitem>
@@ -246,7 +248,7 @@
<para>Hibernate Search allows you to retrieve the total number of
matching documents regardless of the pagination parameters. Even more
interesting, you can retrieve the number of matching elements without
- even triggering a single object load.</para>
+ triggering a single object load.</para>
<programlisting>org.hibernate.search.FullTextQuery query =
s.createFullTextQuery( luceneQuery, Book.class );
assert 3245 == <emphasis
role="bold">query.getResultSize()</emphasis>; //return the number of
matching books without loading a single one
@@ -256,7 +258,11 @@
List results = query.list();
assert 3245 == <emphasis
role="bold">query.getResultSize()</emphasis>; //return the total number
of matching books regardless of pagination</programlisting>
- <para></para>
+ <note>
+ <para>Like Google, the number of results is approximative if the index
+ is not fully up-to-date with the database (asynchronous cluster for
+ example).</para>
+ </note>
</section>
</section>