From hibernate-commits at lists.jboss.org Fri Apr  2 08:33:50 2010
Content-Type: multipart/mixed; boundary="===============6764293357831763250=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r19157 - in search/trunk:
 hibernate-search and 1 other directories.
Date: Fri, 02 Apr 2010 08:33:49 -0400
Message-ID: <201004021233.o32CXnPS021456@svn01.web.mwc.hst.phx2.redhat.com>

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

Author: epbernard
Date: 2010-04-02 08:33:49 -0400 (Fri, 02 Apr 2010)
New Revision: 19157

Modified:
   search/trunk/hibernate-search/pom.xml
   search/trunk/hibernate-search/src/main/docbook/en-US/modules/getting-sta=
rted.xml
   search/trunk/hibernate-search/src/main/docbook/en-US/modules/mapping.xml
   search/trunk/readme.txt
Log:
HSEARCH-428 refresh the geting started guide.

Modified: search/trunk/hibernate-search/pom.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/hibernate-search/pom.xml	2010-04-02 10:06:25 UTC (rev 1915=
6)
+++ search/trunk/hibernate-search/pom.xml	2010-04-02 12:33:49 UTC (rev 1915=
7)
@@ -158,9 +158,9 @@
                     <sourceDocumentName>master.xml</sourceDocumentName>
                     <sourceDirectory>${basedir}/src/main/docbook</sourceDi=
rectory>
                     <masterTranslation>en-US</masterTranslation>
-                    <translations>
+                    <!-- translations>
                         <translation>zh-CN</translation>
-                    </translations>
+                    </translations -->
                     <imageResource>
                         <directory>${basedir}/src/main/docbook/en-US/image=
s</directory>
                     </imageResource>

Modified: search/trunk/hibernate-search/src/main/docbook/en-US/modules/gett=
ing-started.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/hibernate-search/src/main/docbook/en-US/modules/getting-st=
arted.xml	2010-04-02 10:06:25 UTC (rev 19156)
+++ search/trunk/hibernate-search/src/main/docbook/en-US/modules/getting-st=
arted.xml	2010-04-02 12:33:49 UTC (rev 19157)
@@ -3,10 +3,10 @@
 <!--
   ~ Hibernate, Relational Persistence for Idiomatic Java
   ~
-  ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors=
 as
+  ~ Copyright (c) 2010, Red Hat Inc. or third-party contributors as
   ~ indicated by the @author tags or express copyright attribution
   ~ statements applied by the authors.  All third-party contributions are
-  ~ distributed under license by Red Hat Middleware LLC.
+  ~ distributed under license by Red Hat Inc.
   ~
   ~ This copyrighted material is made available to anyone wishing to use, =
modify,
   ~ copy, or redistribute it subject to the terms and conditions of the GNU
@@ -28,10 +28,9 @@
 <!ENTITY version "WORKING">
 ]>
 <chapter id=3D"getting-started">
-
   <title>Getting started</title>
 =

-  <para>Welcome to Hibernate Search! The following chapter will guide you
+  <para>Welcome to Hibernate Search. The following chapter will guide you
   through the initial steps required to integrate Hibernate Search into an
   existing Hibernate enabled application. In case you are a Hibernate new
   timer we recommend you start <ulink
@@ -57,16 +56,14 @@
             <entry>Hibernate Search</entry>
 =

             <entry><literal>hibernate-search.jar</literal> and all runtime
-            dependencies from the <literal>lib</literal> directory of the
-            Hibernate Search distribution. Please refer to
-            <filename>README.txt </filename>in the lib directory to unders=
tand
-            which dependencies are required.</entry>
+            dependencies from the <literal>dist/lib</literal> directory of=
 the
+            Hibernate Search distribution.</entry>
           </row>
 =

           <row>
             <entry>Hibernate Core</entry>
 =

-            <entry>This instructions have been tested against Hibernate 3.=
3.x.
+            <entry>This instructions have been tested against Hibernate 3.=
5.
             You will need <literal>hibernate-core.jar</literal> and its
             transitive dependencies from the <literal>lib</literal> direct=
ory
             of the distribution. Refer to <literal>README.txt</literal> in=
 the
