[hibernate-commits] Hibernate SVN: r15657 - search/trunk/doc/reference/en/modules.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Wed Dec 3 15:10:03 EST 2008
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
===================================================================
--- search/trunk/doc/reference/en/modules/mapping.xml 2008-12-03 16:41:15 UTC (rev 15656)
+++ search/trunk/doc/reference/en/modules/mapping.xml 2008-12-03 20:10:03 UTC (rev 15657)
@@ -48,11 +48,16 @@
entities not annotated with <literal>@Indexed</literal> will be ignored
by the indexing process):</para>
- <programlisting>@Entity
+ <example>
+ <title>Making a class indexable using the
+ <classname>@Indexed</classname> annotation</title>
+
+ <programlisting>@Entity
<emphasis role="bold">@Indexed(index="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 document
id.</para>
- <programlisting>@Entity
+ <example>
+ <title>Adding <classname>@DocumentId</classname> ad
+ <classname>@Field</classname> annotations to an indexed entity</title>
+
+ <programlisting>@Entity
@Indexed(index="indexes/essays")
public class Essay {
...
@@ -205,6 +214,7 @@
<emphasis role="bold">@Field(index=Index.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 = "Book" )
public class Book {
<emphasis role="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<Place> 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="indexes/essays")
<emphasis role="bold">@Boost(1.7f)</emphasis>
public class Essay {
@@ -506,7 +538,7 @@
public Long getId() { return id; }
@Field(name="Abstract", index=Index.TOKENIZED, store=Store.YES, boost=<emphasis
- role="bold">@Boost(2f)</emphasis>)
+ role="bold">@Boost(2f)</emphasis>)
<emphasis role="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 single
property).</para>
- <programlisting>@Entity
+ <example>
+ <title>Different ways of specifying an analyzer</title>
+
+ <programlisting>@Entity
@Indexed
<emphasis role="bold">@Analyzer(impl = 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="customanalyzer",
+ <example>
+ <title><classname>@AnalyzerDef</classname> and the Solr
+ framework</title>
+
+ <programlisting>@AnalyzerDef(name="customanalyzer",
tokenizer = @TokenizerDef(factory = StandardTokenizerFactory.class),
filters = {
@TokenFilterDef(factory = ISOLatin1AccentFilterFactory.class),
@@ -640,6 +681,7 @@
public class Team {
...
}</programlisting>
+ </example>
<para>A tokenizer is defined by its factory which is responsible for
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="customanalyzer", ... )
public class Team {
@@ -678,6 +723,7 @@
@Field <emphasis role="bold">@Analyzer(definition = "customanalyzer")</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 StringBridge, <emphasis
- role="bold">ParameterizedBridge</emphasis> {
+ <example>
+ <title>Passing parameters to your bridge implementation</title>
+ <programlisting>public class PaddedIntegerBridge implements StringBridge, <emphasis
+ role="bold">ParameterizedBridge</emphasis> {
+
public static String PADDING_PROPERTY = "padding";
private int padding = 5; //default
@@ -1156,6 +1210,7 @@
<emphasis role="bold">params = @Parameter(name="padding", value="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 TwoWayStringBridge, ParameterizedBridge {
+ <example>
+ <title>Implementing a TwoWayStringBridge which can for example be
+ used for id properties</title>
+ <programlisting>public class PaddedIntegerBridge implements TwoWayStringBridge, ParameterizedBridge {
+
public static String PADDING_PROPERTY = "padding";
private int padding = 5; //default
@@ -1207,6 +1266,7 @@
params = @Parameter(name="padding", value="10")
private Integer id;
</programlisting>
+ </example>
<para>It is critically important for the two-way process to be
idempotent (ie object = 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="bold">@FieldBridge(impl = DateSplitBridge.class)</emphasis>
private Date date; </programlisting>
+ </example>
</section>
<section>
@@ -1287,7 +1352,10 @@
<methodname>termVector</methodname> attribute discussed in section
<xref linkend="basic-mapping" />.</para>
- <programlisting>@Entity
+ <example>
+ <title>Implementing a class bridge</title>
+
+ <programlisting>@Entity
@Indexed
<emphasis role="bold">@ClassBridge</emphasis>(name="branchnetwork",
index=Index.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 = org.my.own.package.MyCustomBridge)
+ <example>
+ <title>Providing your own id</title>
+
+ <programlisting>@ProvidedId (bridge = org.my.own.package.MyCustomBridge)
@Indexed
public class MyClass{
@Field
String MyString;
...
}</programlisting>
+ </example>
</section>
</section>
</chapter>
More information about the hibernate-commits
mailing list