From hibernate-commits at lists.jboss.org Sun Nov 1 09:31:50 2009
Content-Type: multipart/mixed; boundary="===============3961171440510430238=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r17885 -
search/trunk/src/main/docbook/en-US/modules.
Date: Sun, 01 Nov 2009 09:31:50 -0500
Message-ID: <200911011431.nA1EVoU6008441@svn01.web.mwc.hst.phx2.redhat.com>
--===============3961171440510430238==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- search/trunk/src/main/docbook/en-US/modules/mapping.xml 2009-10-30 13:5=
8:05 UTC (rev 17884)
+++ search/trunk/src/main/docbook/en-US/modules/mapping.xml 2009-11-01 14:3=
1:50 UTC (rev 17885)
@@ -33,9 +33,9 @@
through annotations. There is no need for xml mapping files. In fact the=
re
is currently no xml configuration option available (see HSEARCH-210).
- You can still use hibernate mapping files for the basic Hibernate
- configuration, but the Search specific configuration has to be expressed=
via
- annotations.
+ You can still use Hibernate mapping files for the basic Hibernate
+ configuration, but the Hibernate Search specific configuration has to be
+ expressed via annotations.
=
Mapping an entity
@@ -73,9 +73,9 @@
=
For each property (or attribute) of your entity, you have the
ability to describe how it will be indexed. The default (no annotati=
on
- present) means that the property is completely ignored by the indexi=
ng
- process. @Field does declare a property as indexe=
d.
- 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.
+ @Field does declare a property as indexed. When
+ indexing an element to a Lucene document you can specify how it is
indexed:
=
@@ -181,9 +181,10 @@
=
Whether or not you want to tokenize a property depends on whet=
her
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.
+ make sense to tokenize a text field, but probably not a date field.
+
+ Fields used for sorting must not be tokenized.
+
=
Finally, the id property of an entity is a special property us=
ed
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 docu=
ment
id.
=
-
+
Adding <classname>@DocumentId</classname> ad
<classname>@Field</classname> annotations to an indexed entity</ti=
tle>
=
@@ -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=3D"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=3D"example-fields-annotation">
<title>Using @Fields to map a property multiple times
=
@Entity
@@ -249,7 +250,8 @@
}
=
- The field summary is indexed twice, once as
+ In the field
+ summary is indexed twice, once as
summary in a tokenized way, and once as
summary_forSort in an untokenized way. @Field
supports 2 attributes useful when @Fields is used:
@@ -514,7 +516,7 @@
=
-
+
Boost factor
=
Lucene has the notion of boost factor. It=
's a
@@ -565,6 +567,63 @@
from Otis Gospodnetic and Erik Hatcher.
=
+
+ Dynamic boost factor
+
+ The @Boost annotation used in 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
+ @DynamicBoost annotation together with an
+ accompanying custom BoostStrategy.
+ Dynamic boost examle
+
+ public enum PersonType {
+ NORMAL,
+ VIP
+}
+
+(a)Entity
+(a)Indexed
+@DynamicBoost(impl =3D VIPBoostStrategy.class)
+public class Person {
+ private PersonType type; =
+ =
+ // ....
+}
+
+public class VIPBoostStrategy implements BoostStrategy {
+ public float defineBoost(Object value) {
+ Person person =3D ( Person ) value;
+ if ( person.getType().equals( PersonType.VIP ) ) {
+ return 2.0f;
+ }
+ else {
+ return 1.0f;
+ }
+ }
+}
+ In a dynam=
ic
+ boost is defined on class level specifying
+ VIPBoostStrategy as implementation of the
+ BoostStrategy interface to be used at indexing
+ time. You can place the @DynamicBoost either at c=
lass
+ or field level. Depending on the placement of the annotation either =
the
+ whole entity is passed to the defineBoost
+ 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 index=
ed
+ values of a VIP person would be double as important as the values of=
a
+ normal person.
+ The specified BoostStrategy
+ implementation must define a public no-arg constructor.
+ Of course you can mix and match @Boost a=
nd
+ @DynamicBoost annotations in your entity. All def=
ined
+ boost factors are cummulative as described in .
+
+
Analyzer
=
--===============3961171440510430238==--