[hibernate-commits] Hibernate SVN: r20690 - in search/trunk/hibernate-search/src/main/docbook/en-US: modules and 1 other directory.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Thu Sep 23 10:53:59 EDT 2010
Author: hardy.ferentschik
Date: 2010-09-23 10:53:58 -0400 (Thu, 23 Sep 2010)
New Revision: 20690
Added:
search/trunk/hibernate-search/src/main/docbook/en-US/modules/advanced-features.xml
Removed:
search/trunk/hibernate-search/src/main/docbook/en-US/modules/jmx.xml
search/trunk/hibernate-search/src/main/docbook/en-US/modules/lucene-native.xml
Modified:
search/trunk/hibernate-search/src/main/docbook/en-US/master.xml
search/trunk/hibernate-search/src/main/docbook/en-US/modules/architecture.xml
search/trunk/hibernate-search/src/main/docbook/en-US/modules/batchindex.xml
search/trunk/hibernate-search/src/main/docbook/en-US/modules/configuration.xml
search/trunk/hibernate-search/src/main/docbook/en-US/modules/getting-started.xml
search/trunk/hibernate-search/src/main/docbook/en-US/modules/mapping.xml
search/trunk/hibernate-search/src/main/docbook/en-US/modules/optimize.xml
search/trunk/hibernate-search/src/main/docbook/en-US/modules/query.xml
Log:
HSEARCH-586 Updated copyright notices and removed obsolete $Id:$. Also removed jmx include file and made chatper part of the advanced features chapter
Modified: search/trunk/hibernate-search/src/main/docbook/en-US/master.xml
===================================================================
--- search/trunk/hibernate-search/src/main/docbook/en-US/master.xml 2010-09-23 11:15:16 UTC (rev 20689)
+++ search/trunk/hibernate-search/src/main/docbook/en-US/master.xml 2010-09-23 14:53:58 UTC (rev 20690)
@@ -2,25 +2,25 @@
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
- ~ Copyright (c) 2008, Red Hat Middleware LLC 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.
+ ~ Copyright (c) 2010, Red Hat, Inc. and/or its affiliates 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, 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
- ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~ 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
+ ~ Lesser General Public License, as published by the Free Software Foundation.
~
- ~ This program is distributed in the hope that it will be useful,
- ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
- ~ for more details.
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ ~ for more details.
~
- ~ You should have received a copy of the GNU Lesser General Public License
- ~ along with this distribution; if not, write to:
- ~ Free Software Foundation, Inc.
- ~ 51 Franklin Street, Fifth Floor
- ~ Boston, MA 02110-1301 USA
+ ~ You should have received a copy of the GNU Lesser General Public License
+ ~ along with this distribution; if not, write to:
+ ~ Free Software Foundation, Inc.
+ ~ 51 Franklin Street, Fifth Floor
+ ~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
@@ -92,9 +92,6 @@
<xi:include href="modules/optimize.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="modules/jmx.xml"
+ <xi:include href="modules/advanced-features.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
-
- <xi:include href="modules/lucene-native.xml"
- xmlns:xi="http://www.w3.org/2001/XInclude" />
</book>
Copied: search/trunk/hibernate-search/src/main/docbook/en-US/modules/advanced-features.xml (from rev 20689, search/trunk/hibernate-search/src/main/docbook/en-US/modules/lucene-native.xml)
===================================================================
--- search/trunk/hibernate-search/src/main/docbook/en-US/modules/advanced-features.xml (rev 0)
+++ search/trunk/hibernate-search/src/main/docbook/en-US/modules/advanced-features.xml 2010-09-23 14:53:58 UTC (rev 20690)
@@ -0,0 +1,273 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ Hibernate, Relational Persistence for Idiomatic Java
+ ~
+ ~ Copyright (c) 2010, Red Hat, Inc. and/or its affiliates 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, 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
+ ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ ~ for more details.
+ ~
+ ~ You should have received a copy of the GNU Lesser General Public License
+ ~ along with this distribution; if not, write to:
+ ~ Free Software Foundation, Inc.
+ ~ 51 Franklin Street, Fifth Floor
+ ~ Boston, MA 02110-1301 USA
+ -->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="search-lucene-native">
+ <title>Advanced features</title>
+
+ <section>
+ <title>SearchFactory</title>
+
+ <para>The <classname>SearchFactory</classname> object keeps track of the
+ underlying Lucene resources for Hibernate Search, it's also a convenient
+ way to access Lucene natively. The <classname>SearchFactory</classname>
+ can be accessed from a <classname>FullTextSession</classname>:</para>
+
+ <example>
+ <title>Accessing the <classname>SearchFactory</classname></title>
+
+ <programlisting>FullTextSession fullTextSession = Search.getFullTextSession(regularSession);
+SearchFactory searchFactory = fullTextSession.getSearchFactory();</programlisting>
+ </example>
+ </section>
+
+ <section>
+ <title>Accessing a Lucene Directory</title>
+
+ <para>You can always access the Lucene directories through plain Lucene,
+ the Directory structure is in no way different with or without Hibernate
+ Search. However there are some more convenient ways to access a given
+ Directory. The <classname>SearchFactory</classname> keeps track of the
+ <classname>DirectoryProvider</classname>s per indexed class. One directory
+ provider can be shared amongst several indexed classes if the classes
+ share the same underlying index directory. While usually not the case, a
+ given entity can have several <classname>DirectoryProvider</classname>s if
+ the index is sharded (see <xref
+ linkend="search-configuration-directory-sharding" />).</para>
+
+ <example>
+ <title>Accessing the Lucene <classname>Directory</classname></title>
+
+ <programlisting>DirectoryProvider[] provider = searchFactory.getDirectoryProviders(Order.class);
+org.apache.lucene.store.Directory directory = provider[0].getDirectory();</programlisting>
+ </example>
+
+ <para>In this example, directory points to the lucene index storing
+ <classname>Order</classname>s information. Note that the obtained Lucene
+ directory must not be closed (this is Hibernate Search
+ responsibility).</para>
+ </section>
+
+ <section>
+ <title>Using an IndexReader</title>
+
+ <para>Queries in Lucene are executed on an <literal>IndexReader</literal>.
+ Hibernate Search caches all index readers to maximize performance. Your
+ code can access this cached resources, but you have to follow some "good
+ citizen" rules.</para>
+
+ <example>
+ <title>Accessing an <classname>IndexReader</classname></title>
+
+ <programlisting>DirectoryProvider orderProvider = searchFactory.getDirectoryProviders(Order.class)[0];
+DirectoryProvider clientProvider = searchFactory.getDirectoryProviders(Client.class)[0];
+
+ReaderProvider readerProvider = searchFactory.getReaderProvider();
+IndexReader reader = readerProvider.openReader(orderProvider, clientProvider);
+
+try {
+ //do read-only operations on the reader
+}
+finally {
+ readerProvider.closeReader(reader);
+}</programlisting>
+ </example>
+
+ <para>The ReaderProvider (described in <xref
+ linkend="search-architecture-readerstrategy" />), will open an IndexReader
+ on top of the index(es) referenced by the directory providers. Because
+ this <classname>IndexReader</classname> is shared amongst several clients,
+ you must adhere to the following rules:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Never call indexReader.close(), but always call
+ readerProvider.closeReader(reader), preferably in a finally
+ block.</para>
+ </listitem>
+
+ <listitem>
+ <para>Don't use this <classname>IndexReader</classname> for
+ modification operations (you would get an exception). If you want to
+ use a read/write index reader, open one from the Lucene Directory
+ object.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Aside from those rules, you can use the IndexReader freely,
+ especially to do native queries. Using the shared
+ <literal>IndexReader</literal>s will make most queries more
+ efficient.</para>
+ </section>
+
+ <section>
+ <title>Customizing Lucene's scoring formula</title>
+
+ <para>Lucene allows the user to customize its scoring formula by extending
+ <classname>org.apache.lucene.search.Similarity</classname>. The abstract
+ methods defined in this class match the factors of the following formula
+ calculating the score of query q for document d:</para>
+
+ <para><emphasis role="bold">score(q,d) = coord(q,d) · queryNorm(q) ·
+ ∑<subscript>t in q</subscript> ( tf(t in d) ·
+ idf(t)<superscript>2</superscript> · t.getBoost() · norm(t,d)
+ )</emphasis></para>
+
+ <para><informaltable align="left" width="">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry align="center">Factor</entry>
+
+ <entry align="center">Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry align="left">tf(t ind)</entry>
+
+ <entry>Term frequency factor for the term (t) in the document
+ (d).</entry>
+ </row>
+
+ <row>
+ <entry align="left">idf(t)</entry>
+
+ <entry>Inverse document frequency of the term.</entry>
+ </row>
+
+ <row>
+ <entry align="left">coord(q,d)</entry>
+
+ <entry>Score factor based on how many of the query terms are
+ found in the specified document.</entry>
+ </row>
+
+ <row>
+ <entry align="left">queryNorm(q)</entry>
+
+ <entry>Normalizing factor used to make scores between queries
+ comparable.</entry>
+ </row>
+
+ <row>
+ <entry align="left">t.getBoost()</entry>
+
+ <entry>Field boost.</entry>
+ </row>
+
+ <row>
+ <entry align="left">norm(t,d)</entry>
+
+ <entry>Encapsulates a few (indexing time) boost and length
+ factors.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>It is beyond the scope of this manual to explain this
+ formula in more detail. Please refer to
+ <classname>Similarity</classname>'s Javadocs for more information.</para>
+
+ <para>Hibernate Search provides two ways to modify Lucene's similarity
+ calculation. First you can set the default similarity by specifying the
+ fully specified classname of your <classname>Similarity</classname>
+ implementation using the property
+ <constant>hibernate.search.similarity</constant>. The default value is
+ <classname>org.apache.lucene.search.DefaultSimilarity</classname>.
+ Additionally you can override the default similarity on class level using
+ the <literal>@Similarity</literal> annotation.<programlisting>@Entity
+ at Indexed
+<emphasis role="bold">@Similarity(impl = DummySimilarity.class)</emphasis>
+public class Book {
+ ...
+}</programlisting>As an example, let's assume it is not important how often a
+ term appears in a document. Documents with a single occurrence of the term
+ should be scored the same as documents with multiple occurrences. In this
+ case your custom implementation of the method <methodname>tf(float
+ freq)</methodname> should return 1.0.</para>
+
+ <warning><para>When two entities share the same index they must declare the
+ same <classname>Similarity</classname> implementation. Classes in the same
+ class hierarchy always share the index, so it's not allowed to override the
+ <classname>Similarity</classname> implementation in a subtype.</para></warning>
+
+ </section>
+
+ <section id="search-jmx">
+ <title>JMX integration</title>
+
+ <para>Hibernate Search offers, similar to Hibernate Core, the ability to
+ manage several aspects of Search via JMX. In order to use this functionality
+ you have to set the <literal>hibernate.search.jmx_enabled</literal> property
+ in your configuration. Setting this property will give you access to the
+ Mbeans <classname>StatisticsInfoMBean</classname>,
+ <classname>IndexControlMBean</classname> and
+ <classname>IndexingProgressMonitorMBean</classname>. Depending on the
+ configuration and state of Search not all beans are available at all times.
+ Lets have a closer look at the different MBeans.</para>
+
+ <section>
+ <title>StatisticsInfoMBean</title>
+
+ <para>This MBean gives you access to information like the total number of
+ indexed entities as well as total and average Lucene query and object
+ loading times. Setting the property
+ <literal>hibernate.search.jmx_enabled</literal> will automatically
+ register the MBean, however query and object loading timings will not be
+ taken unless you also specify
+ <literal>hibernate.search.generate_statistics</literal> in your
+ configuration. The statistics offered by
+ <classname>StatisticsInfoMBean</classname> are also available
+ programmatically via <code>SearchFactory.getStatistics()</code>.</para>
+ </section>
+
+ <section>
+ <title>IndexControlMBean</title>
+
+ <para>This MBean allows to build, optimize and purge the index for a given
+ entity. Indexing occurs via the mass indexing API (see <xref
+ linkend="search-batchindex-massindexer" />). A requirement for this bean
+ to be registered in JMX is, that the Hibernate
+ <classname>SessionFactory</classname> is bound to JNDI via the
+ <literal>hibernate.session_factory_name</literal> property. Refer to the
+ Hibernate Core manual for more information on how to configure JNDI. The
+ <classname>IndexControlMBean</classname> and its API have to be considered
+ experimental.</para>
+ </section>
+
+ <section>
+ <title>IndexingProgressMonitorMBean</title>
+
+ <para>This MBean is an implementation
+ <classname>MassIndexerProgressMonitor</classname> interface. If
+ <literal>hibernate.search.jmx_enabled</literal> is enabled and the mass
+ indexer API is used the indexing progress can be followed via this bean.
+ The bean will only be bound to JMX while indexing is in progress. Once
+ indexing is completed the MBean is not longer available.</para>
+ </section>
+</section>
+
+</chapter>
Modified: search/trunk/hibernate-search/src/main/docbook/en-US/modules/architecture.xml
===================================================================
--- search/trunk/hibernate-search/src/main/docbook/en-US/modules/architecture.xml 2010-09-23 11:15:16 UTC (rev 20689)
+++ search/trunk/hibernate-search/src/main/docbook/en-US/modules/architecture.xml 2010-09-23 14:53:58 UTC (rev 20690)
@@ -2,30 +2,29 @@
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
- ~ Copyright (c) 2008, Red Hat Middleware LLC 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.
+ ~ Copyright (c) 2010, Red Hat, Inc. and/or its affiliates 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, 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
- ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~ 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
+ ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ ~ for more details.
~
- ~ This program is distributed in the hope that it will be useful,
- ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
- ~ for more details.
- ~
- ~ You should have received a copy of the GNU Lesser General Public License
- ~ along with this distribution; if not, write to:
- ~ Free Software Foundation, Inc.
- ~ 51 Franklin Street, Fifth Floor
- ~ Boston, MA 02110-1301 USA
+ ~ You should have received a copy of the GNU Lesser General Public License
+ ~ along with this distribution; if not, write to:
+ ~ Free Software Foundation, Inc.
+ ~ 51 Franklin Street, Fifth Floor
+ ~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="search-architecture">
- <!-- $Id$ -->
<title>Architecture</title>
Modified: search/trunk/hibernate-search/src/main/docbook/en-US/modules/batchindex.xml
===================================================================
--- search/trunk/hibernate-search/src/main/docbook/en-US/modules/batchindex.xml 2010-09-23 11:15:16 UTC (rev 20689)
+++ search/trunk/hibernate-search/src/main/docbook/en-US/modules/batchindex.xml 2010-09-23 14:53:58 UTC (rev 20690)
@@ -2,30 +2,29 @@
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
- ~ Copyright (c) 2008, Red Hat Middleware LLC 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.
+ ~ Copyright (c) 2010, Red Hat, Inc. and/or its affiliates 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, 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
- ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~ 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
+ ~ Lesser General Public License, as published by the Free Software Foundation.
~
- ~ This program is distributed in the hope that it will be useful,
- ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
- ~ for more details.
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ ~ for more details.
~
- ~ You should have received a copy of the GNU Lesser General Public License
- ~ along with this distribution; if not, write to:
- ~ Free Software Foundation, Inc.
- ~ 51 Franklin Street, Fifth Floor
- ~ Boston, MA 02110-1301 USA
+ ~ You should have received a copy of the GNU Lesser General Public License
+ ~ along with this distribution; if not, write to:
+ ~ Free Software Foundation, Inc.
+ ~ 51 Franklin Street, Fifth Floor
+ ~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="manual-index-changes">
- <!-- $Id$ -->
<title>Manual index changes</title>
Modified: search/trunk/hibernate-search/src/main/docbook/en-US/modules/configuration.xml
===================================================================
--- search/trunk/hibernate-search/src/main/docbook/en-US/modules/configuration.xml 2010-09-23 11:15:16 UTC (rev 20689)
+++ search/trunk/hibernate-search/src/main/docbook/en-US/modules/configuration.xml 2010-09-23 14:53:58 UTC (rev 20690)
@@ -2,30 +2,29 @@
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
- ~ Copyright (c) 2008, Red Hat Middleware LLC 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.
+ ~ Copyright (c) 2010, Red Hat, Inc. and/or its affiliates 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, 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
- ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~ 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
+ ~ Lesser General Public License, as published by the Free Software Foundation.
~
- ~ This program is distributed in the hope that it will be useful,
- ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
- ~ for more details.
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ ~ for more details.
~
- ~ You should have received a copy of the GNU Lesser General Public License
- ~ along with this distribution; if not, write to:
- ~ Free Software Foundation, Inc.
- ~ 51 Franklin Street, Fifth Floor
- ~ Boston, MA 02110-1301 USA
+ ~ You should have received a copy of the GNU Lesser General Public License
+ ~ along with this distribution; if not, write to:
+ ~ Free Software Foundation, Inc.
+ ~ 51 Franklin Street, Fifth Floor
+ ~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="search-configuration">
- <!-- $Id$ -->
<title>Configuration</title>
Modified: search/trunk/hibernate-search/src/main/docbook/en-US/modules/getting-started.xml
===================================================================
--- search/trunk/hibernate-search/src/main/docbook/en-US/modules/getting-started.xml 2010-09-23 11:15:16 UTC (rev 20689)
+++ search/trunk/hibernate-search/src/main/docbook/en-US/modules/getting-started.xml 2010-09-23 14:53:58 UTC (rev 20690)
@@ -1,27 +1,26 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!-- $Id$ -->
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
- ~ 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 Inc.
+ ~ Copyright (c) 2010, Red Hat, Inc. and/or its affiliates 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, 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
- ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~ 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
+ ~ Lesser General Public License, as published by the Free Software Foundation.
~
- ~ This program is distributed in the hope that it will be useful,
- ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
- ~ for more details.
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ ~ for more details.
~
- ~ You should have received a copy of the GNU Lesser General Public License
- ~ along with this distribution; if not, write to:
- ~ Free Software Foundation, Inc.
- ~ 51 Franklin Street, Fifth Floor
- ~ Boston, MA 02110-1301 USA
+ ~ You should have received a copy of the GNU Lesser General Public License
+ ~ along with this distribution; if not, write to:
+ ~ Free Software Foundation, Inc.
+ ~ 51 Franklin Street, Fifth Floor
+ ~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
Deleted: search/trunk/hibernate-search/src/main/docbook/en-US/modules/jmx.xml
===================================================================
--- search/trunk/hibernate-search/src/main/docbook/en-US/modules/jmx.xml 2010-09-23 11:15:16 UTC (rev 20689)
+++ search/trunk/hibernate-search/src/main/docbook/en-US/modules/jmx.xml 2010-09-23 14:53:58 UTC (rev 20690)
@@ -1,79 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- ~ Hibernate, Relational Persistence for Idiomatic Java
- ~
- ~ Copyright (c) 2008, Red Hat Middleware LLC 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.
- ~
- ~ 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
- ~ Lesser General Public License, as published by the Free Software Foundation.
- ~
- ~ This program is distributed in the hope that it will be useful,
- ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
- ~ for more details.
- ~
- ~ You should have received a copy of the GNU Lesser General Public License
- ~ along with this distribution; if not, write to:
- ~ Free Software Foundation, Inc.
- ~ 51 Franklin Street, Fifth Floor
- ~ Boston, MA 02110-1301 USA
- -->
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="search-jmx">
- <title>JMX integration</title>
-
- <para>Hibernate Search offers, similar to Hibernate Core, the ability to
- manage several aspects of Search via JMX. In order to use this functionality
- you have to set the <literal>hibernate.search.jmx_enabled</literal> property
- in your configuration. Setting this property will give you access to the
- Mbeans <classname>StatisticsInfoMBean</classname>,
- <classname>IndexControlMBean</classname> and
- <classname>IndexingProgressMonitorMBean</classname>. Depending on the
- configuration and state of Search not all beans are available at all times.
- Lets have a closer look at the different MBeans.</para>
-
- <section>
- <title>StatisticsInfoMBean</title>
-
- <para>This MBean gives you access to information like the total number of
- indexed entities as well as total and average Lucene query and object
- loading times. Setting the property
- <literal>hibernate.search.jmx_enabled</literal> will automatically
- register the MBean, however query and object loading timings will not be
- taken unless you also specify
- <literal>hibernate.search.generate_statistics</literal> in your
- configuration. The statistics offered by
- <classname>StatisticsInfoMBean</classname> are also available
- programmatically via <code>SearchFactory.getStatistics()</code>.</para>
- </section>
-
- <section>
- <title>IndexControlMBean</title>
-
- <para>This MBean allows to build, optimize and purge the index for a given
- entity. Indexing occurs via the mass indexing API (see <xref
- linkend="search-batchindex-massindexer" />). A requirement for this bean
- to be registered in JMX is, that the Hibernate
- <classname>SessionFactory</classname> is bound to JNDI via the
- <literal>hibernate.session_factory_name</literal> property. Refer to the
- Hibernate Core manual for more information on how to configure JNDI. The
- <classname>IndexControlMBean</classname> and its API have to be considered
- experimental.</para>
- </section>
-
- <section>
- <title>IndexingProgressMonitorMBean</title>
-
- <para>This MBean is an implementation
- <classname>MassIndexerProgressMonitor</classname> interface. If
- <literal>hibernate.search.jmx_enabled</literal> is enabled and the mass
- indexer API is used the indexing progress can be followed via this bean.
- The bean will only be bound to JMX while indexing is in progress. Once
- indexing is completed the MBean is not longer available.</para>
- </section>
-</chapter>
Deleted: search/trunk/hibernate-search/src/main/docbook/en-US/modules/lucene-native.xml
===================================================================
--- search/trunk/hibernate-search/src/main/docbook/en-US/modules/lucene-native.xml 2010-09-23 11:15:16 UTC (rev 20689)
+++ search/trunk/hibernate-search/src/main/docbook/en-US/modules/lucene-native.xml 2010-09-23 14:53:58 UTC (rev 20690)
@@ -1,220 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- ~ Hibernate, Relational Persistence for Idiomatic Java
- ~
- ~ Copyright (c) 2008, Red Hat Middleware LLC 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.
- ~
- ~ 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
- ~ Lesser General Public License, as published by the Free Software Foundation.
- ~
- ~ This program is distributed in the hope that it will be useful,
- ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
- ~ for more details.
- ~
- ~ You should have received a copy of the GNU Lesser General Public License
- ~ along with this distribution; if not, write to:
- ~ Free Software Foundation, Inc.
- ~ 51 Franklin Street, Fifth Floor
- ~ Boston, MA 02110-1301 USA
- -->
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="search-lucene-native">
- <!-- $Id$ -->
-
- <title>Advanced features</title>
-
- <section>
- <title>SearchFactory</title>
-
- <para>The <classname>SearchFactory</classname> object keeps track of the
- underlying Lucene resources for Hibernate Search, it's also a convenient
- way to access Lucene natively. The <classname>SearchFactory</classname>
- can be accessed from a <classname>FullTextSession</classname>:</para>
-
- <example>
- <title>Accessing the <classname>SearchFactory</classname></title>
-
- <programlisting>FullTextSession fullTextSession = Search.getFullTextSession(regularSession);
-SearchFactory searchFactory = fullTextSession.getSearchFactory();</programlisting>
- </example>
- </section>
-
- <section>
- <title>Accessing a Lucene Directory</title>
-
- <para>You can always access the Lucene directories through plain Lucene,
- the Directory structure is in no way different with or without Hibernate
- Search. However there are some more convenient ways to access a given
- Directory. The <classname>SearchFactory</classname> keeps track of the
- <classname>DirectoryProvider</classname>s per indexed class. One directory
- provider can be shared amongst several indexed classes if the classes
- share the same underlying index directory. While usually not the case, a
- given entity can have several <classname>DirectoryProvider</classname>s if
- the index is sharded (see <xref
- linkend="search-configuration-directory-sharding" />).</para>
-
- <example>
- <title>Accessing the Lucene <classname>Directory</classname></title>
-
- <programlisting>DirectoryProvider[] provider = searchFactory.getDirectoryProviders(Order.class);
-org.apache.lucene.store.Directory directory = provider[0].getDirectory();</programlisting>
- </example>
-
- <para>In this example, directory points to the lucene index storing
- <classname>Order</classname>s information. Note that the obtained Lucene
- directory must not be closed (this is Hibernate Search
- responsibility).</para>
- </section>
-
- <section>
- <title>Using an IndexReader</title>
-
- <para>Queries in Lucene are executed on an <literal>IndexReader</literal>.
- Hibernate Search caches all index readers to maximize performance. Your
- code can access this cached resources, but you have to follow some "good
- citizen" rules.</para>
-
- <example>
- <title>Accessing an <classname>IndexReader</classname></title>
-
- <programlisting>DirectoryProvider orderProvider = searchFactory.getDirectoryProviders(Order.class)[0];
-DirectoryProvider clientProvider = searchFactory.getDirectoryProviders(Client.class)[0];
-
-ReaderProvider readerProvider = searchFactory.getReaderProvider();
-IndexReader reader = readerProvider.openReader(orderProvider, clientProvider);
-
-try {
- //do read-only operations on the reader
-}
-finally {
- readerProvider.closeReader(reader);
-}</programlisting>
- </example>
-
- <para>The ReaderProvider (described in <xref
- linkend="search-architecture-readerstrategy" />), will open an IndexReader
- on top of the index(es) referenced by the directory providers. Because
- this <classname>IndexReader</classname> is shared amongst several clients,
- you must adhere to the following rules:</para>
-
- <itemizedlist>
- <listitem>
- <para>Never call indexReader.close(), but always call
- readerProvider.closeReader(reader), preferably in a finally
- block.</para>
- </listitem>
-
- <listitem>
- <para>Don't use this <classname>IndexReader</classname> for
- modification operations (you would get an exception). If you want to
- use a read/write index reader, open one from the Lucene Directory
- object.</para>
- </listitem>
- </itemizedlist>
-
- <para>Aside from those rules, you can use the IndexReader freely,
- especially to do native queries. Using the shared
- <literal>IndexReader</literal>s will make most queries more
- efficient.</para>
- </section>
-
- <section>
- <title>Customizing Lucene's scoring formula</title>
-
- <para>Lucene allows the user to customize its scoring formula by extending
- <classname>org.apache.lucene.search.Similarity</classname>. The abstract
- methods defined in this class match the factors of the following formula
- calculating the score of query q for document d:</para>
-
- <para><emphasis role="bold">score(q,d) = coord(q,d) · queryNorm(q) ·
- ∑<subscript>t in q</subscript> ( tf(t in d) ·
- idf(t)<superscript>2</superscript> · t.getBoost() · norm(t,d)
- )</emphasis></para>
-
- <para><informaltable align="left" width="">
- <tgroup cols="2">
- <thead>
- <row>
- <entry align="center">Factor</entry>
-
- <entry align="center">Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry align="left">tf(t ind)</entry>
-
- <entry>Term frequency factor for the term (t) in the document
- (d).</entry>
- </row>
-
- <row>
- <entry align="left">idf(t)</entry>
-
- <entry>Inverse document frequency of the term.</entry>
- </row>
-
- <row>
- <entry align="left">coord(q,d)</entry>
-
- <entry>Score factor based on how many of the query terms are
- found in the specified document.</entry>
- </row>
-
- <row>
- <entry align="left">queryNorm(q)</entry>
-
- <entry>Normalizing factor used to make scores between queries
- comparable.</entry>
- </row>
-
- <row>
- <entry align="left">t.getBoost()</entry>
-
- <entry>Field boost.</entry>
- </row>
-
- <row>
- <entry align="left">norm(t,d)</entry>
-
- <entry>Encapsulates a few (indexing time) boost and length
- factors.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>It is beyond the scope of this manual to explain this
- formula in more detail. Please refer to
- <classname>Similarity</classname>'s Javadocs for more information.</para>
-
- <para>Hibernate Search provides two ways to modify Lucene's similarity
- calculation. First you can set the default similarity by specifying the
- fully specified classname of your <classname>Similarity</classname>
- implementation using the property
- <constant>hibernate.search.similarity</constant>. The default value is
- <classname>org.apache.lucene.search.DefaultSimilarity</classname>.
- Additionally you can override the default similarity on class level using
- the <literal>@Similarity</literal> annotation.<programlisting>@Entity
- at Indexed
-<emphasis role="bold">@Similarity(impl = DummySimilarity.class)</emphasis>
-public class Book {
- ...
-}</programlisting>As an example, let's assume it is not important how often a
- term appears in a document. Documents with a single occurrence of the term
- should be scored the same as documents with multiple occurrences. In this
- case your custom implementation of the method <methodname>tf(float
- freq)</methodname> should return 1.0.</para>
-
- <warning><para>When two entities share the same index they must declare the
- same <classname>Similarity</classname> implementation. Classes in the same
- class hierarchy always share the index, so it's not allowed to override the
- <classname>Similarity</classname> implementation in a subtype.</para></warning>
-
- </section>
-</chapter>
Modified: search/trunk/hibernate-search/src/main/docbook/en-US/modules/mapping.xml
===================================================================
--- search/trunk/hibernate-search/src/main/docbook/en-US/modules/mapping.xml 2010-09-23 11:15:16 UTC (rev 20689)
+++ search/trunk/hibernate-search/src/main/docbook/en-US/modules/mapping.xml 2010-09-23 14:53:58 UTC (rev 20690)
@@ -2,30 +2,29 @@
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
- ~ Copyright (c) 2008, Red Hat Middleware LLC 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.
+ ~ Copyright (c) 2010, Red Hat, Inc. and/or its affiliates 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, 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
- ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~ 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
+ ~ Lesser General Public License, as published by the Free Software Foundation.
~
- ~ This program is distributed in the hope that it will be useful,
- ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
- ~ for more details.
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ ~ for more details.
~
- ~ You should have received a copy of the GNU Lesser General Public License
- ~ along with this distribution; if not, write to:
- ~ Free Software Foundation, Inc.
- ~ 51 Franklin Street, Fifth Floor
- ~ Boston, MA 02110-1301 USA
+ ~ You should have received a copy of the GNU Lesser General Public License
+ ~ along with this distribution; if not, write to:
+ ~ Free Software Foundation, Inc.
+ ~ 51 Franklin Street, Fifth Floor
+ ~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="search-mapping" revision="3">
- <!-- $Id$ -->
<title>Mapping entities to the index structure</title>
Modified: search/trunk/hibernate-search/src/main/docbook/en-US/modules/optimize.xml
===================================================================
--- search/trunk/hibernate-search/src/main/docbook/en-US/modules/optimize.xml 2010-09-23 11:15:16 UTC (rev 20689)
+++ search/trunk/hibernate-search/src/main/docbook/en-US/modules/optimize.xml 2010-09-23 14:53:58 UTC (rev 20690)
@@ -2,30 +2,29 @@
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
- ~ Copyright (c) 2008, Red Hat Middleware LLC 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.
+ ~ Copyright (c) 2010, Red Hat, Inc. and/or its affiliates 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, 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
- ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~ 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
+ ~ Lesser General Public License, as published by the Free Software Foundation.
~
- ~ This program is distributed in the hope that it will be useful,
- ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
- ~ for more details.
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ ~ for more details.
~
- ~ You should have received a copy of the GNU Lesser General Public License
- ~ along with this distribution; if not, write to:
- ~ Free Software Foundation, Inc.
- ~ 51 Franklin Street, Fifth Floor
- ~ Boston, MA 02110-1301 USA
+ ~ You should have received a copy of the GNU Lesser General Public License
+ ~ along with this distribution; if not, write to:
+ ~ Free Software Foundation, Inc.
+ ~ 51 Franklin Street, Fifth Floor
+ ~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="search-optimize">
- <!-- $Id$ -->
<title>Index Optimization</title>
Modified: search/trunk/hibernate-search/src/main/docbook/en-US/modules/query.xml
===================================================================
--- search/trunk/hibernate-search/src/main/docbook/en-US/modules/query.xml 2010-09-23 11:15:16 UTC (rev 20689)
+++ search/trunk/hibernate-search/src/main/docbook/en-US/modules/query.xml 2010-09-23 14:53:58 UTC (rev 20690)
@@ -2,30 +2,29 @@
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
- ~ Copyright (c) 2008, Red Hat Middleware LLC 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.
+ ~ Copyright (c) 2010, Red Hat, Inc. and/or its affiliates 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, 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
- ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~ 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
+ ~ Lesser General Public License, as published by the Free Software Foundation.
~
- ~ This program is distributed in the hope that it will be useful,
- ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
- ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
- ~ for more details.
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ ~ for more details.
~
- ~ You should have received a copy of the GNU Lesser General Public License
- ~ along with this distribution; if not, write to:
- ~ Free Software Foundation, Inc.
- ~ 51 Franklin Street, Fifth Floor
- ~ Boston, MA 02110-1301 USA
+ ~ You should have received a copy of the GNU Lesser General Public License
+ ~ along with this distribution; if not, write to:
+ ~ Free Software Foundation, Inc.
+ ~ 51 Franklin Street, Fifth Floor
+ ~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="search-query" xreflabel="Querying">
- <!-- $Id$ -->
<title>Querying</title>
More information about the hibernate-commits
mailing list