@@ -85,17 +82,15 @@
             has its own set of annotations (<emphasis>@Indexed, @DocumentI=
d,
             @Field,...</emphasis>) for which there exists so far no
             alternative configuration. The tutorial is tested against vers=
ion
-            3.4.x of Hibernate Annotations.</entry>
+            3.5 of Hibernate Annotations (part of the Hibernate Core
+            distribution). </entry>
           </row>
         </tbody>
       </tgroup>
     </table>
 =

-    <para>You can download all dependencies from the Hibernate <ulink
-    url=3D"http://www.hibernate.org/6.html">download site</ulink>. You can=
 also
-    verify the dependency versions against the <ulink
-    url=3D"http://www.hibernate.org/6.html#A3">Hibernate Compatibility
-    Matrix</ulink>.</para>
+    <para>You can download all dependencies from the Hibernate download
+    site.</para>
   </section>
 =

   <section>
@@ -112,14 +107,12 @@
       <title>Adding the JBoss maven repository to
       <filename>settings.xml</filename></title>
 =

-      <programlisting>
-&lt;repository&gt;
+      <programlisting>&lt;repository&gt;
   &lt;id&gt;repository.jboss.org&lt;/id&gt;
   &lt;name&gt;JBoss Maven Repository&lt;/name&gt;
   &lt;url&gt;http://repository.jboss.org/maven2&lt;/url&gt;
   &lt;layout&gt;default&lt;/layout&gt;
-&lt;/repository&gt;
-      </programlisting>
+&lt;/repository&gt;      </programlisting>
     </example>
 =

     <para>Then add the following dependencies to your pom.xml:</para>
@@ -127,54 +120,83 @@
     <example>
       <title>Maven dependencies for Hibernate Search</title>
 =

-      <programlisting>
-&lt;dependency&gt;
+      <programlisting>&lt;dependency&gt;
    &lt;groupId&gt;org.hibernate&lt;/groupId&gt;
    &lt;artifactId&gt;hibernate-search&lt;/artifactId&gt;
    &lt;version&gt;&version;&lt;/version&gt;
 &lt;/dependency&gt;
 &lt;dependency&gt;
    &lt;groupId&gt;org.hibernate&lt;/groupId&gt;
-   &lt;artifactId&gt;hibernate-annotations&lt;/artifactId&gt;
-   &lt;version&gt;3.4.0.GA&lt;/version&gt;
-&lt;/dependency&gt;
-&lt;dependency&gt;
-   &lt;groupId&gt;org.hibernate&lt;/groupId&gt;
    &lt;artifactId&gt;hibernate-entitymanager&lt;/artifactId&gt;
-   &lt;version&gt;3.4.0.GA&lt;/version&gt;
+   &lt;version&gt;3.5.0-Final&lt;/version&gt;
 &lt;/dependency&gt;
 &lt;dependency&gt;
    &lt;groupId&gt;org.apache.solr&lt;/groupId&gt;
-   &lt;artifactId&gt;solr-common&lt;/artifactId&gt;
-   &lt;version&gt;1.3.0&lt;/version&gt;
+   &lt;artifactId&gt;solr-core&lt;/artifactId&gt;
+   &lt;version&gt;1.4.0&lt;/version&gt;
+   &lt;exclusions&gt;
+      &lt;exclusion&gt;
+         &lt;groupId&gt;commons-httpclient&lt;/groupId&gt;
+         &lt;artifactId&gt;commons-httpclient&lt;/artifactId&gt;
+      &lt;/exclusion&gt;
+      &lt;exclusion&gt;
+         &lt;groupId&gt;woodstox&lt;/groupId&gt;
+         &lt;artifactId&gt;wstx-asl&lt;/artifactId&gt;
+      &lt;/exclusion&gt;
+      &lt;exclusion&gt;
+         &lt;groupId&gt;net.java.dev.stax-utils&lt;/groupId&gt;
+         &lt;artifactId&gt;stax-utils&lt;/artifactId&gt;
+      &lt;/exclusion&gt;
+      &lt;exclusion&gt;
+         &lt;groupId&gt;commons-logging&lt;/groupId&gt;
+         &lt;artifactId&gt;commons-logging&lt;/artifactId&gt;
+      &lt;/exclusion&gt;
+      &lt;exclusion&gt;
+         &lt;groupId&gt;org.apache.solr&lt;/groupId&gt;
+         &lt;artifactId&gt;solr-lucene-core&lt;/artifactId&gt;
+      &lt;/exclusion&gt;
+   &lt;/exclusions&gt;
 &lt;/dependency&gt;
 &lt;dependency&gt;
