[hibernate-commits] Hibernate SVN: r20690 - in search/trunk/hibernate-search/src/main/docbook/en-US: modules and 1 other directory.

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 +@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 -@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>