[hibernate-commits] Hibernate SVN: r11263 - branches/Branch_3_2/HibernateExt/search/doc/reference/en/modules.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Wed Mar 7 20:42:10 EST 2007
Author: epbernard
Date: 2007-03-07 20:42:10 -0500 (Wed, 07 Mar 2007)
New Revision: 11263
Modified:
branches/Branch_3_2/HibernateExt/search/doc/reference/en/modules/mapping.xml
Log:
HSEARCH-27 documentation on @indexedEmbedded
Modified: branches/Branch_3_2/HibernateExt/search/doc/reference/en/modules/mapping.xml
===================================================================
--- branches/Branch_3_2/HibernateExt/search/doc/reference/en/modules/mapping.xml 2007-03-07 23:56:43 UTC (rev 11262)
+++ branches/Branch_3_2/HibernateExt/search/doc/reference/en/modules/mapping.xml 2007-03-08 01:42:10 UTC (rev 11263)
@@ -10,81 +10,84 @@
<section id="search-mapping-entity" revision="3">
<title>Mapping an entity</title>
- <para>First, we must declare a persistent class as indexable. This is done
- by annotating the class with <literal>@Indexed</literal> (all entities not
- annotated with <literal>@Indexed</literal> will be ignored by the indexing
- process):</para>
+ <section>
+ <title>Basic mapping</title>
- <programlisting>@Entity
+ <para>First, we must declare a persistent class as indexable. This is
+ done by annotating the class with <literal>@Indexed</literal> (all
+ entities not annotated with <literal>@Indexed</literal> will be ignored
+ by the indexing process):</para>
+
+ <programlisting>@Entity
<emphasis role="bold">@Indexed(index="indexes/essays")</emphasis>
public class Essay {
...
}</programlisting>
- <para>The <literal>index</literal> attribute tells Hibernate what the
- Lucene directory name is (usually a directory on your file system). If you
- wish to define a base directory for all Lucene indexes, you can use the
- <literal>hibernate.search.default.indexBase</literal> property in your
- configuration file. Each entity instance will be represented by a Lucene
- <classname>Document</classname> inside the given index (aka
- Directory).</para>
+ <para>The <literal>index</literal> attribute tells Hibernate what the
+ Lucene directory name is (usually a directory on your file system). If
+ you wish to define a base directory for all Lucene indexes, you can use
+ the <literal>hibernate.search.default.indexBase</literal> property in
+ your configuration file. Each entity instance will be represented by a
+ Lucene <classname>Document</classname> inside the given index (aka
+ Directory).</para>
- <para>For each property (or attribute) of your entity, you have the
- ability to describe how it will be indexed. The default (ie no annotation)
- means that the property is completly ignored by the indexing process.
- <literal>@Field</literal> does declare a property as indexed. When
- indexing an element to a Lucene document you can specify how it is
- indexed:</para>
+ <para>For each property (or attribute) of your entity, you have the
+ ability to describe how it will be indexed. The default (ie no
+ annotation) means that the property is completly ignored by the indexing
+ process. <literal>@Field</literal> does declare a property as indexed.
+ When indexing an element to a Lucene document you can specify how it is
+ indexed:</para>
- <itemizedlist>
- <listitem>
- <para><literal>name</literal> : describe under which name, the
- property should be stored in the Lucene Document. The default value is
- the property name (following the JavaBeans convention)</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><literal>name</literal> : describe under which name, the
+ property should be stored in the Lucene Document. The default value
+ is the property name (following the JavaBeans convention)</para>
+ </listitem>
- <listitem>
- <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),
- 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 value). When a
- property is stored, you can retrieve it from the Lucene Document (note
- that this is not related to whether the element is indexed or
- not).</para>
- </listitem>
+ <listitem>
+ <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),
+ 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 value). When a
+ property is stored, you can retrieve it from the Lucene Document
+ (note that this is not related to whether the element is indexed or
+ not).</para>
+ </listitem>
- <listitem>
- <para>index: describe how the element is indexed (ie the process used
- to index the property and the type of information store). The
- different values are <literal>Index.NO</literal> (no indexing, ie
- cannot be found by a query), <literal>Index.TOKENIZED</literal> (use
- an analyzer to process the property),
- <literal>Index.UN_TOKENISED</literal> (no analyzer pre processing),
- <literal>Index.NO_NORM</literal> (do not store the normalization
- data).</para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para>index: describe how the element is indexed (ie the process
+ used to index the property and the type of information store). The
+ different values are <literal>Index.NO</literal> (no indexing, ie
+ cannot be found by a query), <literal>Index.TOKENIZED</literal> (use
+ an analyzer to process the property),
+ <literal>Index.UN_TOKENISED</literal> (no analyzer pre processing),
+ <literal>Index.NO_NORM</literal> (do not store the normalization
+ data).</para>
+ </listitem>
+ </itemizedlist>
- <para>These attributes are part of the <literal>@Field</literal>
- annotation.</para>
+ <para>These attributes are part of the <literal>@Field</literal>
+ annotation.</para>
- <para>Whether or not you want to store the data depends on how you wish to
- use the index query result. As of today, for a pure <productname>Hibernate
- Search </productname> usage, storing is not necessary. Whether or not you
- want to tokenize a property or not depends on whether you wish to search
- the element as is, or only normalized part of it. It make sense to
- tokenize a text field, but it does not to do it for a date field (or an id
- field).</para>
+ <para>Whether or not you want to store the data depends on how you wish
+ to use the index query result. As of today, for a pure
+ <productname>Hibernate Search </productname> usage, storing is not
+ necessary. Whether or not you want to tokenize a property or not depends
+ on whether you wish to search the element as is, or only normalized part
+ of it. It make sense to tokenize a text field, but it does not to do it
+ for a date field (or an id field).</para>
- <para>Finally, the id property of an entity is a special property used by
- <productname>Hibernate Search</productname> to ensure index unicity of a
- given entity. By design, an id has to be stored and must not be tokenized.
- To mark a property as index id, use the <literal>@DocumentId</literal>
- annotation.</para>
+ <para>Finally, the id property of an entity is a special property used
+ by <productname>Hibernate Search</productname> to ensure index unicity
+ of a given entity. By design, an id has to be stored and must not be
+ tokenized. To mark a property as index id, use the
+ <literal>@DocumentId</literal> annotation.</para>
- <programlisting>@Entity
+ <programlisting>@Entity
@Indexed(index="indexes/essays")
public class Essay {
...
@@ -101,21 +104,150 @@
public String getText() { return text; }
}</programlisting>
- <para>These annotations define an index with three fields:
- <literal>id</literal> , <literal>Abstract</literal> and
- <literal>text</literal> . Note that by default the field name is
- decapitalized, following the JavaBean specification.</para>
+ <para>These annotations define an index with three fields:
+ <literal>id</literal> , <literal>Abstract</literal> and
+ <literal>text</literal> . Note that by default the field name is
+ decapitalized, following the JavaBean specification.</para>
- <para>Note: you <emphasis>must</emphasis> specify
- <literal>@DocumentId</literal> on the identifier property of your entity
- class.</para>
+ <note>
+ <para>You <emphasis>must</emphasis> specify
+ <literal>@DocumentId</literal> on the identifier property of your
+ entity class.</para>
+ </note>
+ </section>
- <para>Lucene has the notion of <emphasis>boost factor</emphasis> . It's a
- way to give more weigth to a field or to an indexed element over an other
- during the indexation process. You can use <literal>@Boost</literal> at
- the field or the class level.</para>
+ <section>
+ <title>Embedded and associated objects</title>
- <programlisting>@Entity
+ <para>Associated objects as well as embedded objects can be indexed as
+ well as part of the root entity index.</para>
+
+ <programlisting>@Entity
+ at Indexed
+public class Place {
+ @Id
+ @GeneratedValue
+ @DocumentId
+ private Long id;
+
+ @Field( index = Index.TOKENIZED )
+ private String name;
+
+ @OneToOne( cascade = { CascadeType.PERSIST, CascadeType.REMOVE } )
+ <emphasis role="bold">@IndexedEmbedded</emphasis>
+ private Address address;
+ ....
+}
+
+ at Entity
+ at Indexed
+public class Address {
+ @Id
+ @GeneratedValue
+ @DocumentId
+ private Long id;
+
+ @Field(index=Index.TOKENIZED)
+ private String street;
+
+ @Field(index=Index.TOKENIZED)
+ private String city;
+
+ <emphasis role="bold">@IndexedEmbedded(depth = 1, prefix = "ownedBy_")</emphasis>
+ private Owner ownedBy;
+ ...
+}
+
+ at Embeddable
+public class Owner {
+ @Field(index = Index.TOKENIZED)
+ private String name;
+ ...
+}</programlisting>
+
+ <para>Any <literal>@*ToOne</literal> and <literal>@Embedded</literal>
+ attribute can be annotated with <literal>@IndexedEmbedded</literal>. The
+ attributes of the associated class will then be added to the main entity
+ index. In the previous example, the index will contain the following
+ fields</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>id</para>
+ </listitem>
+
+ <listitem>
+ <para>name</para>
+ </listitem>
+
+ <listitem>
+ <para>address.street</para>
+ </listitem>
+
+ <listitem>
+ <para>address.city</para>
+ </listitem>
+
+ <listitem>
+ <para>addess.ownedBy_name</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The default prefix is <literal>propertyName.</literal>, following
+ the traditional object navigation convention. You can override it using
+ the <literal>prefix</literal> attribute.</para>
+
+ <para><literal>depth</literal> is necessary when the object graph
+ contains a cyclic dependency of classes (not instance). 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
+ 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)
+ will be ignored.</para>
+
+ <para>Such a mapping is very useful to express queries refering to
+ associated objects, such as:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Return places where name contains JBoss and where address city
+ is Atlanta. In Lucene query this would be</para>
+
+ <programlisting>+name:jboss +address.city:atlanta </programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Return places where name contains JBoss and where owner's name
+ contain Joe. In Lucene query this would be</para>
+
+ <programlisting>+name:jboss +address.orderBy_name:joe </programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <para>In a way it mimics the relational join operation in a more
+ efficient way (at the cost of data duplication). Remember that, out of
+ the box, Lucene indexes have no notion of association, the join
+ operation is simply non-existent. It might help to keep the relational
+ model normalzed while benefiting from the full text index speed and
+ feature richness.</para>
+
+ <para><note>
+ <para>An associated object can itself be (but don't have to)
+ <literal>@Indexed</literal> </para>
+ </note></para>
+ </section>
+
+ <section>
+ <title>Boost factor</title>
+
+ <para>Lucene has the notion of <emphasis>boost factor</emphasis> . It's
+ a way to give more weigth to a field or to an indexed element over an
+ other during the indexation process. You can use
+ <literal>@Boost</literal> at the field or the class level.</para>
+
+ <programlisting>@Entity
@Indexed(index="indexes/essays")
<emphasis role="bold">@Boost(2)</emphasis>
public class Essay {
@@ -134,18 +266,23 @@
public String getText() { return text; }
} </programlisting>
- <para>In our example, Essay's probability to reach the top of the search
- list will be multiplied by 2 and the summary field will be 2.5 more
- important than the test field. Note that this explaination is actually
- wrong, but it is simple and close enought to the reality. Please check the
- Lucene documentation or the excellent <citetitle>Lucene In Action
- </citetitle> from Otis Gospodnetic and Erik Hatcher.</para>
+ <para>In our example, Essay's probability to reach the top of the search
+ list will be multiplied by 2 and the summary field will be 2.5 more
+ important than the test field. Note that this explaination is actually
+ wrong, but it is simple and close enought to the reality. Please check
+ the Lucene documentation or the excellent <citetitle>Lucene In Action
+ </citetitle> from Otis Gospodnetic and Erik Hatcher.</para>
+ </section>
- <para>The analyzer class used to index the elements is configurable
- through the <literal>hibernate.search.analyzer</literal> property. If none
- defined,
- <classname>org.apache.lucene.analysis.standard.StandardAnalyzer</classname>
- is used as the default.</para>
+ <section>
+ <title>Analyser</title>
+
+ <para>The analyzer class used to index the elements is configurable
+ through the <literal>hibernate.search.analyzer</literal> property. If
+ none defined,
+ <classname>org.apache.lucene.analysis.standard.StandardAnalyzer</classname>
+ is used as the default.</para>
+ </section>
</section>
<section id="search-mapping-bridge">
More information about the hibernate-commits
mailing list