-   &lt;groupId&gt;org.apache.solr&lt;/groupId&gt;
-   &lt;artifactId&gt;solr-core&lt;/artifactId&gt;
-   &lt;version&gt;1.3.0&lt;/version&gt;
+   &lt;groupId&gt;org.apache.lucene&lt;/groupId&gt;
+   &lt;artifactId&gt;lucene-snowball&lt;/artifactId&gt;
+   &lt;version&gt;2.9.2&lt;/version&gt;
 &lt;/dependency&gt;
 &lt;dependency&gt;
    &lt;groupId&gt;org.apache.lucene&lt;/groupId&gt;
    &lt;artifactId&gt;lucene-snowball&lt;/artifactId&gt;
-   &lt;version&gt;2.4.0&lt;/version&gt;
+   &lt;version&gt;2.9.2&lt;/version&gt;
 &lt;/dependency&gt;
-      </programlisting>
+&lt;dependency&gt;
+   &lt;groupId&gt;org.apache.lucene&lt;/groupId&gt;
+   &lt;artifactId&gt;lucene-analyzers&lt;/artifactId&gt;
+   &lt;version&gt;2.9.2&lt;/version&gt;
+&lt;/dependency&gt;</programlisting>
     </example>
 =

     <para>Not all dependencies are required. Only the
     <emphasis>hibernate-search</emphasis> dependency is mandatory. This
     dependency, together with its required transitive dependencies, contain
-    all required classes needed to use Hibernate Search.
-    <emphasis>hibernate-annotations</emphasis> is only needed if you want =
to
-    use annotations to configure your domain model as we do in this tutori=
al.
-    However, even if you choose not to use Hibernate Annotations you still
-    have to use the Hibernate Search specific annotations, which are bundl=
ed
-    with the hibernate-search jar file, to configure your Lucene index.
-    Currently there is no XML configuration available for Hibernate Search.
-    <emphasis>hibernate-entitymanager</emphasis> is required if you want to
-    use Hibernate Search in conjunction with JPA. The Solr dependencies are
-    needed if you want to utilize Solr's analyzer framework. More about th=
is
-    later. And finally, the <literal>lucene-snowball</literal> dependency =
is
+    all required classes needed to use Hibernate Search. </para>
+
+    <para><emphasis>hibernate-annotations</emphasis> is needed if you want=
 to
+    use annotations to configure your domain model but don't want to use J=
PA's
+    runtime APIs. If you choose not to use Hibernate Annotations and descr=
ibe
+    your ORM mapping using <filename>cfg.xml</filename> files, you still h=
ave
+    to use the Hibernate Search specific annotations, which are bundled wi=
th
+    the hibernate-search jar file, to configure your Lucene index. There i=
s no
+    XML configuration available for Hibernate Search but we provide a powe=
rful
+    programmatic mapping API that elegantly replace this kind of deployment
+    descriptor (see <xref linkend=3D"hsearch-mapping-programmaticapi" /> f=
or
+    more information). </para>
+
+    <para><emphasis>hibernate-entitymanager</emphasis> is required if you =
want
+    to use Hibernate Search in conjunction with JPA. </para>
+
+    <para>The Solr dependencies are needed if you want to utilize Solr's
+    analyzer framework. More about this later. </para>
+
+    <para>And finally, the <literal>lucene-snowball</literal> dependency is
     needed if you want to use Lucene's snowball stemmer.</para>
   </section>
 =

@@ -197,14 +219,13 @@
       <literal><filename>hibernate.cfg.xml</filename></literal> or
       <filename>persistence.xml</filename></title>
 =

-      <programlisting>
-...
+      <programlisting>...
 &lt;property name=3D"hibernate.search.default.directory_provider" =

-   value=3D"org.hibernate.search.store.FSDirectoryProvider"/&gt; =

+          value=3D"org.hibernate.search.store.FSDirectoryProvider"/&gt; =

 =

-&lt;property name=3D"hibernate.search.default.indexBase" value=3D"/var/luc=
ene/indexes"/&gt; =

