From hibernate-commits at lists.jboss.org Thu Sep 23 10:54:29 2010
Content-Type: multipart/mixed; boundary="===============0676285818890610284=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r20691 -
search/trunk/hibernate-search/src/main/docbook/en-US/modules.
Date: Thu, 23 Sep 2010 10:54:29 -0400
Message-ID: <201009231454.o8NEsThL013700@svn01.web.mwc.hst.phx2.redhat.com>
--===============0676285818890610284==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Author: hardy.ferentschik
Date: 2010-09-23 10:54:28 -0400 (Thu, 23 Sep 2010)
New Revision: 20691
Modified:
search/trunk/hibernate-search/src/main/docbook/en-US/modules/advanced-fe=
atures.xml
Log:
HSEARCH-586 made the JMX chapter a monitoring one
Modified: search/trunk/hibernate-search/src/main/docbook/en-US/modules/adva=
nced-features.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- search/trunk/hibernate-search/src/main/docbook/en-US/modules/advanced-f=
eatures.xml 2010-09-23 14:53:58 UTC (rev 20690)
+++ search/trunk/hibernate-search/src/main/docbook/en-US/modules/advanced-f=
eatures.xml 2010-09-23 14:54:28 UTC (rev 20691)
@@ -33,13 +33,13 @@
The SearchFactory object keeps track of t=
he
underlying Lucene resources for Hibernate Search, it's also a convenie=
nt
way to access Lucene natively. The SearchFactory
- can be accessed from a FullTextSession:
+ can be accessed from aFullTextSession:
=
Accessing the <classname>SearchFactory</classname>
=
FullTextSession fullTextSession =3D Search.getFullTe=
xtSession(regularSession);
-SearchFactory searchFactory =3D fullTextSession.getSearchFactory();
+SearchFactory searchFactory =3D fullTextSession.getSearchFactory(); =
=
@@ -53,15 +53,15 @@
DirectoryProviders per indexed class. One direc=
tory
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 DirectoryProvider=
s if
- the index is sharded (see DirectoryProviders=
if
+ the index is sharded (see).
=
Accessing the Lucene <classname>Directory</classname>
=
DirectoryProvider[] provider =3D searchFactory.getDi=
rectoryProviders(Order.class);
-org.apache.lucene.store.Directory directory =3D provider[0].getDirectory()=
;
+org.apache.lucene.store.Directory directory =3D provider[0].getDirectory()=
;
=
In this example, directory points to the lucene index storing
@@ -73,7 +73,7 @@
Using an IndexReader
=
- Queries in Lucene are executed on an IndexReader.
+ Queries in Lucene are executed on anIndexReader.
Hibernate Search caches all index readers to maximize performance. Your
code can access this cached resources, but you have to follow some "go=
od
citizen" rules.
@@ -88,14 +88,14 @@
IndexReader reader =3D readerProvider.openReader(orderProvider, clientProv=
ider);
=
try {
- //do read-only operations on the reader
+ //do read-only operations on the reader
}
finally {
- readerProvider.closeReader(reader);
-}
+ readerProvider.closeReader(reader);
+}
=
- The ReaderProvider (described in The ReaderProvider (described in), will open an Index=
Reader
on top of the index(es) referenced by the directory providers. Because
this IndexReader is shared amongst several clie=
nts,
@@ -130,10 +130,10 @@
methods defined in this class match the factors of the following formu=
la
calculating the score of query q for document d:
=
- score(q,d) =3D coord(q,d) =C2=B7 queryNo=
rm(q) =C2=B7
- =E2=88=91t in q ( tf(t in d) =C2=B7
- idf(t)2 =C2=B7 t.getBoost() =C2=B7 norm(t,d)
- )
+ score(q,d) =3D coord(q,d) =C2=B7 queryNo=
rm(q) =C2=B7 =E2=88=91
+ t in q ( tf(t in d) =C2=B7 idf(t)
+ 2 =C2=B7 t.getBoost() =C2=B7 norm(t,d) )
+
=
@@ -187,7 +187,7 @@
- It is beyond the scope of this manual to explain this
+ It is beyond the scope of this manual to explain th=
is
formula in more detail. Please refer to
Similarity's Javadocs for more information.
=
@@ -198,76 +198,86 @@
hibernate.search.similarity. The default value is
org.apache.lucene.search.DefaultSimilarity.
Additionally you can override the default similarity on class level us=
ing
- the @Similarity annotation.@Entity
+ the @Similarity annotation. @Entity
@Indexed
@Similarity(impl =3D DummySimilarity.class)
public class Book {
- ...
-}As an example, let's assume it is not important how ofte=
n 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 t=
his
- case your custom implementation of the method tf(float
- freq) should return 1.0.
- =
- When two entities share the same index they must declar=
e the
- same Similarity implementation. Classes in the =
same
- class hierarchy always share the index, so it's not allowed to overrid=
e the
- Similarity implementation in a subtype.<=
/warning>
- =
+...
+} As an example, let's assume it is not import=
ant
+ how often a term appears in a document. Documents with a single occurr=
ence
+ of the term should be scored the same as documents with multiple
+ occurrences. In this case your custom implementation of the method
+ tf(float freq) should return 1.0.
+
+
+ When two entities share the same index they must declare the s=
ame
+ Similarity implementation. Classes in the same
+ class hierarchy always share the index, so it's not allowed to overr=
ide
+ the Similarity implementation in a
+ subtype.
+
=
-
- JMX integration
+
+ Monitoring
=
- Hibernate Search offers, similar to Hibernate Core, the ability to
- manage several aspects of Search via JMX. In order to use this functiona=
lity
- you have to set the hibernate.search.jmx_enabled prop=
erty
- in your configuration. Setting this property will give you access to the
- Mbeans StatisticsInfoMBean,
- IndexControlMBean and
- IndexingProgressMonitorMBean. Depending on the
- configuration and state of Search not all beans are available at all tim=
es.
- Lets have a closer look at the different MBeans.
+ Hibernate Search offers access to a
+ Statistics object via
+ SearchFactory.getStatistics(). It allows you =
for
+ example to determine which classes are indexed and how many entities a=
re
+ in the index. This information is always available. However, by specif=
ying
+ the hibernate.search.generate_statistics property in
+ your configuration you can also collect total and average Lucene query=
and
+ object loading timings.
=
-
- StatisticsInfoMBean
+
+ JMX
=
- 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
- hibernate.search.jmx_enabled will automatically
- register the MBean, however query and object loading timings will not =
be
- taken unless you also specify
- hibernate.search.generate_statistics in your
- configuration. The statistics offered by
- StatisticsInfoMBean are also available
- programmatically via SearchFactory.getStatistics().
-
+ You can also enable access to the statistics via JMX. Setting =
the
+ property hibernate.search.jmx_enabled will
+ automatically register the StatisticsInfoMBean.
+ Depending on your the configuration the
+ IndexControlMBean and
+ IndexingProgressMonitorMBean will also be
+ registered. Lets have a closer look at the different MBeans.
+ If you want to access your JMX beans remotely via JConsole
+ make sure to set the system property
+ com.sun.management.jmxremote to
+ true.
+
=
-
- IndexControlMBean
+
+ StatisticsInfoMBean
=
- This MBean allows to build, optimize and purge the index for a g=
iven
- entity. Indexing occurs via the mass indexing API (see ). A requirement for this =
bean
- to be registered in JMX is, that the Hibernate
- SessionFactory is bound to JNDI via the
- hibernate.session_factory_name property. Refer to t=
he
- Hibernate Core manual for more information on how to configure JNDI. T=
he
- IndexControlMBean and its API have to be consid=
ered
- experimental.
-
+ This MBean gives you access to Statistics
+ object as desribed in the previous section.
+
=
-
- IndexingProgressMonitorMBean
+
+ IndexControlMBean
=
- This MBean is an implementation
- MassIndexerProgressMonitor interface. If
- hibernate.search.jmx_enabled is enabled and the mass
- indexer API is used the indexing progress can be followed via this bea=
n.
- The bean will only be bound to JMX while indexing is in progress. Once
- indexing is completed the MBean is not longer available.
+ This MBean allows to build, optimize and purge the index for=
a
+ given entity. Indexing occurs via the mass indexing API (see). A requirement for t=
his
+ bean to be registered in JMX is, that the Hibernate
+ SessionFactory is bound to JNDI via the
+ hibernate.session_factory_name property. Refer =
to
+ the Hibernate Core manual for more information on how to configure
+ JNDI. The IndexControlMBean and its API are=
for
+ now experimental.
+
+
+
+ IndexingProgressMonitorMBean
+
+ This MBean is an implementation
+ MassIndexerProgressMonitor interface. If
+ hibernate.search.jmx_enabled 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.
+
+
- =
-
--===============0676285818890610284==--