From hibernate-commits at lists.jboss.org Wed Dec  3 15:10:04 2008
Content-Type: multipart/mixed; boundary="===============7472537210297299958=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r15657 -
 search/trunk/doc/reference/en/modules.
Date: Wed, 03 Dec 2008 15:10:03 -0500
Message-ID: <E1L7y2t-0000QB-U8@committer01.frg.pub.inap.atl.jboss.com>

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

Author: hardy.ferentschik
Date: 2008-12-03 15:10:03 -0500 (Wed, 03 Dec 2008)
New Revision: 15657

Modified:
   search/trunk/doc/reference/en/modules/mapping.xml
Log:
doc update

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-03 16:41:15 U=
TC (rev 15656)
+++ search/trunk/doc/reference/en/modules/mapping.xml	2008-12-03 20:10:03 U=
TC (rev 15657)
@@ -48,11 +48,16 @@
       entities not annotated with <literal>@Indexed</literal> will be igno=
red
       by the indexing process):</para>
 =

-      <programlisting>@Entity
+      <example>
+        <title>Making a class indexable using the
+        <classname>@Indexed</classname> annotation</title>
+
+        <programlisting>@Entity
 <emphasis role=3D"bold">@Indexed(index=3D"indexes/essays")</emphasis>
 public class Essay {
     ...
 }</programlisting>
+      </example>
 =

       <para>The <literal>index</literal> attribute tells Hibernate what the
       Lucene directory name is (usually a directory on your file system). =
It
@@ -189,7 +194,11 @@
       can omit @DocumentId. The chosen entity id will also be used as docu=
ment
       id.</para>
 =

-      <programlisting>@Entity
+      <example>
+        <title>Adding <classname>@DocumentId</classname> ad
+        <classname>@Field</classname> annotations to an indexed entity</ti=
tle>
+
+        <programlisting>@Entity
 @Indexed(index=3D"indexes/essays")
 public class Essay {
     ...
@@ -205,6 +214,7 @@
     <emphasis role=3D"bold">@Field(index=3DIndex.TOKENIZED)</emphasis>
     public String getText() { return text; }
 }</programlisting>
+      </example>
 =

       <para>The above annotations define an index with three fields:
       <literal>id</literal> , <literal>Abstract</literal> and
@@ -222,7 +232,10 @@
       index it twice - once tokenized and once untokenized. @Fields allows=
 to
       achieve this goal.</para>
 =

