Author: epbernard
Date: 2008-07-16 23:39:44 -0400 (Wed, 16 Jul 2008)
New Revision: 14944
Modified:
search/trunk/doc/reference/en/master.xml
search/trunk/doc/reference/en/modules/batchindex.xml
search/trunk/doc/reference/en/modules/configuration.xml
search/trunk/doc/reference/en/modules/getting-started.xml
search/trunk/doc/reference/en/modules/lucene-native.xml
search/trunk/doc/reference/en/modules/mapping.xml
search/trunk/doc/reference/en/modules/optimize.xml
search/trunk/doc/reference/en/modules/query.xml
Log:
Catch up on doc for HSearch 3.1.0.Beta1
Modified: search/trunk/doc/reference/en/master.xml
===================================================================
--- search/trunk/doc/reference/en/master.xml 2008-07-17 02:29:47 UTC (rev 14943)
+++ search/trunk/doc/reference/en/master.xml 2008-07-17 03:39:44 UTC (rev 14944)
@@(protected) @@
<subtitle>Reference Guide</subtitle>
- <releaseinfo>3.0.1.GA</releaseinfo>
+ <releaseinfo>3.1.0.Beta1</releaseinfo>
<mediaobject>
<imageobject>
Modified: search/trunk/doc/reference/en/modules/batchindex.xml
===================================================================
--- search/trunk/doc/reference/en/modules/batchindex.xml 2008-07-17 02:29:47 UTC (rev 14943)
+++ search/trunk/doc/reference/en/modules/batchindex.xml 2008-07-17 03:39:44 UTC (rev 14944)
@@(protected) @@
<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="search-batchindex">
+ <!-- $Id$ -->
-<chapter id="search-batchindex">
- <!-- $Id$ -->
<title>Manual indexing</title>
<section id="search-batchindex-indexing">
@@(protected) @@
want to build your index for the first time. You can achieve that goal
using the <classname>FullTextSession</classname>.</para>
- <programlisting>FullTextSession fullTextSession = Search.createFullTextSession(session);
+ <programlisting>FullTextSession fullTextSession = Search.getFullTextSession(session);
Transaction tx = fullTextSession.beginTransaction();
for (Customer customer : customers) {
<emphasis role="bold">fullTextSession.index(customer);</emphasis>
@@(protected) @@
tx.commit(); //index are written at commit time </programlisting>
<para>For maximum efficiency, Hibernate Search batches index operations
- and executse them at commit time (Note: you don't need to use
+ and executes them at commit time (Note: you don't need to use
<classname>
org.hibernate.Transaction</classname> in a JTA
environment).</para>
@@(protected) @@
transaction commit, you can potentially face an
<classname>OutOfMemoryException</classname>.</para>
- <para>To avoid that, you can set up the
- <literal>hibernate.search.worker.batch_size</literal> property to a
- sensitive value: all index operations are queued until
- <literal>batch_size</literal> is reached. Every time
- <literal>batch_size</literal> is reached (or if the transaction is
- committed), the queue is processed (freeing memory) and emptied. Be aware
- that the changes cannot be rollbacked if the number of index elements goes
- beyond <literal>batch_size</literal>. Be also aware that the queue limits
- are also applied on regular transparent indexing (and not only when
- <literal>session.index()</literal> is used). That's why a sensitive
- <literal>batch_size</literal> value is expected.</para>
+ <para>To avoid that, you can use
+ <methodname>fullTextSession.flushToIndexes()</methodname>: all index
+ operations are queued until
+ <methodname>fullTextSession.flushToIndexes()</methodname> is called. Every
+ time <methodname>fullTextSession.flushToIndexes()</methodname> is called
+ (or if the transaction is committed), the queue is processed (freeing
+ memory) and emptied. Be aware that changes made before a flush cannot be
+ rollbacked. </para>
+ <note>
+ <para><literal>hibernate.search.worker.batch_size</literal> has been
+ deprecated in favor of this explicit API which provides better
+ control</para>
+ </note>
+
<para>Other parameters which also can affect indexing time and memory
consumption are
<literal>hibernate.search.[default|<indexname>].indexwriter.batch.max_buffered_docs</literal>
@@(protected) @@
and
<literal>hibernate.search.[default|<indexname>].indexwriter.batch.term_index_interval</literal>
. These parameters are Lucene specific and Hibernate Search is just
- passing these paramters through - see <xref
+ passing these parameters through - see <xref
linkend="lucene-indexing-performance" /> for more details.</para>
<para>Here is an especially efficient way to index a given class (useful
@@(protected) @@
fullTextSession.setCacheMode(CacheMode.IGNORE);
transaction = fullTextSession.beginTransaction();
//Scrollable results will avoid loading too many objects in memory
-ScrollableResults results = fullTextSession.createCriteria( Email.class ).scroll( ScrollMode.FORWARD_ONLY );
+ScrollableResults results = fullTextSession.createCriteria( Email.class )
+ .setFetchSize(BATCH_SIZE)
+ .scroll( ScrollMode.FORWARD_ONLY );
int index = 0;
while( results.next() ) {
index++;
fullTextSession.index( results.get(0) ); //index each element
- if (index % batchSize == 0) s.clear(); //clear every batchSize since the queue is processed
+ if (index % BATCH_SIZE == 0) {
+ fullTextSession.flushToIndexes(); //apply changes to indexes
+ fullTextSession.clear(); //clear since the queue is processed
+ }
}
transaction.commit();</programlisting>
- <para>It is critical that <literal>batchSize</literal> in the previous
- example matches the <literal>batch_size</literal> value described
- previously.</para>
+ <para>Try to use a batch size that guaranty that your application will not
+ run out of memory.</para>
</section>
<section>
@@(protected) @@
from the database. This operation is named purging and is done through the
<classname>FullTextSession</classname>.</para>
- <programlisting>FullTextSession fullTextSession = Search.createFullTextSession(session);
+ <programlisting>FullTextSession fullTextSession = Search.getFullTextSession(session);
Transaction tx = fullTextSession.beginTransaction();
for (Customer customer : customers) {
<emphasis role="bold">fullTextSession.purge( Customer.class, customer.getId() );</emphasis>
@@(protected) @@
<para>If you need to remove all entities of a given type, you can use the
<methodname>purgeAll</methodname> method.</para>
- <programlisting>FullTextSession fullTextSession = Search.createFullTextSession(session);
+ <programlisting>FullTextSession fullTextSession = Search.getFullTextSession(session);
Transaction tx = fullTextSession.beginTransaction();
<emphasis role="bold">fullTextSession.purgeAll( Customer.class );</emphasis>
//optionally optimize the index
@@(protected) @@
<note>
<para>Methods <methodname>index</methodname>,
<methodname>purge</methodname> and <methodname>purgeAll</methodname> are
- available on <classname>FullTextEntityManager</classname> as well.</para>
+ available on <classname>FullTextEntityManager</classname> as
+ well.</para>
</note>
</section>
-</chapter>
+</chapter>
\ No newline at end of file
Modified: search/trunk/doc/reference/en/modules/configuration.xml
===================================================================
--- search/trunk/doc/reference/en/modules/configuration.xml 2008-07-17 02:29:47 UTC (rev 14943)
+++ search/trunk/doc/reference/en/modules/configuration.xml 2008-07-17 03:39:44 UTC (rev 14944)
@@(protected) @@
lookup the JMS queue from. The queue will be used to post work
messages.</entry>
</row>
-
- <row>
- <entry><literal>hibernate.search.worker.batch_size</literal></entry>
-
- <entry>Defines the maximum number of elements indexed before
- flushing the transaction-bound queue. Default to 0 (ie no limit).
- See <xref linkend="search-batchindex" /> for more
- information.</entry>
- </row>
</tbody>
</tgroup>
</table>
@@(protected) @@
Note that there is no performance runtime when the listeners are enabled
while no entity is indexable.</para>
- <para>To enable Hibernate Search in Hibernate Core, add the
- <literal>FullTextIndexEventListener</literal> for the three Hibernate
+ <para>To enable Hibernate Search in Hibernate Core (ie. if you don't use
+ Hibernate Annotations), add the
+ <literal>FullTextIndexEventListener</literal> for the six Hibernate
events that occur after changes are executed to the database. Once
again, such a configuration is not useful with Hibernate Annotations or
Hibernate EntityManager.</para>
@@(protected) @@
<event type="post-delete"/>
<listener class="
org.hibernate.search.event.FullTextIndexEventListener"/>
</event>
+ <event type="post-collection-recreate"/>
+ <listener class="
org.hibernate.search.event.FullTextIndexEventListener"/>
+ </event>
+ <event type="post-collection-remove"/>
+ <listener class="
org.hibernate.search.event.FullTextIndexEventListener"/>
+ </event>
+ <event type="post-collection-update"/>
+ <listener class="
org.hibernate.search.event.FullTextIndexEventListener"/>
+ </event>
</session-factory>
</hibernate-configuration></programlisting>
@@(protected) @@
<para><filename>lucene-core-*.jar</filename>: Lucene core
engine</para>
</listitem>
- </itemizedlist>
- <section>
- <title>Hibernate Core 3.2.6 and beyond</title>
-
- <para>If you use Hibernate Core 3.2.6 and beyond, make sure to add
- three additional event listeners that cope with collection
- events</para>
-
- <programlisting><hibernate-configuration>
- <session-factory>
- ...
- <event type="post-collection-recreate"/>
- <listener class="
org.hibernate.search.event.FullTextIndexCollectionEventListener"/>
- </event>
- <event type="post-collection-remove"/>
- <listener class="
org.hibernate.search.event.FullTextIndexCollectionEventListener"/>
- </event>
- <event type="post-collection-update"/>
- <listener class="
org.hibernate.search.event.FullTextIndexCollectionEventListener"/>
- </event>
- </session-factory>
-</hibernate-configuration></programlisting>
-
- <para>Those additional event listeners have been introduced in
- Hibernate 3.2.6. note the
- <classname>FullTextIndexCollectionEventListener</classname> usage. You
- need to explicitly reference those event listeners unless you use
- Hibernate Annotations 3.3.1 and above.</para>
- </section>
+ <listitem>
+ <para><filename>apache-solr-analyzer.jar</filename>: Additional
+ analyzer infrastructure</para>
+ </listitem>
+ </itemizedlist>
</section>
<section>
@@(protected) @@
<literal>.batch</literal> value in a specific shard configuration,
Hibernate Search will look at the index section, then at the default
section and after that it will look for a <literal>.transaction</literal>
- in the same order: <programlisting>
- hibernate.search.Animals.2.indexwriter.transaction.max_merge_docs 10
- hibernate.search.Animals.2.indexwriter.transaction.merge_factor 20
- hibernate.search.default.indexwriter.batch.max_merge_docs 100</programlisting>
+ in the same order: <programlisting>hibernate.search.Animals.2.indexwriter.transaction.max_merge_docs 10
+hibernate.search.Animals.2.indexwriter.transaction.merge_factor 20
+hibernate.search.default.indexwriter.batch.max_merge_docs 100</programlisting>
This configuration will result in these settings applied to the second
shard of Animals index: <itemizedlist>
<listitem>
Modified: search/trunk/doc/reference/en/modules/getting-started.xml
===================================================================
--- search/trunk/doc/reference/en/modules/getting-started.xml 2008-07-17 02:29:47 UTC (rev 14943)
+++ search/trunk/doc/reference/en/modules/getting-started.xml 2008-07-17 03:39:44 UTC (rev 14944)
@@(protected) @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="getting-started">
- <!-- $Id$ -->
+ <!-- $Id$ -->
+
<title>Getting started</title>
<para>Welcome to Hibernate Search! The following chapter will guide you
@@(protected) @@
<row>
<entry>Hibernate Core</entry>
- <entry>This instructions have been tested against Hibernate 3.2.x.
+ <entry>This instructions have been tested against Hibernate 3.3.x.
Next to the main <literal>hibernate3.jar</literal> you will need
all required libaries from the <literal>lib</literal> directory of
the distribution. Refer to <literal>README.txt</literal> in the
- <literal>lib</literal> directory of the distibution to determine
+ <literal>lib</literal> directory of the distribution to determine
the minimum runtime requirements.</entry>
</row>
@@(protected) @@
has its own set of annotations (<emphasis>@(protected),
@Field,...</emphasis>) for which there exists so far no
alternative configuration. The tutorial is tested against version
- 3.3.x of Hibernate Annotations. </entry>
+ 3.4.x of Hibernate Annotations.</entry>
</row>
</tbody>
</tgroup>
@@(protected) @@
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-search</artifactId>
- <version>3.0.1.GA</version>
+ <version>3.1.0.Beta1</version>
</dependency>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-annotations</artifactId>
- <version>3.3.0.ga</version>
+ <version>3.4.0.CR1</version>
</dependency>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-entitymanager</artifactId>
- <version>3.3.1.ga</version>
+ <version>3.4.0.CR1</version>
</dependency>
</programlisting>
@@(protected) @@
<para>Example using Hibernate Session:</para>
<programlisting>
-FullTextSession fullTextSession = Search.createFullTextSession(session);
+FullTextSession fullTextSession = Search.getFullTextSession(session);
Transaction tx = fullTextSession.beginTransaction();
List books = session.createQuery("from Book as book").list();
for (Book book : books) {
@@(protected) @@
<programlisting>
EntityManager em = entityManagerFactory.createEntityManager();
-FullTextEntityManager fullTextEntityManager = Search.createFullTextEntityManager(em);
+FullTextEntityManager fullTextEntityManager = Search.getFullTextEntityManager(em);
List books = em.createQuery("select book from Book as book").getResultList();
for (Book book : books) {
fullTextEntityManager.index(book);
@@(protected) @@
<para>Example using Hibernate Session:</para>
<programlisting>
-FullTextSession fullTextSession = Search.createFullTextSession(session);
+FullTextSession fullTextSession = Search.getFullTextSession(session);
Transaction tx = fullTextSession.beginTransaction();
@@(protected) @@
EntityManager em = entityManagerFactory.createEntityManager();
FullTextEntityManager fullTextEntityManager =
- org.hibernate.hibernate.search.jpa.Search.createFullTextEntityManager(em);
+ org.hibernate.hibernate.search.jpa.Search.getFullTextEntityManager(em);
MultiFieldQueryParser parser = new MultiFieldQueryParser( new String[]{"summary", "body"},
new StandardAnalyzer());
Query query = parser.parse( "Java rocks!" );
Modified: search/trunk/doc/reference/en/modules/lucene-native.xml
===================================================================
--- search/trunk/doc/reference/en/modules/lucene-native.xml 2008-07-17 02:29:47 UTC (rev 14943)
+++ search/trunk/doc/reference/en/modules/lucene-native.xml 2008-07-17 03:39:44 UTC (rev 14944)
@@(protected) @@
<?xml version="1.0" encoding="UTF-8"?>
-
<chapter id="search-lucene-native">
<!-- $Id$ -->
+
<title>Accessing Lucene natively</title>
<section>
@@(protected) @@
way to access Lucene natively. The <classname>SearchFactory</classname>
can be accessed from a <classname>FullTextSession</classname>:</para>
- <programlisting>FullTextSession fullTextSession = Search.createFullTextSession(regularSession);
+ <programlisting>FullTextSession fullTextSession = Search.getFullTextSession(regularSession);
SearchFactory searchFactory = fullTextSession.getSearchFactory();</programlisting>
</section>
Modified: search/trunk/doc/reference/en/modules/mapping.xml
===================================================================
--- search/trunk/doc/reference/en/modules/mapping.xml 2008-07-17 02:29:47 UTC (rev 14943)
+++ search/trunk/doc/reference/en/modules/mapping.xml 2008-07-17 03:39:44 UTC (rev 14944)
@@(protected) @@
thumb rule, the same analyzer should be used for both the indexing and
the query for a given field.</para>
</caution>
+
+ <para>analyzer searchFactory.getanalyzer()</para>
</section>
</section>
@@(protected) @@
</warning>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>
java.net.URI,
java.net.URL</term>
+
+ <listitem>
+ <para>URI and URL are converted to their string
+ representation</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
java.lang.Class</term>
+
+ <listitem>
+ <para>Class are converted to their filly qualified class name. The
+ thread context classloader is used when the class is
+ rehydrated</para>
+ </listitem>
+ </varlistentry>
</variablelist>
-
- <para></para>
</section>
<section>
@@(protected) @@
//property
<emphasis role="bold">@(protected)>
private Date date; </programlisting>
-
- <para></para>
</section>
<section>
Modified: search/trunk/doc/reference/en/modules/optimize.xml
===================================================================
--- search/trunk/doc/reference/en/modules/optimize.xml 2008-07-17 02:29:47 UTC (rev 14943)
+++ search/trunk/doc/reference/en/modules/optimize.xml 2008-07-17 03:39:44 UTC (rev 14944)
@@(protected) @@
<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="search-optimize">
+ <!-- $Id$ -->
-<chapter id="search-optimize">
- <!-- $Id$ -->
<title>Index Optimization</title>
<para>From time to time, the Lucene index needs to be optimized. The process
@@(protected) @@
<programlisting>searchFactory.optimize(Order.class);</programlisting>
- <programlisting>searchFactory.optimize();</programlisting>
+ <programlisting>searchFactory.optimize();</programlisting>
<para>The first example optimizes the Lucene index holding
<classname>Order</classname>s; the second, optimizes all indexes.</para>
@@(protected) @@
<para>The <classname>SearchFactory</classname> can be accessed from a
<classname>FullTextSession</classname>:</para>
- <programlisting>FullTextSession fullTextSession = Search.createFullTextSession(regularSession);
+ <programlisting>FullTextSession fullTextSession = Search.getFullTextSession(regularSession);
SearchFactory searchFactory = fullTextSession.getSearchFactory();</programlisting>
<para>Note that <literal>searchFactory.optimize()</literal> has no effect
@@(protected) @@
<para>Apache Lucene has a few parameters to influence how optimization is
performed. Hibernate Search exposes those parameters.</para>
- <para>Further index optimisation parameters include:
- <itemizedlist>
- <listitem><literal>hibernate.search.[default|<indexname>].indexwriter.[batch|transaction].max_buffered_docs</literal></listitem>
- <listitem><literal>hibernate.search.[default|<indexname>].indexwriter.[batch|transaction].max_field_length</literal></listitem>
- <listitem><literal>hibernate.search.[default|<indexname>].indexwriter.[batch|transaction].max_merge_docs</literal></listitem>
- <listitem><literal>hibernate.search.[default|<indexname>].indexwriter.[batch|transaction].merge_factor</literal></listitem>
- <listitem><literal>hibernate.search.[default|<indexname>].indexwriter.[batch|transaction].ram_buffer_size</literal></listitem>
- <listitem><literal>hibernate.search.[default|<indexname>].indexwriter.[batch|transaction].term_index_interval</literal></listitem>
- </itemizedlist>
- See <xref linkend="lucene-indexing-performance" /> for more details.</para>
+ <para>Further index optimisation parameters include: <itemizedlist>
+ <listitem>
+ <literal>hibernate.search.[default|<indexname>].indexwriter.[batch|transaction].max_buffered_docs</literal>
+ </listitem>
+
+ <listitem>
+ <literal>hibernate.search.[default|<indexname>].indexwriter.[batch|transaction].max_field_length</literal>
+ </listitem>
+
+ <listitem>
+ <literal>hibernate.search.[default|<indexname>].indexwriter.[batch|transaction].max_merge_docs</literal>
+ </listitem>
+
+ <listitem>
+ <literal>hibernate.search.[default|<indexname>].indexwriter.[batch|transaction].merge_factor</literal>
+ </listitem>
+
+ <listitem>
+ <literal>hibernate.search.[default|<indexname>].indexwriter.[batch|transaction].ram_buffer_size</literal>
+ </listitem>
+
+ <listitem>
+ <literal>hibernate.search.[default|<indexname>].indexwriter.[batch|transaction].term_index_interval</literal>
+ </listitem>
+ </itemizedlist> See <xref linkend="lucene-indexing-performance" /> for
+ more details.</para>
</section>
-</chapter>
+</chapter>
\ No newline at end of file
Modified: search/trunk/doc/reference/en/modules/query.xml
===================================================================
--- search/trunk/doc/reference/en/modules/query.xml 2008-07-17 02:29:47 UTC (rev 14943)
+++ search/trunk/doc/reference/en/modules/query.xml 2008-07-17 03:39:44 UTC (rev 14944)
@@(protected) @@
<programlisting>Session session = sessionFactory.openSession();
...
-FullTextSession fullTextSession = Search.createFullTextSession(session); </programlisting>
+FullTextSession fullTextSession = Search.getFullTextSession(session); </programlisting>
<para>The search facility is built on native Lucene queries.</para>
@@(protected) @@
<programlisting>EntityManager em = entityManagerFactory.createEntityManager();
FullTextEntityManager fullTextEntityManager =
- org.hibernate.hibernate.search.jpa.Search.createFullTextEntityManager(em);
+ org.hibernate.hibernate.search.jpa.Search.getFullTextEntityManager(em);
...
org.apache.lucene.queryParser.QueryParser parser = new QueryParser("title", new StopAnalyzer() );
@@(protected) @@
<para>This subject is generally speaking out of the scope of this
documentation. Please refer to the Lucene documentation or Lucene In
Action.</para>
+
+ <para>It is quite useful to use the same analyzer when indexing a field
+ and when querying that field. Hibernate Search let's you access analyzer
+ instances that have been defined through an analyzer definition (see
+ <xref linkend="analyzer" /> for more information).</para>
+
+ <programlisting>analyzer analyzer = fullTextSession.getSearchFactory().getAnalyzer("phonetic-analyzer");</programlisting>
</section>
<section>
@@(protected) @@
<para>Once the Lucene query is built, it needs to be wrapped into an
Hibernate Query.</para>
- <programlisting>FullTextSession fullTextSession = Search.createFullTextSession( session );
+ <programlisting>FullTextSession fullTextSession = Search.getFullTextSession( session );
org.hibernate.Query fullTextQuery = fullTextSession.createFullTextQuery( luceneQuery );</programlisting>
<para>If not specified otherwise, the query will be executed against
@@(protected) @@
<para>Be careful, building the explanation object is quite expensive, it
is roughly as expensive as running the Lucene query again. Don't do it
- if you don't need the object and don't do it on too many results.</para>
+ if you don't need the object</para>
</section>
</section>
_______________________________________________
hibernate-commits mailing list
hibernate-commits@(protected)
https://lists.jboss.org/mailman/listinfo/hibernate-commits
