From hibernate-commits at lists.jboss.org Thu Nov 27 12:26:25 2008 Content-Type: multipart/mixed; boundary="===============2930532284285531979==" MIME-Version: 1.0 From: hibernate-commits at lists.jboss.org To: hibernate-commits at lists.jboss.org Subject: [hibernate-commits] Hibernate SVN: r15626 - search/trunk/doc/reference/en/modules. Date: Thu, 27 Nov 2008 12:26:25 -0500 Message-ID: --===============2930532284285531979== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: hardy.ferentschik Date: 2008-11-27 12:26:25 -0500 (Thu, 27 Nov 2008) New Revision: 15626 Modified: search/trunk/doc/reference/en/modules/architecture.xml Log: HSEARCH-303 Modified: search/trunk/doc/reference/en/modules/architecture.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/doc/reference/en/modules/architecture.xml 2008-11-27 13:32= :12 UTC (rev 15625) +++ search/trunk/doc/reference/en/modules/architecture.xml 2008-11-27 17:26= :25 UTC (rev 15626) @@ -22,8 +22,8 @@ ~ 51 Franklin Street, Fifth Floor ~ Boston, MA 02110-1301 USA --> - - = + = @@ -32,14 +32,14 @@
Overview = - Hibernate Search consists of an indexing and an index search eng= ine. - Both are backed by Apache Lucene. + Hibernate Search consists of an indexing component and an index + search component. Both are backed by Apache Lucene. = - When an entity is inserted, updated or removed in/from the datab= ase, - Hibernate Search keeps track of this event (through the Hibernate event - system) and schedules an index update. All the index updates are handl= ed - for you without you having to use the Apache Lucene APIs (see ). + Each time an entity is inserted, updated or removed in/from the + database, Hibernate Search keeps track of this event (through the + Hibernate event system) and schedules an index update. All the index + updates are handled without you having to use the Apache Lucene APIs (= see + ). = To interact with Apache Lucene indexes, Hibernate Search has the notion of DirectoryProviders. A directory provi= der @@ -67,8 +67,8 @@ It is however recommended, for both your database and Hibernate Search, to execute your operation in a transaction be it JDBC or JTA. = When in a transaction, the index update operation is scheduled for the - transaction commit and discarded in case of transaction rollback. The - batching scope is the transaction. There are two immediate + transaction commit phase and discarded in case of transaction rollback. + The batching scope is the transaction. There are two immediate benefits: = @@ -113,101 +113,114 @@ box for two different scenarios. =
- Lucene + Back end types = - In this mode, all index update operations applied on a given n= ode - (JVM) will be executed to the Lucene directories (through the direct= ory - providers) by the same node. This mode is typically used in non - clustered environment or in clustered environments where the directo= ry - store is shared. +
+ Lucene = - - - - + In this mode, all index update operations applied on a given + node (JVM) will be executed to the Lucene directories (through the + directory providers) by the same node. This mode is typically used= in + non clustered environment or in clustered environments where the + directory store is shared. = - - - - + + + + = - This mode targets non clustered applications, or clustered - applications where the Directory is taking care of the locking - strategy. + + + = - The main advantage is simplicity and immediate visibility of t= he - changes in Lucene queries (a requirement is some applications). -
+ + Lucene back end configuration. + + = -
- JMS + This mode targets non clustered applications, or clustered + applications where the Directory is taking care of the locking + strategy. = - All index update operations applied on a given node are sent t= o a - JMS queue. A unique reader will then process the queue and update the - master Lucene index. The master index is then replicated on a regular - basis to the slave copies. This is known as the master / slaves patt= ern. - The master is the sole responsible for updating the Lucene index. The - slaves can accept read as well as write operations. However, they on= ly - process the read operation on their local index copy and delegate the - update operations to the master. + The main advantage is simplicity and immediate visibility of= the + changes in Lucene queries (a requirement in some applications). +
= - - - - +
+ JMS = - - - - + All index update operations applied on a given node are sent= to + a JMS queue. A unique reader will then process the queue and update + the master Lucene index. The master index is then replicated on a + regular basis to the slave copies. This is known as the master / + slaves pattern. The master is the sole responsible for updating the + Lucene index. The slaves can accept read as well as write operatio= ns. + However, they only process the read operation on their local index + copy and delegate the update operations to the master. = - This mode targets clustered environments where throughput is - critical, and index update delays are affordable. Reliability is ens= ured - by the JMS provider and by having the slaves working on a local copy= of - the index. -
+ + + + = - Hibernate Search is an extensible architecture. While not yet pa= rt - of the public API, plugging a third party back end is possible. Feel f= ree - to drop ideas to hibernate-dev(a)lists.jboss.org. -
+ + + = -
- Work execution + + JMS back end configuration. + + = - The indexing work (done by the back end) can be executed - synchronously with the transaction commit (or update operation if out = of - transaction), or asynchronously. + This mode targets clustered environments where throughput is + critical, and index update delays are affordable. Reliability is + ensured by the JMS provider and by having the slaves working on a + local copy of the index. +
= -
- Synchronous - - This is the safe mode where the back end work is executed in - concert with the transaction commit. Under highly concurrent - environment, this can lead to throughput limitations (due to the Apa= che - Lucene lock mechanism) and it can increase the system response time = if - the backend is significantly slower than the transactional process a= nd - if a lot of IO operations are involved. + Hibernate Search is an extensible architecture. Feel free to d= rop + ideas for other third party back ends to + hibernate-dev(a)lists.jboss.org.
=
- Asynchronous + Work execution = - This mode delegates the work done by the back end to a differe= nt - thread. That way, throughput and response time are (to a certain ext= end) - decorrelated from the back end performance. The drawback is that a s= mall - delay appears between the transaction commit and the index update an= d a - small overhead is introduced to deal with thread management. + The indexing work (done by the back end) can be executed + synchronously with the transaction commit (or update operation if ou= t of + transaction), or asynchronously. = - It is recommended to use synchronous execution first and evalu= ate - asynchronous execution if performance problems occur and after having - set up a proper benchmark (ie not a lonely cowboy hitting the system= in - a completely unrealistic way). +
+ Synchronous + + This is the safe mode where the back end work is executed in + concert with the transaction commit. Under highly concurrent + environment, this can lead to throughput limitations (due to the + Apache Lucene lock mechanism) and it can increase the system respo= nse + time if the backend is significantly slower than the transactional + process and if a lot of IO operations are involved. +
+ +
+ Asynchronous + + This mode delegates the work done by the back end to a diffe= rent + thread. That way, throughput and response time are (to a certain + extend) decorrelated from the back end performance. The drawback is + that a small delay appears between the transaction commit and the + index update and a small overhead is introduced to deal with thread + management. + + It is recommended to use synchronous execution first and + evaluate asynchronous execution if performance problems occur and + after having set up a proper benchmark (ie not a lonely cowboy hit= ting + the system in a completely unrealistic way). +
= @@ -228,13 +241,12 @@ multiple queries and threads provided that the IndexReader is still up-to-date. If the IndexReader is not up-to-date, a new one is - opened and provided. Each - IndexReader is made of several - SegmentReaders. This strategy only reopens - segments that have been modified or created after last opening and - shares the already loaded segments from the previous instance. - This strategy is the default. - = + opened and provided. Each IndexReader is made= of + several SegmentReaders. This strategy only + reopens segments that have been modified or created after last openi= ng + and shares the already loaded segments from the previous instance. T= his + strategy is the default. + The name of this strategy is shared. = @@ -259,4 +271,4 @@ implementation must be thread safe. - \ No newline at end of file + --===============2930532284285531979==--