-      <programlisting>@Entity
+      <example>
+        <title>Using @Fields to map a property multiple times</title>
+
+        <programlisting>@Entity
 @Indexed(index =3D "Book" )
 public class Book {
     <emphasis role=3D"bold">@Fields( {</emphasis>
@@ -235,6 +248,7 @@
 =

     ...
 }</programlisting>
+      </example>
 =

       <para>The field <literal>summary</literal> is indexed twice, once as
       <literal>summary</literal> in a tokenized way, and once as
@@ -267,7 +281,10 @@
       (In the Lucene query parser language, it would translate into
       <code>address.city:Atlanta</code>).</para>
 =

-      <programlisting>@Entity
+      <example>
+        <title>Using @IndexedEmbedded to index associations</title>
+
+        <programlisting>@Entity
 @Indexed
 public class Place {
     @Id
@@ -301,6 +318,7 @@
     private Set&lt;Place&gt; places;
     ...
 }</programlisting>
+      </example>
 =

       <para>In this example, the place fields will be indexed in the
       <literal>Place</literal> index. The <literal>Place</literal> index
@@ -325,7 +343,11 @@
 =

       <para>Let's make our example a bit more complex:</para>
 =

-      <programlisting>@Entity
+      <example>
+        <title>Nested usage of <classname>@IndexedEmbedded</classname> and
+        <classname>@ContainedIn</classname></title>
+
+        <programlisting>@Entity
 @Indexed
 public class Place {
     @Id
@@ -369,6 +391,7 @@
     private String name;
    ...
 }</programlisting>
+      </example>
 =

       <para>Any <literal>@*ToMany, @*ToOne</literal> and
       <literal>@Embedded</literal> attribute can be annotated with
@@ -464,7 +487,11 @@
       can override the object type targeted by Hibernate Search using the
       <methodname>targetElement</methodname> parameter.</para>
 =

-      <programlisting>@Entity
+      <example>
+        <title>Using the <literal>targetElement</literal> property of
+        <classname>@IndexedEmbedded</classname></title>
+
+        <programlisting>@Entity
 @Indexed
 public class Address {
     @Id
@@ -485,6 +512,7 @@
 =

 @Embeddable
 public class Owner implements Person { ... }</programlisting>
+      </example>
     </section>
 =

     <section>
@@ -495,7 +523,11 @@
       during the indexation process. You can use <literal>@Boost</literal>=
 at
       the @Field, method or class level.</para>
 =

-      <programlisting>@Entity
+      <example>
+        <title>Using different ways of increasing the weight of an indexed
+        element using a boost factor</title>
+
+        <programlisting>@Entity
 @Indexed(index=3D"indexes/essays")
 <emphasis role=3D"bold">@Boost(1.7f)</emphasis>
 public class Essay {
@@ -506,7 +538,7 @@
     public Long getId() { return id; }
 =

     @Field(name=3D"Abstract", index=3DIndex.TOKENIZED, store=3DStore.YES, =
boost=3D<emphasis
-          role=3D"bold">@Boost(2f)</emphasis>)
+            role=3D"bold">@Boost(2f)</emphasis>)
     <emphasis role=3D"bold">@Boost(1.5f)</emphasis>
     public String getSummary() { return summary; }
 =

@@ -518,6 +550,7 @@
     public String getISBN() { return isbn; }
 =

 }        </programlisting>
+      </example>
 =

       <para>In our example, <classname>Essay</classname>'s probability to
       reach the top of the search list will be multiplied by 1.7. The
@@ -545,7 +578,10 @@
       even per @Field (useful when multiple fields are indexed from a sing=
le
       property).</para>
 =

-      <programlisting>@Entity
+      <example>
+        <title>Different ways of specifying an analyzer</title>
+
+        <programlisting>@Entity
 @Indexed
 <emphasis role=3D"bold">@Analyzer(impl =3D EntityAnalyzer.class)</emphasis>
 public class MyEntity {
@@ -566,6 +602,7 @@
 =

     ...
 }</programlisting>
+      </example>
 =

       <para>In this example, <classname>EntityAnalyzer</classname> is used=
 to
       index all tokenized properties (eg. <literal>name</literal>), except
@@ -627,7 +664,11 @@
         distribution of Hibernate Search provides these dependecies in its
         <filename>lib</filename> directory.</para>
 =

-        <programlisting>@AnalyzerDef(name=3D"customanalyzer",
+        <example>
+          <title><classname>@AnalyzerDef</classname> and the Solr
+          framework</title>
+
+          <programlisting>@AnalyzerDef(name=3D"customanalyzer",
         tokenizer =3D @TokenizerDef(factory =3D StandardTokenizerFactory.c=
lass),
         filters =3D {
                 @TokenFilterDef(factory =3D ISOLatin1AccentFilterFactory.c=
lass),
@@ -640,6 +681,7 @@
 public class Team {
     ...
 }</programlisting>
+        </example>
 =

         <para>A tokenizer is defined by its factory which is responsible f=
or
         building the tokenizer and using the optional list of parameters. =
This
@@ -660,7 +702,10 @@
         <classname>@Analyzer</classname> declaration using the definition =
name
         rather than declaring an implementation class.</para>
 =

-        <programlisting>@Entity
+        <example>
+          <title>Referencing an analyzer by name</title>
+
+          <programlisting>@Entity
 @Indexed
 @AnalyzerDef(name=3D"customanalyzer", ... )
 public class Team {
@@ -678,6 +723,7 @@
     @Field <emphasis role=3D"bold">@Analyzer(definition =3D "customanalyze=
r")</emphasis>
     private String description;
 }</programlisting>
+        </example>
 =

         <para>Analyzer instances declared by
         <classname>@AnalyzerDef</classname> are available by their name in=
 the
@@ -1093,7 +1139,11 @@
         interface. All implementations have to be thread-safe as they are =
used
         concurrently.</para>
 =

-        <programlisting>/**
+        <example>
+          <title>Implementing your own
+          <classname>StringBridge</classname></title>
+
+          <programlisting>/**
  * Padding Integer bridge.
  * All numbers will be padded with 0 to match 5 digits
  *
@@ -1114,6 +1164,7 @@
         return paddedInteger.append( rawInteger ).toString();
     }
 }                </programlisting>
+        </example>
 =

         <para>Then any property or field can use this bridge thanks to the
         <literal>@FieldBridge</literal> annotation</para>
@@ -1127,9 +1178,12 @@
         parameters are passed through the <literal>@FieldBridge</literal>
         annotation.</para>
 =

-        <programlisting>public class PaddedIntegerBridge implements String=
Bridge, <emphasis
-            role=3D"bold">ParameterizedBridge</emphasis> {
+        <example>
+          <title>Passing parameters to your bridge implementation</title>
 =

+          <programlisting>public class PaddedIntegerBridge implements Stri=
ngBridge, <emphasis
+              role=3D"bold">ParameterizedBridge</emphasis> {
+
     public static String PADDING_PROPERTY =3D "padding";
     private int padding =3D 5; //default
 =

@@ -1156,6 +1210,7 @@
              <emphasis role=3D"bold">params =3D @Parameter(name=3D"padding=
", value=3D"10")</emphasis>
             )
 private Integer length;                </programlisting>
+        </example>
 =

         <para>The <classname>ParameterizedBridge</classname> interface can=
 be
         implemented by <classname>StringBridge</classname> ,
@@ -1174,8 +1229,12 @@
         the object out of it. There is not difference in the way the
         <literal>@FieldBridge</literal> annotation is used.</para>
 =

-        <programlisting>public class PaddedIntegerBridge implements TwoWay=
StringBridge, ParameterizedBridge {
+        <example>
+          <title>Implementing a TwoWayStringBridge which can for example be
+          used for id properties</title>
 =

+          <programlisting>public class PaddedIntegerBridge implements TwoW=
ayStringBridge, ParameterizedBridge {
+
     public static String PADDING_PROPERTY =3D "padding";
     private int padding =3D 5; //default
 =

@@ -1207,6 +1266,7 @@
              params =3D @Parameter(name=3D"padding", value=3D"10") =

 private Integer id;
                 </programlisting>
+        </example>
 =

         <para>It is critically important for the two-way process to be
         idempotent (ie object =3D stringToObject( objectToString( object )=
 )
@@ -1227,7 +1287,11 @@
         <para>You can for example store a given property in two different
         document fields:</para>
 =

-        <programlisting>/**
+        <example>
+          <title>Implementing the FieldBridge interface in order to a given
+          property into multiple document fields</title>
+
+          <programlisting>/**
  * Store the date in 3 different fields - year, month, day - to ease Range=
 Query per
  * year, month or day (eg get all the elements of December for the last 5 =
years).
  * =

@@ -1271,6 +1335,7 @@
 //property
 <emphasis role=3D"bold">@FieldBridge(impl =3D DateSplitBridge.class)</emph=
asis>
 private Date date;                </programlisting>
+        </example>
       </section>
 =

       <section>
@@ -1287,7 +1352,10 @@
         <methodname>termVector</methodname> attribute discussed in section
         <xref linkend=3D"basic-mapping" />.</para>
 =

-        <programlisting>@Entity
+        <example>
+          <title>Implementing a class bridge</title>
+
+          <programlisting>@Entity
 @Indexed
 <emphasis role=3D"bold">@ClassBridge</emphasis>(name=3D"branchnetwork",
              index=3DIndex.TOKENIZED,
@@ -1331,6 +1399,7 @@
         document.add( field );
    }
 }</programlisting>
+        </example>
 =

         <para>In this example, the particular
         <classname>CatFieldsClassBridge</classname> is applied to the
@@ -1366,13 +1435,17 @@
       sure however, to <emphasis>not</emphasis> use this annotation with
       @DocumentId as your system will break.</para>
 =

-      <programlisting>@ProvidedId (bridge =3D org.my.own.package.MyCustomB=
ridge)
+      <example>
+        <title>Providing your own id</title>
+
+        <programlisting>@ProvidedId (bridge =3D org.my.own.package.MyCusto=
mBridge)
 @Indexed
 public class MyClass{
     @Field
     String MyString;
     ...
 }</programlisting>
+      </example>
     </section>
   </section>
 </chapter>


--===============7472537210297299958==--