[hibernate-commits] Hibernate SVN: r13964 - search/trunk/doc/reference/en/modules.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Thu Aug 30 10:13:47 EDT 2007
Author: epbernard
Date: 2007-08-30 10:13:47 -0400 (Thu, 30 Aug 2007)
New Revision: 13964
Modified:
search/trunk/doc/reference/en/modules/getting-started.xml
Log:
Various docs
Modified: search/trunk/doc/reference/en/modules/getting-started.xml
===================================================================
--- search/trunk/doc/reference/en/modules/getting-started.xml 2007-08-30 14:06:00 UTC (rev 13963)
+++ search/trunk/doc/reference/en/modules/getting-started.xml 2007-08-30 14:13:47 UTC (rev 13964)
@@ -3,15 +3,14 @@
<chapter id="getting-started">
<title>Getting started</title>
- <para>
- The following chapter will guide you through the initial steps
- required to integrate Hibernate Search into an existing
- Hibernate enabled application. In case you are a Hibernate new timer
- we recommend you start <ulink url="http://hibernate.org/152.html">here</ulink>.
- </para>
+ <para>The following chapter will guide you through the initial steps
+ required to integrate Hibernate Search into an existing Hibernate enabled
+ application. In case you are a Hibernate new timer we recommend you start
+ <ulink url="http://hibernate.org/152.html">here</ulink>.</para>
<section>
<title>System Requirements</title>
+
<table>
<title>System requirements</title>
@@ -19,69 +18,79 @@
<tbody>
<row>
<entry>Java Runtime</entry>
- <entry>
- A JDK or JRE version <emphasis>1.5</emphasis>
- or greater. You can download a Java Runtime for Windows/Linux/Solaris
- <ulink url="http://java.sun.com/javase/downloads/"> here </ulink>.
- </entry>
+
+ <entry>A JDK or JRE version <emphasis>1.5</emphasis> or greater.
+ You can download a Java Runtime for Windows/Linux/Solaris <ulink
+ url="http://java.sun.com/javase/downloads/"> here
+ </ulink>.</entry>
</row>
+
<row>
<entry>Hibernate Search</entry>
- <entry>
- <literal>hibernate-search.jar</literal> and all the dependencies from
- the <literal>lib</literal> directory of the Hibernate Search distribution.
- </entry>
- </row>
+
+ <entry><literal>hibernate-search.jar</literal> and all the
+ dependencies from the <literal>lib</literal> directory of the
+ Hibernate Search distribution.</entry>
+ </row>
+
<row>
<entry>Hibernate Core</entry>
- <entry>
- 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>
+
+ <entry>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>
- 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>
+
+ <entry>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>
</tgroup>
</table>
- <para>
- You can download all dependencies from the Hibernate
- <ulink url="http://www.hibernate.org/6.html">download site</ulink>. You can also verify the
- dependency versions against the <ulink url="http://www.hibernate.org/6.html#A3">
- Hibernate Compatibility Matrix</ulink>.
- </para>
+
+ <para>You can download all dependencies from the Hibernate <ulink
+ url="http://www.hibernate.org/6.html">download site</ulink>. You can also
+ verify the dependency versions against the <ulink
+ url="http://www.hibernate.org/6.html#A3"> Hibernate Compatibility
+ Matrix</ulink>.</para>
</section>
<section>
<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. If you are using Hibernate directly this can
- be done in <literal>hibernate.properties</literal> or <literal>hibernate.cfg.xml</literal>.
- 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>
- 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> 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>
+
+ <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. If you are using Hibernate directly this can be done
+ in <literal>hibernate.properties</literal> or
+ <literal>hibernate.cfg.xml</literal>. 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>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> 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
...
@@ -101,14 +110,14 @@
// standard getters/setters follow here
...
- </programlisting>
-
- <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 have to specify the default root directory for all indexes via <literal>hibernate.search.default.indexBase</literal>.
- </para>
-
+ </programlisting>
+
+ <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 have to specify the default root directory for all
+ indexes via <literal>hibernate.search.default.indexBase</literal>.</para>
+
<programlisting>
...
# the default directory provider
@@ -118,24 +127,28 @@
hibernate.search.default.indexBase = /var/lucene/indexes
...
</programlisting>
-
- <para>
- 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 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
- ensure that the text will be tokenized using the default Lucene analyzer whereas
- <literal>store=Store.NO</literal> ensures that the actual data will not be stored in the index.
- </para>
- <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 in order to avoid database roundtrips refer to projections in <xref linkend="projections" />
- </para>
-
+
+ <para>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 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 ensure that the text will be
+ tokenized using the default Lucene analyzer whereas
+ <literal>store=Store.NO</literal> ensures that the actual data will not be
+ stored in the index.</para>
+
+ <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 in order to avoid
+ database roundtrips refer to projections in <xref
+ linkend="projections" /></para>
+
<programlisting>
package exmaple.Book
...
@@ -161,20 +174,19 @@
// standard getters/setters follow here
...
- </programlisting>
-
+ </programlisting>
</section>
-
+
<section>
<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 one of the following code examples
- to your code (see also <xref linkend="search-batchindex"/>):
- </para>
- <para>
- Example using Hibernate Session:
- </para>
+
+ <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 one of the following code examples to your code (see also <xref
+ linkend="search-batchindex" />):</para>
+
+ <para>Example using Hibernate Session:</para>
+
<programlisting>
FullTextSession fullTextSession = Search.createFullTextSession(session);
Transaction tx = fullTextSession.beginTransaction();
@@ -184,9 +196,9 @@
}
tx.commit(); //index are written at commit time
</programlisting>
- <para>
- Example using JPA:
- </para>
+
+ <para>Example using JPA:</para>
+
<programlisting>
EntityManager em = entityManagerFactory.createEntityManager();
FullTextEntityManager fullTextEntityManager = Search.createFullTextEntityManager(em);
@@ -194,23 +206,24 @@
for (Book book : books) {
fullTextEntityManager.index(book);
}
- </programlisting>
- <para>
- After executing the above code there should be a Lucene index under
- <literal>/var/lucene/indexes/example.Book</literal>. Go ahead an inspect this index. It will
- help you to understand how Hibernate Search works.
- </para>
- </section>
+ </programlisting>
+
+ <para>After executing the above code there should be a Lucene index under
+ <literal>/var/lucene/indexes/example.Book</literal>. Go ahead an inspect
+ this index. It will help you to understand how Hibernate Search
+ works.</para>
+ </section>
+
<section>
<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
- a list of <classname>Book</classname>s:
- </para>
- <para>
- Example using Hibernate Session:
- </para>
+
+ <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 a list of
+ <classname>Book</classname>s:</para>
+
+ <para>Example using Hibernate Session:</para>
+
<programlisting>
FullTextSession fullTextSession = Search.createFullTextSession(session);
@@ -224,10 +237,10 @@
tx.commit();
session.close();
- </programlisting>
- <para>
- Example using JPA:
- </para>
+ </programlisting>
+
+ <para>Example using JPA:</para>
+
<programlisting>
EntityManager em = entityManagerFactory.createEntityManager();
@@ -238,38 +251,44 @@
Query query = parser.parse( "Java rocks!" );
org.hibernate.Query hibQuery = fullTextEntityManager.createFullTextQuery( query, Book.class );
List result = hibQuery.list();
- </programlisting>
+ </programlisting>
</section>
-
+
<section>
<title>Analyzer</title>
-
- <para>
- 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 offers several ways to configure the analyzer to use (see <xref linkend="analyzer"/>):
- </para>
-
+
+ <para>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 offers several ways to configure the analyzer to
+ use (see <xref linkend="analyzer" />):</para>
+
<itemizedlist>
- <listitem>
- <para>Setting the <literal>hibernate.search.analyzer</literal> property in the configuration file.
- The specified class will then be the default analyzer.</para>
- </listitem>
- <listitem>
- <para>Setting the <literal>Analyzer</literal> annotation on entity level.</para>
- </listitem>
- <listitem>
- <para>Setting the <literal>Analyzer</literal> annotation on field level.</para>
- </listitem>
- </itemizedlist>
-
- <para>
- 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>.
- </para>
+ <listitem>
+ <para>Setting the <literal>hibernate.search.analyzer</literal>
+ property in the configuration file. The specified class will then be
+ the default analyzer.</para>
+ </listitem>
+
+ <listitem>
+ <para>Setting the <literal>Analyzer</literal> annotation on entity
+ level.</para>
+ </listitem>
+
+ <listitem>
+ <para>Setting the <literal>Analyzer</literal> annotation on field
+ level.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>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>.</para>
+
<programlisting>
package example.Book
...
@@ -311,25 +330,26 @@
return result;
}
}
- </programlisting>
- </section>
-
+ </programlisting>
+ </section>
+
<section>
<title>What's next</title>
- <para>
- 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 ((<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
- (<xref linkend="analyzer"/>) and field bridges (<xref linkend="search-mapping-bridge"/>), both important
- features required for more fain grained indexing.
- </para>
- <para>
- More advanced topics cover clustering (<xref linkend="jms-backend"/>) and large indexes
- handling (<xref linkend="search-configuration-directory-sharding"/>).
- </para>
+
+ <para>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 ((<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 (<xref linkend="analyzer" />) and field bridges
+ (<xref linkend="search-mapping-bridge" />), both important features
+ required for more fain grained indexing.</para>
+
+ <para>More advanced topics cover clustering (<xref
+ linkend="jms-backend" />) and large indexes handling (<xref
+ linkend="search-configuration-directory-sharding" />).</para>
</section>
</chapter>
\ No newline at end of file
More information about the hibernate-commits
mailing list