Author: epbernard
Date: 2008-02-18 15:50:18 -0500 (Mon, 18 Feb 2008)
New Revision: 14337
Modified:
search/trunk/doc/reference/en/master.xml
search/trunk/doc/reference/en/modules/mapping.xml
search/trunk/doc/reference/en/modules/query.xml
Log:
Documentation updates
Modified: search/trunk/doc/reference/en/master.xml
===================================================================
--- search/trunk/doc/reference/en/master.xml 2008-02-18 19:48:51 UTC (rev 14336)
+++ search/trunk/doc/reference/en/master.xml 2008-02-18 20:50:18 UTC (rev 14337)
@@ -19,7 +19,7 @@
<subtitle>Reference Guide</subtitle>
- <releaseinfo>3.0.0.GA</releaseinfo>
+ <releaseinfo>3.0.1.GA</releaseinfo>
<mediaobject>
<imageobject>
Modified: search/trunk/doc/reference/en/modules/mapping.xml
===================================================================
--- search/trunk/doc/reference/en/modules/mapping.xml 2008-02-18 19:48:51 UTC (rev 14336)
+++ search/trunk/doc/reference/en/modules/mapping.xml 2008-02-18 20:50:18 UTC (rev 14337)
@@ -172,7 +172,10 @@
<para>Associated objects as well as embedded objects can be indexed as
part of the root entity index. It is necessary if you expect to search a
- given entity based on properties of the associated object(s).</para>
+ given entity based on properties of the associated object(s). In the
+ following example, the use case is to return the places whose city is
+ Atlanta (In the Lucene query parser language, it would translate into
+ <code>address.city:Atlanta</code>).</para>
<programlisting>@Entity
@Indexed
@@ -218,12 +221,18 @@
which you will be able to query. This is enabled by the
<literal>@IndexedEmbedded</literal> annotation.</para>
- <para><literal>@ContainedIn</literal> is useful on embedded
objects that
- are also entities (like <literal>Address</literal> in this example):
it
- basically means that when an address entity is updated, the index
- document of the associated <literal>Place</literal>(s), also has to be
- updated.</para>
+ <para>Be careful. Because the data is denormalized in the Lucene index
+ when using the <classname>@IndexedEmbedded</classname> technique,
+ Hibernate Search needs to be aware of any change in the Place object and
+ any change in the Address object to keep the index up to date. To make
+ sure the Place Lucene document is updated when it's Address changes, you
+ need to mark the other side of the birirectional relationship with
+ <classname>(a)ContainedIn</classname>.</para>
+ <para><literal>@ContainedIn</literal> is only useful on
associations
+ pointing to entities as opposed to embedded (collection of)
+ objects.</para>
+
<para>Let's make our example a bit more complex:</para>
<programlisting>@Entity
@@ -356,14 +365,34 @@
index document has to be updated when the associated
<classname>Address</classname> instance is updated.</para>
- <note>
- <para><literal>@IndexedEmbedded</literal> is supported on
collections
- too (ie to index associated object included in collections). But the
- support is only partially implemented. It will depend on how you
- update collections (Check HSEARCH-56 in JIRA for more informations).
- The workaround is to manually index the object
- (session.index())</para>
- </note>
+ <para>Sometimes, the object type annotated by
+ <classname>@IndexedEmbedded</classname> is not the object type
targeted
+ by Hibernate and Hibernate Search especially when interface are used in
+ lieu of their implementation. You can override the object type targeted
+ by Hibernate Search using the <methodname>targetElement</methodname>
+ parameter.</para>
+
+ <programlisting>@Entity
+@Indexed
+public class Address {
+ @Id
+ @GeneratedValue
+ @DocumentId
+ private Long id;
+
+ @Field(index= Index.TOKENIZED)
+ private String street;
+
+ @IndexedEmbedded(depth = 1, prefix = "ownedBy_", <emphasis
role="bold">targetElement = Owner.class</emphasis>)
+ @Target(Owner.class)
+ private Person ownedBy;
+
+
+ ...
+}
+
+@Embeddable
+public class Owner implements Person { ... }</programlisting>
</section>
<section>
Modified: search/trunk/doc/reference/en/modules/query.xml
===================================================================
--- search/trunk/doc/reference/en/modules/query.xml 2008-02-18 19:48:51 UTC (rev 14336)
+++ search/trunk/doc/reference/en/modules/query.xml 2008-02-18 20:50:18 UTC (rev 14337)
@@ -173,7 +173,7 @@
<para>For some use cases, returning the domain object (graph) is
overkill. Only a small subset of the properties is necessary.
- Hibernate Search allows you to return only some properties:</para>
+ Hibernate Search allows you to return a subset of properties:</para>
<programlisting>org.hibernate.search.FullTextQuery query =
s.createFullTextQuery( luceneQuery, Book.class );
query.<emphasis role="bold">setProjection( "id",
"summary", "body", "mainAuthor.name" )</emphasis>;
@@ -253,6 +253,12 @@
<para>FullTextQuery.ID: the id property value of the projected
object</para>
</listitem>
+
+ <listitem>
+ <para>FullTextQuery.DOCUMENT_ID: the Lucene document id. Careful,
+ Lucene document id can change overtime between two different
+ IndexReader opening (this feature is experimental)</para>
+ </listitem>
</itemizedlist>
</section>
</section>
@@ -337,6 +343,30 @@
example).</para>
</note>
</section>
+
+ <section>
+ <title>ResultTransformer</title>
+
+ <para>Especially when using projection, the data structure returned by a
+ query (an object array in this case), is not always matching the
+ application needs. It is possible to apply a
+ <classname>ResultTransformer</classname> operation post query to match
+ the targeted data structure:</para>
+
+ <programlisting>org.hibernate.search.FullTextQuery query =
s.createFullTextQuery( luceneQuery, Book.class );
+query.setProjection( "title", "mainAuthor.name" );
+
+<emphasis role="bold">query.setResultTransformer(
+ new StaticAliasToBeanResultTransformer( BookView.class, "title",
"author" )
+);</emphasis>
+List<BookView> results = (List<BookView>) query.list();
+for(BookView view : results) {
+ log.info( "Book: " + view.getTitle() + ", " + view.getAuthor()
);
+}</programlisting>
+
+ <para>Examples of <classname>ResultTransformer</classname>
+ implementations can be found in the Hibernate Core codebase.</para>
+ </section>
</section>
<section>
Show replies by date