Author: hardy.ferentschik Date: 2007-08-12 09:55:13 -0400 (Sun, 12 Aug 2007) New Revision: 12924 Modified: trunk/HibernateExt/search/doc/reference/en/master.xml trunk/HibernateExt/search/doc/reference/en/modules/architecture.xml trunk/HibernateExt/search/doc/reference/en/modules/batchindex.xml trunk/HibernateExt/search/doc/reference/en/modules/configuration.xml trunk/HibernateExt/search/doc/reference/en/modules/getting-started.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/master.xml =================================================================== --- trunk/HibernateExt/search/doc/reference/en/master.xml 2007-08-11 06:48:08 UTC (rev 12923) +++ trunk/HibernateExt/search/doc/reference/en/master.xml 2007-08-12 13:55:13 UTC (rev 12924) @@ -35,15 +35,16 @@ <para>Full text search engines like <productname>Apache Lucene</productname> are very powerful technologies to add efficient free - text queries to applications. However, they suffer several mismatches when - dealing with object domain models, eg indeces have to be kept up to date, + text search capabilities to applications. However, they suffer several mismatches when + 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 the database/index synchronization and brings you back + takes care of database/index synchronization and brings you back regular managed objects from free text queries. To achieve this Hibernate Search - is using <ulink url="http://lucene.apache.org">Apache Lucene</ulink> under the - cover.</para> + is combining the power of <ulink url="http://www.hibernate.org">Hibernate</ulink> and + <ulink url="http://lucene.apache.org">Apache Lucene</ulink>. + </para> <important>Hibernate Search is a work in progress and new features are cooking in this area. So expect some compatibility changes in subsequent Modified: trunk/HibernateExt/search/doc/reference/en/modules/architecture.xml =================================================================== --- trunk/HibernateExt/search/doc/reference/en/modules/architecture.xml 2007-08-11 06:48:08 UTC (rev 12923) +++ trunk/HibernateExt/search/doc/reference/en/modules/architecture.xml 2007-08-12 13:55:13 UTC (rev 12924) @@ -2,13 +2,15 @@ <!-- $Id$ --> <chapter id="search-architecture"> <title>Architecture</title> - - <para>Hibernate Search is consists of an indexing engine and an index search + <section> + <title>Overview</title> + + <para>Hibernate Search consists of an indexing and an index search engine. Both are backed by Apache Lucene.</para> - <para>When an entity is inserted, updated or removed to/from the database, + <para>When an entity is inserted, updated or removed in the database, Hibernate Search keeps track of this event (through the Hibernate event - system) and schedule an index update. All the index updates are handled for + system) and schedules an index update. All the index updates are handled for you without you having to use the Apache Lucene APIs (see <xref linkend="search-configuration-event"/>). </para> @@ -28,54 +30,51 @@ or <classname>javax.persistence.Query</classname> APIs exactly the way a HQL, JPA-QL or native queries would do.</para> - <section> - <title>Batching Scope</title> + <para>To be more efficient, Hibernate Search batches the write interactions + with the Lucene index. There is currently two types of batching depending + on the expected scope.</para> - <para>To be more efficient, Hibernate Search batch the write interactions - with the Lucene index. There is currently two types of batching depending - on the expected scope.</para> + <para>Outside an transaction, the index update operation is executed + right after the actual database operation. This scope is really a no + scoping, and no batching is performed.</para> - <para>When out of transaction, the index update operation is executed - right after the actual database operation. This scope is really a no - scoping, and no batching is performed.</para> + <para>It is however recommended, for both your database and Hibernate + Search, to execute your operation in a transaction be it JDBC or + JTA. When in a transaction, the index update operation is scheduled for + the transaction commit (and discarded in case of transaction rollback). + The batching scope is the transaction. There are two immediate + benefits:</para> - <para>It is however recommended, for both your database and Hibernate - Search, to execute your operation in a transaction (whether it be JDBC or - JTA). When in a transaction, the index update operation is schedule for - the transaction commit (and discarded in case of transaction rollback). - The batching scope is the transaction. There is 2 immediate - benefits:</para> + <itemizedlist> + <listitem> + <para>Performance: Lucene indexing works better when operation are + executed in batch.</para> + </listitem> - <itemizedlist> - <listitem> - <para>performance: Lucene indexing works better when operation are - executed in batch.</para> - </listitem> + <listitem> + <para>ACIDity: The work executed has the same scoping as the one + executed by the database transaction and is executed if and only if + the transaction is committed.</para> - <listitem> - <para>ACIDity: The work executed has the same scoping as the one - executed by the database transaction and is executed if and only if - the transaction is committed.</para> + <note> + <para>Disclaimer, the work in not ACID in the strict sense of it, + but ACID behavior is rarely useful for full text search indexes + since they can be rebuilt from the source at any time.</para> + </note> + </listitem> + </itemizedlist> - <note> - <para>Disclaimer, the work in not ACID in the strict sense of it, - but ACID behavior is rarely useful for full text search indexes - since they can be rebuilt from the source at any time.</para> - </note> - </listitem> - </itemizedlist> + <para>You can think of those two scopes (no scope vs transactional) as the + equivalent of the (infamous) autocommit vs transactional behavior. From a + performance perspective, the <emphasis>in transaction</emphasis> mode is + recommended. The scoping choice is made transparently: Hibernate Search + detects the presence of a transaction and adjust the scoping.</para> - <para>You can think of those two scopes (no scope vs transactional) as the - equivalent of the (infamous) autocommit vs transactional behavior. From a - performance perspective, the <emphasis>in transaction</emphasis> mode is - recommended. The scoping choice is made transparently: Hibernate Search - detects the presence of a transaction and adjust the scoping.</para> + <note>Hibernate Search works perfectly fine in the Hibernate / + EntityManager long conversation pattern aka. atomic conversation.</note> - <remark>Note that Hibernate Search works perfectly fine in the Hibernate / - EntityManager long conversation pattern aka. atomic conversation.</remark> - - <para>Depending on user demand, additional scoping will be considered, the - pluggability mechanism being already in place.</para> + <note>Depending on user demand, additional scoping will be considered, the + pluggability mechanism being already in place.</note> </section> <section> @@ -83,7 +82,7 @@ <para>Hibernate Search offers the ability to let the scoped work being processed by different back ends. Two back ends are provided out of the - box for 2 different scenarios.</para> + box for two different scenarios.</para> <section> <title>Lucene</title> @@ -91,7 +90,7 @@ <para>In this mode, all index update operations applied on a given node (JVM) will be executed to the Lucene directories (through the directory providers) by the same node. This mode is typically used in non - clustered mode or in clustered mode where the directory store is + clustered environment or in clustered environments where the directory store is shared.</para> <mediaobject> @@ -122,10 +121,10 @@ JMS queue. A unique reader will then process the queue and update the master Lucene index. The master index is then replicated on a regular basis to the slave copies. This is known as the master / slaves pattern. - The master is the sole responsible for updating the Lucene index, the - slaves can accept read/write operations, process the read operation on - their local index copy, and delegate the update operations to the - master.</para> + The master is the sole responsible for updating the Lucene index. The + slaves can accept read as well as write operations. However, they only + process the read operation on their local index copy and delegate the update + operations to the master.</para> <mediaobject> <imageobject role="html"> @@ -145,14 +144,10 @@ the index.</para> </section> - <section> - <title>Custom</title> - - <para>Hibernate Search is an extensible architecture. While not yet part - of the public API, plugging a third party back end is possible. Feel - free to drop ideas to - <literal&gt;hibernate-dev(a)lists.jboss.org&lt;/literal&gt;.&lt;/para&gt; - </section> + <note>Hibernate Search is an extensible architecture. While not yet part + of the public API, plugging a third party back end is possible. Feel + free to drop ideas to + <literal&gt;hibernate-dev(a)lists.jboss.org&lt;/literal&gt;.&lt;/note&gt; </section> <section> @@ -195,19 +190,11 @@ <para>When executing a query, Hibernate Search interacts with the Apache Lucene indexes through a reader strategy. chosing a reader strategy will depend on the profile of the application (frequent updates, read mostly, - asynchronous index update etc).</para> + asynchronous index update etc). See also <xref linkend="configuration-reader-strategy"/></para> <section> - <title>not-shared</title> + <title>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 - IndexReader can be a relatively expensive operation.</para> - </section> - - <section> - <title>shared</title> - <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 @@ -219,8 +206,16 @@ </section> <section> - <title>custom</title> + <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 + IndexReader can be a relatively expensive operation.</para> + </section> + + <section> + <title>Custom</title> + <para>You can write your own reader strategy that suits your application needs by implementing <classname>org.hibernate.search.reader.ReaderProvider</classname>. The Modified: trunk/HibernateExt/search/doc/reference/en/modules/batchindex.xml =================================================================== --- trunk/HibernateExt/search/doc/reference/en/modules/batchindex.xml 2007-08-11 06:48:08 UTC (rev 12923) +++ trunk/HibernateExt/search/doc/reference/en/modules/batchindex.xml 2007-08-12 13:55:13 UTC (rev 12924) @@ -32,7 +32,7 @@ <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 is + 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> Modified: trunk/HibernateExt/search/doc/reference/en/modules/configuration.xml =================================================================== --- trunk/HibernateExt/search/doc/reference/en/modules/configuration.xml 2007-08-11 06:48:08 UTC (rev 12923) +++ trunk/HibernateExt/search/doc/reference/en/modules/configuration.xml 2007-08-12 13:55:13 UTC (rev 12924) @@ -6,10 +6,10 @@ <section id="search-configuration-directory" revision="1"> <title>Directory configuration</title> - <para>Apache Lucene has a notion of Directory to store the index files. + <para>Apache Lucene has a notion of <literal>Directory</literal> to store the index files. The Directory implementation can be customized, but Lucene comes bundled - with a file system (<literal>FSDirectoryProvider</literal>) and a full - memory (RAMDirectoryProvider) implementation. Hibernate Search has the + with a file system (<literal>FSDirectoryProvider</literal>) and a in + memory (<literal>RAMDirectoryProvider</literal>) implementation. Hibernate Search has the notion of <literal>DirectoryProvider</literal> that handles the configuration and the initialization of the Lucene Directory.</para> @@ -44,7 +44,7 @@ <entry>org.hibernate.search.store.FSMasterDirectoryProvider</entry> <entry><para>File system based directory. Like - FSDirectoryProvider. It also copy the index to a source directory + FSDirectoryProvider. It also copies the index to a source directory (aka copy directory) on a regular basis. </para><para>The recommended value for the refresh period is (at least) 50% higher that the time to copy the information (default 3600 seconds - 60 @@ -70,7 +70,7 @@ <entry>org.hibernate.search.store.FSSlaveDirectoryProvider</entry> <entry><para>File system based directory. Like - FSDirectoryProvider. But retrieve a master version (source) on a + FSDirectoryProvider, but retrieves a master version (source) on a regular basis. To avoid locking and inconsistent search results, 2 local copies are kept. </para><para>The recommended value for the refresh period is (at least) 50% higher that the time to copy the @@ -139,12 +139,13 @@ will be indexed, and use an in memory directory named <literal>Rules</literal> where Rule entities will be indexed.</para> - <para>So you can easily defined common rules like the directory provider + <para>You can easily define common rules like the directory provider and base directory, and overide those default later on on a per index basis.</para> <para>Writing your own <classname>DirectoryProvider</classname>, you can - benefit this configuration mechanism too.</para> + utilize this configuration mechanism as well.</para> + </section> <section id="search-configuration-directory-sharding" revision="1"> <title>Index sharding</title> @@ -152,9 +153,9 @@ <para>In some extreme cases involving huge indexes (in size), it is necessary to split (shard) the indexing data of a given entity type into several Lucene indexes. This solution is not recommended until you reach - significant index sizes and important indexing slows down, the main - drawback being that search will end up being slower (more files to - open). In other words don't do it until you have problems :)</para> + significant index sizes and important index updates are slowing down. The main + drawback of index sharding is that searches will end up being slower since more files have to + be opend for a single search. In other words don't do it until you have problems :)</para> <para>Despite this strong warning, Hibernate Search allows you to index a given entity type into several sub indexes. Data is sharded into the @@ -223,113 +224,107 @@ indexBase, default indexName)</para> </listitem> </itemizedlist> - </section> </section> <section> - <title>Worker and Back ends configuration</title> + <title>Worker configuration</title> <para>Hibernate Search works done by a worker you can configure. The default (and only) worker today use transactional scoping.</para> - <section> - <title>Generic configuration</title> + <para>You can define the worker configuration using the following + properties</para> - <para>You can define the worker configuration using the following - properties</para> + <table> + <title>worker configuration</title> - <para></para> + <tgroup cols="2"> + <colspec align="center" /> - <table> - <title>worker configuration</title> + <tbody> + <row> + <entry>Property</entry> - <tgroup cols="2"> - <colspec align="center" /> + <entry>Description</entry> + </row> - <tbody> - <row> - <entry>Property</entry> + <row> + <entry><literal>org.hibernate.worker.backend</literal></entry> - <entry>Description</entry> - </row> + <entry>Out of the box support for the Apache Lucene back end and + the JMS back end. Default to <literal>lucene</literal>. Supports + also <literal>jms</literal>.</entry> + </row> - <row> - <entry><literal>org.hibernate.worker.backend</literal></entry> + <row> + <entry><literal>org.hibernate.worker.execution</literal></entry> - <entry>Out of the box support for the Apache Lucene back end and - the JMS back end. Default to <literal>lucene</literal>. Supports - also <literal>jms</literal>.</entry> - </row> + <entry>Supports synchronous and asynchrounous execution. Default + to <literal><literal>sync</literal></literal>. Supports also + <literal>async</literal>.</entry> + </row> - <row> - <entry><literal>org.hibernate.worker.execution</literal></entry> + <row> + <entry><literal>org.hibernate.worker.thread_pool.size</literal></entry> - <entry>Supports synchronous and asynchrounous execution. Default - to <literal><literal>sync</literal></literal>. Supports also - <literal>async</literal>.</entry> - </row> + <entry>Defines the number of threads in the pool. useful only + for asynchrounous execution. Default to 1.</entry> + </row> - <row> - <entry><literal>org.hibernate.worker.thread_pool.size</literal></entry> + <row> + <entry><literal>org.hibernate.worker.buffer_queue.max</literal></entry> - <entry>Defines the number of threads in the pool. useful only - for asynchrounous execution. Default to 1.</entry> - </row> + <entry>Defines the maximal number of work queue if the thread + poll is starved. Useful only for asynchrounous execution. + Default to infinite. If the limit is reached, the work is done + by the main thread.</entry> + </row> - <row> - <entry><literal>org.hibernate.worker.buffer_queue.max</literal></entry> + <row> + <entry><literal>org.hibernate.worker.jndi.*</literal></entry> - <entry>Defines the maximal number of work queue if the thread - poll is starved. Useful only for asynchrounous execution. - Default to infinite. If the limit is reached, the work is done - by the main thread.</entry> - </row> + <entry>Defines the JNDI properties to initiate the + InitialContext (if needed). JNDI is only used by the JMS back + end.</entry> + </row> - <row> - <entry><literal>org.hibernate.worker.jndi.*</literal></entry> + <row> + <entry><literal> + org.hibernate.worker.jms.connection_factory</literal></entry> - <entry>Defines the JNDI properties to initiate the - InitialContext (if needed). JNDI is only used by the JMS back - end.</entry> - </row> + <entry>Mandatory for the JMS back end. Defines the JNDI name to + lookup the JMS connection factory from + (<literal>java:/ConnectionFactory</literal> by default in JBoss + AS)</entry> + </row> - <row> - <entry><literal> - org.hibernate.worker.jms.connection_factory</literal></entry> + <row> + <entry><literal> + org.hibernate.worker.jms.queue</literal></entry> - <entry>Mandatory for the JMS back end. Defines the JNDI name to - lookup the JMS connection factory from - (<literal>java:/ConnectionFactory</literal> by default in JBoss - AS)</entry> - </row> + <entry>Mandatory for the JMS back end. Defines the JNDI name to + lookup the JMS queue from. The queue will be used to post work + messages.</entry> + </row> - <row> - <entry><literal> - org.hibernate.worker.jms.queue</literal></entry> + <row> + <entry><literal> + org.hibernate.worker.batch_size</literal></entry> - <entry>Mandatory for the JMS back end. Defines the JNDI name to - lookup the JMS queue from. The queue will be used to post work - messages.</entry> - </row> + <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> + </section> - <row> - <entry><literal> - org.hibernate.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> - </section> - <section id="jms-backend"> <title>JMS Master/Slave configuration</title> - <para>This chapter describes in greater detail how to configure the + <para>This section describes in greater detail how to configure the Master / Slaves Hibernate Search architecture.</para> <section> @@ -374,7 +369,7 @@ <section> <title>Master node</title> - <para>Every index update operation is taken fron a JMS queue and + <para>Every index update operation is taken from a JMS queue and executed. The master index(es) is(are) copied on a regular basis.</para> @@ -423,26 +418,25 @@ <para>This example inherit the abstract JMS controller class available and implements a JavaEE 5 MDB. This implementation is given as an - example and, while most likely ;ore complex, can be adjusted to make + example and, while most likely more complex, can be adjusted to make use of non Java EE Message Driven Beans. For more information about the <methodname>getSession()</methodname> and <methodname>cleanSessionIfNeeded()</methodname>, please check <classname>AbstractJMSHibernateSearchController</classname>'s javadoc.</para> - <remark>Hibernate Search test suite makes use of JBoss Embedded to + <note>Hibernate Search test suite makes use of JBoss Embedded to test the JMS integration. It allows the unit test to run both the MDB container and JBoss Messaging (JMS provider) in a standalone way - (marketed by some as "lightweight").</remark> - </section> + (marketed by some as "lightweight").</note> </section> </section> - <section> + <section id="configuration-reader-strategy"> <title>Reader strategy configuration</title> <para>The different reader strategies are described in <xref - linkend="search-architecture-readerstrategy" /> .The default reader + linkend="search-architecture-readerstrategy" />. The default reader strategy is <literal>shared</literal>. This can be adjusted:</para> <programlisting>hibernate.search.reader.strategy = not-shared</programlisting> @@ -459,9 +453,9 @@ </section> <section id="search-configuration-event" revision="2"> - <title>Enabling automatic indexing</title> + <title>Automatic indexing</title> - <para>Automatic indexing is enable out of the box when using Hibernate + <para>Automatic indexing is enabled out of the box when using Hibernate Annotations or Hibernate EntityManager. If, for some reason you need to disable that, set <literal>hibernate.search.autoregister_listeners</literal> to false. Note @@ -518,18 +512,31 @@ <para>There are two sets of parameters allowing for different performance settings depending on the use case. During indexing operations triggered - by database modifications - <literal>hibernate.search.[default|&lt;indexname&gt;].transaction.merge_factor</literal>, - <literal>hibernate.search.[default|&lt;indexname&gt;].transaction.max_merge_docs</literal> - and - <literal>hibernate.search.[default|&lt;indexname&gt;].transaction.max_buffered_docs</literal> - are used. The corresponding - <literal>hibernate.search.[default|&lt;indexname&gt;].batch.merge_factor</literal>, - <literal>hibernate.search.[default|&lt;indexname&gt;].batch.max_merge_docs</literal> - and - <literal>hibernate.search.[default|&lt;indexname&gt;].batch.max_buffered_docs</literal> - properties are applied when indexing occurs via - <literal>FullTextSession.index()</literal> (see <xref + by database modifications: + <itemizedlist> + <listitem> + <literal>hibernate.search.[default|&lt;indexname&gt;].transaction.merge_factor</literal> + </listitem> + <listitem> + <literal>hibernate.search.[default|&lt;indexname&gt;].transaction.max_merge_docs</literal> + </listitem> + <listitem> + <literal>hibernate.search.[default|&lt;indexname&gt;].transaction.max_buffered_docs</literal> + </listitem> + </itemizedlist> + are used. The corresponding properties: + <itemizedlist> + <listitem> + <literal>hibernate.search.[default|&lt;indexname&gt;].batch.merge_factor</literal> + </listitem> + <listitem> + <literal>hibernate.search.[default|&lt;indexname&gt;].batch.max_merge_docs</literal> + </listitem> + <listitem> + <literal>hibernate.search.[default|&lt;indexname&gt;].batch.max_buffered_docs</literal> + </listitem> + </itemizedlist> + are applied when indexing occurs via <literal>FullTextSession.index()</literal> (see <xref linkend="search-batchindex" />).</para> <para>Unless the corresponding <literal>.batch</literal> property is Modified: trunk/HibernateExt/search/doc/reference/en/modules/getting-started.xml =================================================================== --- trunk/HibernateExt/search/doc/reference/en/modules/getting-started.xml 2007-08-11 06:48:08 UTC (rev 12923) +++ trunk/HibernateExt/search/doc/reference/en/modules/getting-started.xml 2007-08-12 13:55:13 UTC (rev 12924) @@ -28,23 +28,25 @@ <row> <entry>Hibernate Search</entry> <entry> - Version 3.0.0.Beta4 with all its dependencies - hibernate-search.jar, lucene-core-2.2.0.jar, jms.jar, ejb3-persistence.jar and - hibernate-commons-annotations.jar + <literal>hibernate-search.jar</literal> and all the dependencies from + the <literal>lib</literal> directory of the distribution. </entry> </row> <row> <entry>Hibernate Core</entry> <entry> - Version >= 3.2.2 with all its dependencies - hibernate3.jar, ehcache-1.2.3.jar, - swarmcache-1.0rc2.jar, jboss-cache.jar, jgroups-2.2.8.jar, jta.jar, commons-logging-1.0.4.jar, - c3p0-0.9.1.jar, asm-attrs.jar, dom4j-1.6.1.jar, ant-antlr-1.6.5.jar, cglib-2.1.3.jar, - oscache-2.1.jar, asm.jar, commons-collections-2.1.1.jar, ant-1.6.5.jar and proxool-0.8.3.jar. + This instructions have been tested against Hibernate 3.2.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 the minimum runtime requirements. </entry> </row> <row> <entry>Hibernate Annotations</entry> <entry> - Version 3.3.x with all its dependencies - hibernate-annotations.jar, ejb3-persistence.jar and jta.jar. + Even though Hibernate Search can be used without Hibernate Annotations + the following instructions will use them for ease of use. The tutorial is + tested against version 3.3.x of Hibernate Annotations. </entry> </row> </tbody> @@ -62,9 +64,8 @@ <title>Configuration</title> <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. + to add a few properties to your hibernate configuration file (hibernate.properties, hibernate.cfg.xml or persistence.xml). The good news is that for standard use + most properties offer a sensible default. 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 @@ -161,7 +162,7 @@ </section> <section> - <title>Inital Indexing</title> + <title>Indexing</title> <para> 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 @@ -183,7 +184,7 @@ </section> <section> - <title>First search</title> + <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 @@ -191,14 +192,19 @@ </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(); +// JPA users have to use <classname>EntityManager</classname> and <classname>FullTextEntityManager</classname> +// instead of <classname>Session</classname> and <classname>FullTextSession</classname> in order create a query - see <xref linkend="search-query"/> -MultiFieldQueryParser parser = new MultiFieldQueryParser( new String[]{"summary", "body"}, new StandardAnalyzer()); +// 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(); + +Transaction tx = fullTextSession.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 ); +org.hibernate.Query hibQuery = fullTextSession.createFullTextQuery( query, Book.class ); List result = hibQuery.list(); tx.commit(); Modified: trunk/HibernateExt/search/doc/reference/en/modules/mapping.xml =================================================================== --- trunk/HibernateExt/search/doc/reference/en/modules/mapping.xml 2007-08-11 06:48:08 UTC (rev 12923) +++ trunk/HibernateExt/search/doc/reference/en/modules/mapping.xml 2007-08-12 13:55:13 UTC (rev 12924) @@ -3,7 +3,7 @@ <chapter id="search-mapping" revision="3"> <title>Mapping entities to the index structure</title> - <para>All the metadata information related to indexed entities is described + <para>All the metadata information needed to index entities is described through some Java annotations. There is no need for xml mapping files nor a list of indexed entities. The list is discovered at startup time scanning the Hibernate mapped entities.</para> @@ -51,7 +51,7 @@ <para><literal>store</literal> : describe whether or not the property is stored in the Lucene index. You can store the value <literal>Store.YES</literal> (comsuming more space in the index but - allowing projection, see <xref linkend="search-query" /> for more + allowing projection, see <xref linkend="projections" /> for more information), store it in a compressed way <literal>Store.COMPRESS</literal> (this does consume more CPU), or avoid any storage <literal>Store.NO</literal> (this is the default @@ -78,7 +78,7 @@ <para>Whether or not you want to store the data depends on how you wish 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 + subsequently project them (see <xref linkend="projections" /> for more information).</para> <para>Whether or not you want to tokenize a property depends on whether @@ -125,10 +125,10 @@ <section> <title>Mapping properties multiple times</title> - <para>It is sometimes needed to map a proeprty multiple times per index, + <para>It is sometimes needed to map a property multiple times per index, with slightly different indexing strategies. Especially, sorting a query by field requires the field to be <literal>UN_TOKENIZED</literal>. If - one want to search by words in this proeprty and still sort it, one need + one want to search by words in this property and still sort it, one need to index it twice, once tokenized, once untokenized. @Fields allows to achieve this goal.</para> @@ -309,7 +309,7 @@ contains a cyclic dependency of classes (not instances). For example, if <classname>Owner</classname> points to <classname>Place</classname>. Hibernate Search will stop including Indexed embedded atttributes after - reaching the expected depth (or is the object graph boundaries are + reaching the expected depth (or the object graph boundaries are reached). A class having a self reference is an example of cyclic dependency. In our example, because <literal>depth</literal> is set to 1, any <literal>@IndexedEmbedded</literal> attribute in Owner (if any) @@ -455,10 +455,11 @@ <section id="search-mapping-bridge"> <title>Property/Field Bridge</title> - <para>All field of a full text index in Lucene have to be represented as - Strings. Ones Java properties have to be indexed in a String form. For + <para>In Lucene all index fields have to be represented as + Strings. For this reason all entity properties annotated with <literal>@Field</literal> + have to be indexed in a String form. For most of your properties, Hibernate Search does the translation job for you - thanks to a built-in set of bridges. In some cases, though you need a fine + thanks to a built-in set of bridges. In some cases, though you need a more fine grain control over the translation process.</para> <section> @@ -497,7 +498,7 @@ <para>Numbers are converted in their String representation. Note that numbers cannot be compared by Lucene (ie used in ranged queries) out of the box: they have to be padded <footnote> - <para>Using a Range query is debattable and has drawbacks, an + <para>Using a Range query is debatable and has drawbacks, an alternative approach is to use a Filter query which will filter the result query to the appropriate range.</para> @@ -546,9 +547,10 @@ <section> <title>Custom Bridge</title> - <para>It can happen that the built-in bridges of Hibernate Search does + <para>It can happen that the built-in bridges of Hibernate Search do not cover some of your property types, or that the String representation - used is not what you expect.</para> + used is not what you expect. The following paragraphs sveral solutions for this + problem.</para> <section> <title>StringBridge</title> Modified: trunk/HibernateExt/search/doc/reference/en/modules/query.xml =================================================================== --- trunk/HibernateExt/search/doc/reference/en/modules/query.xml 2007-08-11 06:48:08 UTC (rev 12923) +++ trunk/HibernateExt/search/doc/reference/en/modules/query.xml 2007-08-12 13:55:13 UTC (rev 12924) @@ -30,7 +30,7 @@ List result = fullTextQuery.list(); //return a list of managed objects </programlisting> <para>The Hibernate query built on top of the Lucene query is a regular - <literal>org.hibernate.Query</literal> , you are is the same paradigm as the + <literal>org.hibernate.Query</literal> , you are in the same paradigm as the other Hibernate query facilities (HQL, Native or Criteria). The regular <literal>list()</literal> , <literal>uniqueResult()</literal> , <literal>iterate()</literal> and <literal>scroll()</literal> can be @@ -59,7 +59,7 @@ <section> <title>Building queries</title> - <para>Hibernate Search queries are built on top of a Lucene query. It + <para>Hibernate Search queries are built on top of Lucene queries. It gives you a total freedom on the kind of Lucene queries you are willing to execute. However, once built, Hibernate Search abstract the query processing from your application using org.hibernate.Query as your primary @@ -85,7 +85,7 @@ <programlisting>FullTextSession fullTextSession = Search.createFullTextSession( session ); org.hibernate.Query fullTextQuery = fullTextSession.createFullTextQuery( luceneQuery );</programlisting> - <para>If not specified, the query will be executed all indexed, + <para>If not specified otherwise, the query will be executed against all indexed entities, potentially returning all types of indexed classes. It is advised, from a performance point of view, to restrict the returned types:</para> @@ -498,7 +498,7 @@ implementation to each of the parameters equals and hashcode methods.</para> - <para>Should filters be cached? There are 2 area where filter caching + <para>Why should filters be cached? There are two area where filter caching shines:</para> <itemizedlist>