-...
-    </programlisting>
+&lt;property name=3D"hibernate.search.default.indexBase" =

+          value=3D"/var/lucene/indexes"/&gt; =

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

     <para>First you have to tell Hibernate Search which
@@ -234,8 +255,7 @@
       <title>Example entities Book and Author before adding Hibernate Sear=
ch
       specific annotations</title>
 =

-      <programlisting>
-package example;
+      <programlisting>package example;
 ...
 @Entity
 public class Book {
@@ -253,16 +273,13 @@
 =

   private Date publicationDate;
   =

-  public Book() {
-  } =

+  public Book() {} =

   =

   // standard getters/setters follow here
   ...
-} =

-    </programlisting>
+}</programlisting>
 =

-      <programlisting>
-package example;
+      <programlisting>package example;
 ...
 @Entity
 public class Author {
@@ -273,14 +290,11 @@
 =

   private String name;
 =

-  public Author() {
-  } =

+  public Author() {} =

  =

   // standard getters/setters follow here
   ...
-}
-
-</programlisting>
+}</programlisting>
     </example>
 =

     <para>To achieve this you have to add a few annotations to the
@@ -308,7 +322,7 @@
     to do with the ability to search for it. From Lucene's perspective it =
is
     not necessary to keep the data once the index is created. The benefit =
of
     storing it is the ability to retrieve it via projections (<xref
-    linkend=3D"projections" />). </para>
+    linkend=3D"projections" />).</para>
 =

     <para>Without projections, Hibernate Search will per default execute a
     Lucene query in order to find the database identifiers of the entities
@@ -348,8 +362,7 @@
       <title>Example entities after adding Hibernate Search
       annotations</title>
 =

-      <programlisting>
-package example;
+      <programlisting>package example;
 ...
 @Entity
 <emphasis role=3D"bold">@Indexed</emphasis>
@@ -357,7 +370,6 @@
 =

   @Id
   @GeneratedValue
-  <emphasis role=3D"bold">@DocumentId</emphasis>
   private Integer id;
   =

   <emphasis role=3D"bold">@Field(index=3DIndex.TOKENIZED, store=3DStore.NO=
)</emphasis>
@@ -379,11 +391,9 @@
   =

   // standard getters/setters follow here
   ... =

-}
-  </programlisting>
+}</programlisting>
 =

-      <programlisting>
-package example;
+      <programlisting>package example;
 ...
 @Entity
 public class Author {
@@ -400,8 +410,7 @@
  =

   // standard getters/setters follow here
   ...
-}
-  </programlisting>
+}</programlisting>
     </example>
   </section>
 =

@@ -410,25 +419,23 @@
 =

     <para>Hibernate Search will transparently index every entity persisted,
     updated or removed through Hibernate Core. However, you have to trigge=
r an
-    initial indexing to populate the Lucene index with the data already pr=
esent
-    in your database. Once you have added the above properties and annotat=
ions
-    it is time to trigger an initial batch index of your books. You can
-    achieve this by using one of the following code snippets (see also <xr=
ef
-    linkend=3D"search-batchindex" />):</para>
+    initial indexing to populate the Lucene index with the data already
+    present in your database. Once you have added the above properties and
+    annotations it is time to trigger an initial batch index of your books.
+    You can achieve this by using one of the following code snippets (see =
also
+    <xref linkend=3D"search-batchindex" />):</para>
 =

     <example>
       <title>Using Hibernate Session to index data</title>
 =

-      <programlisting>
-FullTextSession fullTextSession =3D Search.getFullTextSession(session);
+      <programlisting>FullTextSession fullTextSession =3D Search.getFullTe=
xtSession(session);
 fullTextSession.createIndexer().startAndWait();</programlisting>
     </example>
 =

     <example>
       <title>Using JPA to index data</title>
 =

-      <programlisting>
-EntityManager em =3D entityManagerFactory.createEntityManager();
+      <programlisting>EntityManager em =3D entityManagerFactory.createEnti=
tyManager();
 FullTextEntityManager fullTextEntityManager =3D Search.getFullTextEntityMa=
nager(em);
 fullTextEntityManager.createIndexer().startAndWait();</programlisting>
     </example>
