[hibernate-commits] Hibernate SVN: r14337 - in search/trunk/doc/reference/en: modules and 1 other directory.

[hibernate-commits at lists.jboss.org]

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>@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
+ at 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;
+
+
+    ...
+}
+
+ at 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&lt;BookView&gt; results = (List&lt;BookView&gt;) 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>