From hibernate-commits at lists.jboss.org Tue Dec  2 13:16:47 2008
Content-Type: multipart/mixed; boundary="===============3758354542256176766=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r15643 -
 search/trunk/doc/reference/en/modules.
Date: Tue, 02 Dec 2008 13:16:47 -0500
Message-ID: <E1L7Znj-00029B-0t@committer01.frg.pub.inap.atl.jboss.com>

--===============3758354542256176766==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: hardy.ferentschik
Date: 2008-12-02 13:16:46 -0500 (Tue, 02 Dec 2008)
New Revision: 15643

Modified:
   search/trunk/doc/reference/en/modules/mapping.xml
Log:
added documentation for AnalyzerDiscriminator

Modified: search/trunk/doc/reference/en/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/doc/reference/en/modules/mapping.xml	2008-12-02 16:33:47 U=
TC (rev 15642)
+++ search/trunk/doc/reference/en/modules/mapping.xml	2008-12-02 18:16:46 U=
TC (rev 15643)
@@ -810,6 +810,99 @@
         your IDE to see the implementations available.</para>
       </section>
 =

+      <section>
+        <title>Analyzer discriminator (experimental)</title>
+
+        <para>So far all the different ways to specify an analyzer were
+        static. However, there are usecases where it is useful to select an
+        analyzer depending on the current state of the entity to be indexe=
d,
+        for example in multi language enabled applications. For an BlogEnt=
ry
+        class for example the analyzer could depend on the language proper=
ty
+        of the entry. Depending on this property the correct stemmer can be
+        chosen to index the actual text. </para>
+
+        <para>To enable this dynamic analyzer selection Hibernate Search
+        introduces the <classname>AnalyzerDiscriminator</classname>
+        annotation. The following example demonstrates the usage of this
+        annotation:</para>
+
+        <para><example>
+            <title>Usage of @AnalyzerDiscriminator in order to select an
+            analyzer depending on the entity state</title>
+
+            <programlisting>@Entity
+(a)Indexed
+(a)AnalyzerDefs({
+  @AnalyzerDef(name =3D "en",
+    tokenizer =3D @TokenizerDef(factory =3D StandardTokenizerFactory.class=
),
+    filters =3D {
+      @TokenFilterDef(factory =3D LowerCaseFilterFactory.class),
+      @TokenFilterDef(factory =3D EnglishPorterFilterFactory.class
+      )
+    }),
+  @AnalyzerDef(name =3D "de",
+    tokenizer =3D @TokenizerDef(factory =3D StandardTokenizerFactory.class=
),
+    filters =3D {
+      @TokenFilterDef(factory =3D LowerCaseFilterFactory.class),
+      @TokenFilterDef(factory =3D GermanStemFilterFactory.class)
+    })
+})
+public class BlogEntry {
+
+    @Id
+    @GeneratedValue
+    @DocumentId
+    private Integer id;
+
+    @Field
+    @AnalyzerDiscriminator(impl =3D LanguageDiscriminator.class)
+    private String language;
+    =

+    @Field
+    private String text;
+    =

+    private Set&lt;BlogEntry&gt; references;
+
+    // standard getter/setter
+    ...
+}</programlisting>
+
+            <programlisting>public class LanguageDiscriminator implements =
Discriminator {
+
+    public String getAnanyzerDefinitionName(Object value, Object entity, S=
tring field) {
+        if ( value =3D=3D null || !( entity instanceof Article ) ) {
+            return null;
+        }
+        return (String) value;
+    }
+}</programlisting>
+          </example>The prerequisite for using
+        <classname>@AnalyzerDiscriminator</classname> is that all analyzer
+        which are going to be used are predefined via
+        <classname>@AnalyzerDef</classname> definitions. If this is the ca=
se
+        one can place the <classname>@AnalyzerDiscriminator</classname>
+        annotation either on the class or on a specific property of the en=
tity
+        for which to dynamically select an analyzer. Via the
+        <literal>impl</literal> parameter of the
+        <classname>AnalyzerDiscriminator</classname> you specify a concrete
+        implementation of the <classname>Discriminator</classname> interfa=
ce.
+        It is up to you to provide an implementation for this interface. T=
he
+        only method you have to implement is
+        <classname>getAnanyzerDefinitionName()</classname> which gets call=
ed
+        for each field added to the Lucene document. The entity which is
+        getting indexed is also passed at each call to the interface metho=
d.
+        The <literal>value</literal> parameter is only set if the
+        <classname>AnalyzerDiscriminator</classname> is placed on a proper=
ty
+        instead of class level. In this case the value represents the curr=
ent
+        value of this property.</para>
+
+        <para>The implemention of the interface has to return the name of =
an
+        existing analyzer definition if the analyzer should be set dynamic=
ally
+        or <classname>null</classname> if the default analyzer should be
+        applied. The given example assumes that the language paramter is
+        either 'de' or 'en'.</para>
+      </section>
+
       <section id=3D"analyzer-retrievinganalyzer">
         <title>Retrieving an analyzer</title>
 =



--===============3758354542256176766==--