@@ -448,13 +455,12 @@
     org.hibernate.Query in order to get all the functionality one is used =
to
     from the Hibernate API. The following code will prepare a query against
     the indexed fields, execute it and return a list of
-    <classname>Book</classname>s. </para>
+    <classname>Book</classname>s.</para>
 =

     <example>
       <title>Using Hibernate Session to create and execute a search</title>
 =

-      <programlisting>
-FullTextSession fullTextSession =3D Search.getFullTextSession(session);
+      <programlisting>FullTextSession fullTextSession =3D Search.getFullTe=
xtSession(session);
 Transaction tx =3D fullTextSession.beginTransaction();
 =

 // create native Lucene query
@@ -469,15 +475,13 @@
 List result =3D hibQuery.list();
   =

 tx.commit();
-session.close();  =

-    </programlisting>
+session.close();  </programlisting>
     </example>
 =

     <example>
       <title>Using JPA to create and execute a search</title>
 =

-      <programlisting>
-EntityManager em =3D entityManagerFactory.createEntityManager();
+      <programlisting>EntityManager em =3D entityManagerFactory.createEnti=
tyManager();
 FullTextEntityManager fullTextEntityManager =3D =

     org.hibernate.search.jpa.Search.getFullTextEntityManager(em);
 em.getTransaction().begin();
@@ -494,9 +498,7 @@
 List result =3D persistenceQuery.getResultList();
 =

 em.getTransaction().commit();
-em.close();
-
-    </programlisting>
+em.close();  </programlisting>
     </example>
   </section>
 =

@@ -560,9 +562,7 @@
       <title>Using <classname>@AnalyzerDef</classname> and the Solr framew=
ork
       to define and use an analyzer</title>
 =

-      <programlisting>
-
-package example;
+      <programlisting>package example;
 ...
 @Entity
 @Indexed
@@ -602,9 +602,7 @@
   =

   // standard getters/setters follow here
   ... =

-}
-
-  </programlisting>
+}</programlisting>
     </example>
   </section>
 =

@@ -622,7 +620,7 @@
       <programlisting>mvn archetype:create \ =

     -DarchetypeGroupId=3Dorg.hibernate \
     -DarchetypeArtifactId=3Dhibernate-search-quickstart \ =

-    -DarchetypeVersion=3D3.2.0.Beta1 \
+    -DarchetypeVersion=3D&version; \
     -DgroupId=3Dmy.company -DartifactId=3Dquickstart</programlisting>
     </example>
 =


Modified: search/trunk/hibernate-search/src/main/docbook/en-US/modules/mapp=
ing.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/hibernate-search/src/main/docbook/en-US/modules/mapping.xm=
l	2010-04-02 10:06:25 UTC (rev 19156)
+++ search/trunk/hibernate-search/src/main/docbook/en-US/modules/mapping.xm=
l	2010-04-02 12:33:49 UTC (rev 19157)
@@ -1508,7 +1508,7 @@
     </section>
   </section>
 =

-  <section>
+  <section id=3D"hsearch-mapping-programmaticapi">
     <title>Programmatic API</title>
 =

     <para><warning>
@@ -2221,8 +2221,8 @@
     <section>
       <title>Mapping dynamic boost</title>
 =

-      <para>You can apply a dynamic boost
-      factor on either a field or a whole entity: </para>
+      <para>You can apply a dynamic boost factor on either a field or a wh=
ole
+      entity:</para>
 =

       <example>
         <title>DynamicBoost mapping using programmatic model</title>
@@ -2244,7 +2244,7 @@
 =

         <para>The next example shows the equivalent mapping using the
         <classname>@DynamicBoost</classname> annotation: <example>
-            <title>Using the @DynamicBoost </title>
+            <title>Using the @DynamicBoost</title>
 =

             <programlisting>@Entity
 @Indexed

Modified: search/trunk/readme.txt
=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/readme.txt	2010-04-02 10:06:25 UTC (rev 19156)
+++ search/trunk/readme.txt	2010-04-02 12:33:49 UTC (rev 19157)
@@ -19,7 +19,7 @@
 Instructions
 ------------
 =

-Unzip to installation directory and read docs/manual
+Unzip to installation directory and read the documentation available in di=
st/docs/manual
 =

 =

 Contact


--===============6764293357831763250==--