Author: hardy.ferentschik Date: 2009-11-01 09:31:50 -0500 (Sun, 01 Nov 2009) New Revision: 17885 Modified: search/trunk/src/main/docbook/en-US/modules/mapping.xml Log: HSEARCH-324 Added documentation for dynamic boost Modified: search/trunk/src/main/docbook/en-US/modules/mapping.xml =================================================================== --- search/trunk/src/main/docbook/en-US/modules/mapping.xml 2009-10-30 13:58:05 UTC (rev 17884) +++ search/trunk/src/main/docbook/en-US/modules/mapping.xml 2009-11-01 14:31:50 UTC (rev 17885) @@ -33,9 +33,9 @@ through annotations. There is no need for xml mapping files. In fact there is currently no xml configuration option available (see <ulink url="http://opensource.atlassian.com/projects/hibernate/browse/HSEAR...>). - You can still use hibernate mapping files for the basic Hibernate - configuration, but the Search specific configuration has to be expressed via - annotations.</para> + You can still use Hibernate mapping files for the basic Hibernate + configuration, but the Hibernate Search specific configuration has to be + expressed via annotations.</para> <section id="search-mapping-entity" revision="3"> <title>Mapping an entity</title> @@ -73,9 +73,9 @@ <para>For each property (or attribute) of your entity, you have the ability to describe how it will be indexed. The default (no annotation - present) means that the property is completely 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 + present) means that the property is 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> @@ -181,9 +181,10 @@ <para>Whether or not you want to tokenize a property depends on whether you wish to search the element as is, or by the words it contains. It - make sense to tokenize a text field, but tokenizing a date field - probably not. Note that fields used for sorting must not be - tokenized.</para> + make sense to tokenize a text field, but probably not a date field. + <note> + <para>Fields used for sorting must not be tokenized.</para> + </note></para> <para>Finally, the id property of an entity is a special property used by Hibernate Search to ensure index unicity of a given entity. By @@ -193,7 +194,7 @@ can omit @DocumentId. The chosen entity id will also be used as document id.</para> - <example> + <example id="example-annotated-entity"> <title>Adding <classname>@DocumentId</classname> ad <classname>@Field</classname> annotations to an indexed entity</title> @@ -215,8 +216,8 @@ }</programlisting> </example> - <para>The above annotations define an index with three fields: - <literal>id</literal> , <literal>Abstract</literal> and + <para><xref linkend="example-annotated-entity" /> 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> </section> @@ -231,7 +232,7 @@ index it twice - once tokenized and once untokenized. @Fields allows to achieve this goal.</para> - <example> + <example id="example-fields-annotation"> <title>Using @Fields to map a property multiple times</title> <programlisting>@Entity @@ -249,7 +250,8 @@ }</programlisting> </example> - <para>The field <literal>summary</literal> is indexed twice, once as + <para>In <xref linkend="example-fields-annotation" /> the field + <literal>summary</literal> is indexed twice, once as <literal>summary</literal> in a tokenized way, and once as <literal>summary_forSort</literal> in an untokenized way. @Field supports 2 attributes useful when @Fields is used:</para> @@ -514,7 +516,7 @@ </example> </section> - <section> + <section id="section-boost-annotation"> <title>Boost factor</title> <para>Lucene has the notion of <emphasis>boost factor</emphasis>. It's a @@ -565,6 +567,63 @@ from Otis Gospodnetic and Erik Hatcher.</para> </section> + <section> + <title id="section-dynamic-boost">Dynamic boost factor</title> + + <para>The <literal>@Boost </literal>annotation used in <xref + linkend="section-boost-annotation" /> defines a static boost factor + which is is independent of the state of of the indexed entity at + runtime. However, there are usecases in which the boost factor may + depends on the actual state of the entity. In this case you can use the + <literal>@DynamicBoost </literal>annotation together with an + accompanying custom <classname>BoostStrategy</classname>.<example + id="example-dynamic-boosting"> + <title>Dynamic boost examle</title> + + <programlisting>public enum PersonType { + NORMAL, + VIP +} + +@Entity +@Indexed +<emphasis role="bold">@DynamicBoost(impl = VIPBoostStrategy.class)</emphasis> +public class Person { + private PersonType type; + + // .... +} + +public class VIPBoostStrategy implements BoostStrategy { + <emphasis role="bold">public float defineBoost(Object value)</emphasis> { + Person person = ( Person ) value; + if ( person.getType().equals( PersonType.VIP ) ) { + return 2.0f; + } + else { + return 1.0f; + } + } +}</programlisting> + </example>In <xref linkend="example-dynamic-boosting" /> a dynamic + boost is defined on class level specifying + <classname>VIPBoostStrategy</classname> as implementation of the + <classname>BoostStrategy</classname> interface to be used at indexing + time. You can place the <literal>@DynamicBoost</literal> either at class + or field level. Depending on the placement of the annotation either the + whole entity is passed to the <methodname>defineBoost</methodname> + method or just the annotated field/property value. It's up to you to + cast the passed object to the correct type. In the example all indexed + values of a VIP person would be double as important as the values of a + normal person.<note> + <para>The specified <classname>BoostStrategy</classname> + implementation must define a public no-arg constructor.</para> + </note>Of course you can mix and match <literal>@Boost</literal> and + <literal>@DynamicBoost</literal> annotations in your entity. All defined + boost factors are cummulative as described in <xref + linkend="section-boost-annotation" />.</para> + </section> + <section id="analyzer"> <title>Analyzer</title>