[hibernate-commits] Hibernate SVN: r11639 - trunk/HibernateExt/search/doc/reference/en/modules.

[hibernate-commits at lists.jboss.org]

Author: epbernard
Date: 2007-06-05 20:45:49 -0400 (Tue, 05 Jun 2007)
New Revision: 11639

Added:
   trunk/HibernateExt/search/doc/reference/en/modules/lucene-native.xml
   trunk/HibernateExt/search/doc/reference/en/modules/optimize.xml
Log:
some more doc

Added: trunk/HibernateExt/search/doc/reference/en/modules/lucene-native.xml
===================================================================
--- trunk/HibernateExt/search/doc/reference/en/modules/lucene-native.xml	                        (rev 0)
+++ trunk/HibernateExt/search/doc/reference/en/modules/lucene-native.xml	2007-06-06 00:45:49 UTC (rev 11639)
@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="search-lucene-native">
+  <title>Accessing Lucene natively</title>
+
+  <section>
+    <title>SearchFactory</title>
+
+    <para>The <classname>SearchFactory</classname> object keeps track of the
+    underlying Lucene resources for Hibernate Search, it's also a convenient
+    way to access Lucene natively. The <classname>SearchFactory</classname>
+    can be accessed from a <classname>FullTextSession</classname>:</para>
+
+    <programlisting>FullTextSession fullTextSession = Search.createFullTextSession(regularSession);
+SearchFactory searchFactory = fullTextSession.getSearchFactory();</programlisting>
+  </section>
+
+  <section>
+    <title>Accessing a Lucene Directory</title>
+
+    <para>You can always access the Lucene directories through plain Lucene,
+    the Directory structure is in no way different with or without Hibernate
+    Search. However there are some more convenient ways to access a given
+    Directory. The <classname>SearchFactory</classname> keeps track of a
+    <classname>DirectoryProvider</classname> per indexed class (one directory
+    provider can be shared amongst several indexed classes if the classes
+    share the same underlying index directory).</para>
+
+    <programlisting>DirectoryProvider provider = searchFactory.getDirectoryProvider(Order.class);
+org.apache.lucene.store.Directory directory = provider.getDirectory();</programlisting>
+
+    <para>In this example, directory points to the lucene index storing
+    <classname>Order</classname>s information. Note that the obtained Lucene
+    directory must not be closed (this is Hibernate Search
+    responsibility).</para>
+  </section>
+
+  <section>
+    <title>Using an IndexReader</title>
+
+    <para>Queries in Lucene are executed on an <literal>IndexReader</literal>.
+    Hibernate Search caches such index readers to maximize performances. Your
+    code can access such cached / shared resources. You will just have to
+    follow some "good citizen" rules.</para>
+
+    <programlisting>DirectoryProvider orderProvider = searchFactory.getDirectoryProvider(Order.class);
+DirectoryProvider clientProvider = searchFactory.getDirectoryProvider(Client.class);
+
+ReaderProvider readerProvider = searchFactory.getReaderProvider();
+IndexReader reader = readerProvider.openReader(orderProvider, clientProvider);
+
+try {
+    //do read-only operations on the reader
+}
+finally {
+    readerProvider.closeReader(reader);
+}</programlisting>
+
+    <para>The ReaderProvider (described in <xref
+    linkend="search-architecture-readerstrategy" />), will open an IndexReader
+    on top of the index(es) referenced by the directory providers. This
+    IndexReader being shared amongst several clients, you must adhere to the
+    following rules:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Never call indexReader.close(), but always call
+        readerProvider.closeReader(reader); (a finally block is the best
+        area).</para>
+      </listitem>
+
+      <listitem>
+        <para>This indexReader must not be used for modification operations
+        (especially delete), if you want to use an read/write index reader,
+        open one from the Lucene Directory object.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Aside from those rules, you can use the IndexReader freely,
+    especially to do native queries. Using the shared
+    <literal>IndexReader</literal>s will make most queries more
+    efficient.</para>
+  </section>
+</chapter>
\ No newline at end of file

Added: trunk/HibernateExt/search/doc/reference/en/modules/optimize.xml
===================================================================
--- trunk/HibernateExt/search/doc/reference/en/modules/optimize.xml	                        (rev 0)
+++ trunk/HibernateExt/search/doc/reference/en/modules/optimize.xml	2007-06-06 00:45:49 UTC (rev 11639)
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="search-optimize">
+  <title>Index Optimization</title>
+
+  <para>From time to time, the Lucene index needs to be optimize. The process
+  is essentially a defragmentation: until the optimization occurs, deleted
+  documents are just marked as such, no physical deletion is applied, the
+  optimization can also adjust the number of files in the Lucene
+  Directory.</para>
+
+  <para>You can programmatically optimize (defragment) a Lucene index from
+  Hibernate Search through the <classname>SearchFactory</classname></para>
+
+  <programlisting>searchFactory.optimize(Order.class);
+
+searchFactory.optimize();
+</programlisting>
+
+  <para>The first example reindex the Lucene index holding
+  <classname>Order</classname>s, the second, optimize all indexes.</para>
+
+  <para>The optimization speeds up searches but in no way speeds up indexation
+  (update). During an optimization, searches can be performed (but will most
+  likely be slowed down), and all index updates will be stopped. Prefer
+  optimizing:</para>
+
+  <itemizedlist>
+    <listitem>
+      <para>on an idle system or when the searches are less frequent</para>
+    </listitem>
+
+    <listitem>
+      <para>after a lot of index modifications (doing so before will not speed
+      up the indexation process)</para>
+    </listitem>
+  </itemizedlist>
+
+  <para>The <classname>SearchFactory</classname> can be accessed from a
+  <classname>FullTextSession</classname>:</para>
+
+  <programlisting>FullTextSession fullTextSession = Search.createFullTextSession(regularSession);
+SearchFactory searchFactory = fullTextSession.getSearchFactory();</programlisting>
+
+  <para>Note that <literal>searchFactory.optimize()</literal> has no effect on
+  a JMS backend. You must apply the optimize operation on the Master
+  node.</para>
+
+  <para></para>
+</chapter>
\ No newline at end of file