[hibernate-commits] Hibernate SVN: r16575 - search/branches/Branch_3_1/src/main/docbook/en-US/modules.

Author: sannegrinovero Date: 2009-05-16 05:54:26 -0400 (Sat, 16 May 2009) New Revision: 16575 Modified: search/branches/Branch_3_1/src/main/docbook/en-US/modules/architecture.xml search/branches/Branch_3_1/src/main/docbook/en-US/modules/configuration.xml search/branches/Branch_3_1/src/main/docbook/en-US/modules/getting-started.xml search/branches/Branch_3_1/src/main/docbook/en-US/modules/lucene-native.xml search/branches/Branch_3_1/src/main/docbook/en-US/modules/mapping.xml search/branches/Branch_3_1/src/main/docbook/en-US/modules/optimize.xml search/branches/Branch_3_1/src/main/docbook/en-US/modules/query.xml Log: HSEARCH-369 Running a spellchecker on documentation Modified: search/branches/Branch_3_1/src/main/docbook/en-US/modules/architecture.xml =================================================================== --- search/branches/Branch_3_1/src/main/docbook/en-US/modules/architecture.xml 2009-05-16 09:47:42 UTC (rev 16574) +++ search/branches/Branch_3_1/src/main/docbook/en-US/modules/architecture.xml 2009-05-16 09:54:26 UTC (rev 16575) @@ -219,7 +219,7 @@ <title>Reader strategy</title> <para>When executing a query, Hibernate Search interacts with the Apache - Lucene indexes through a reader strategy. chosing a reader strategy will + Lucene indexes through a reader strategy. Choosing a reader strategy will depend on the profile of the application (frequent updates, read mostly, asynchronous index update etc). See also <xref linkend="configuration-reader-strategy" /></para> Modified: search/branches/Branch_3_1/src/main/docbook/en-US/modules/configuration.xml =================================================================== --- search/branches/Branch_3_1/src/main/docbook/en-US/modules/configuration.xml 2009-05-16 09:47:42 UTC (rev 16574) +++ search/branches/Branch_3_1/src/main/docbook/en-US/modules/configuration.xml 2009-05-16 09:54:26 UTC (rev 16575) @@ -312,8 +312,8 @@ “Animal”. Both entities will then be stored in the Animal directory</para> - <para><programlisting><code>hibernate.search.org.hibernate.search.test.shards.Furniture.indexName = Aninal -hibernate.search.org.hibernate.search.test.shards.Animal.indexName = Aninal</code></programlisting></para> + <para><programlisting><code>hibernate.search.org.hibernate.search.test.shards.Furniture.indexName = Animal +hibernate.search.org.hibernate.search.test.shards.Animal.indexName = Animal</code></programlisting></para> </listitem> <listitem> @@ -366,7 +366,7 @@ <row> <entry><literal>hibernate.search.worker.execution</literal></entry> - <entry>Supports synchronous and asynchrounous execution. Default + <entry>Supports synchronous and asynchronous execution. Default to <literal><literal>sync</literal></literal>. Supports also <literal>async</literal>.</entry> </row> @@ -375,14 +375,14 @@ <entry><literal>hibernate.search.worker.thread_pool.size</literal></entry> <entry>Defines the number of threads in the pool. useful only for - asynchrounous execution. Default to 1.</entry> + asynchronous execution. Default to 1.</entry> </row> <row> <entry><literal>hibernate.search.worker.buffer_queue.max</literal></entry> <entry>Defines the maximal number of work queue if the thread poll - is starved. Useful only for asynchrounous execution. Default to + is starved. Useful only for asynchronous execution. Default to infinite. If the limit is reached, the work is done by the main thread.</entry> </row> @@ -439,7 +439,7 @@ <section> <title>Slave nodes</title> - <para>Every index update operation is sent to a JMS queue. Index quering + <para>Every index update operation is sent to a JMS queue. Index querying operations are executed on a local index copy.</para> <example> @@ -763,7 +763,7 @@ terms.</para> <para>This silently truncates large documents, excluding from the index all terms that occur further in the document. If you know your source documents are large, be sure to - set this value high enough to accomodate the expected size. If you + set this value high enough to accommodate the expected size. If you set it to Integer.MAX_VALUE, then the only limit is your memory, but you should anticipate an OutOfMemoryError. </para> <para>If setting this value in <literal>batch</literal> differently than in @@ -789,13 +789,13 @@ <entry><literal>hibernate.search.[default|&lt;indexname&gt;].indexwriter.[transaction|batch].merge_factor</literal></entry> <entry><para>Controls segment merge frequency and size. </para> - <para>Determines how often segment indices are merged when + <para>Determines how often segment indexes are merged when insertion occurs. With smaller values, less RAM is used while - indexing, and searches on unoptimized indices are faster, but + indexing, and searches on unoptimized indexes are faster, but indexing speed is slower. With larger values, more RAM is used - during indexing, and while searches on unoptimized indices are + during indexing, and while searches on unoptimized indexes are slower, indexing is faster. Thus larger values (&gt; 10) are best - for batch index creation, and smaller values (&lt; 10) for indices + for batch index creation, and smaller values (&lt; 10) for indexes that are interactively maintained. The value must no be lower than 2.</para></entry> Modified: search/branches/Branch_3_1/src/main/docbook/en-US/modules/getting-started.xml =================================================================== --- search/branches/Branch_3_1/src/main/docbook/en-US/modules/getting-started.xml 2009-05-16 09:47:42 UTC (rev 16574) +++ search/branches/Branch_3_1/src/main/docbook/en-US/modules/getting-started.xml 2009-05-16 09:54:26 UTC (rev 16575) @@ -160,7 +160,7 @@ </example> <para>Not all dependencies are required. Only the - <emphasis>hibernate-search</emphasis> dependeny is mandatory. This + <emphasis>hibernate-search</emphasis> dependency is mandatory. This dependency, together with its required transitive dependencies, contain all required classes needed to use Hibernate Search. <emphasis>hibernate-annotations</emphasis> is only needed if you want to @@ -173,7 +173,7 @@ use Hibernate Search in conjunction with JPA. The Solr dependencies are needed if you want to utilize Solr's analyzer framework. More about this later. And finally, the <literal>lucene-snowball</literal> dependency is - needed if you want to utililze Lucene's snowball stemmer.</para> + needed if you want to use Lucene's snowball stemmer.</para> </section> <section> @@ -230,7 +230,7 @@ <example> <title>Example entities Book and Author before adding Hibernate Search - specific annotatons</title> + specific annotations</title> <programlisting> package example; @@ -336,7 +336,7 @@ searchable you have to make sure that the names are indexed as part of the book itself. On top of <literal>@IndexedEmbedded</literal> you will also have to mark all fields of the associated entity you want to have included - in the index with <literal>@Indexed</literal>. For more dedails see <xref + in the index with <literal>@Indexed</literal>. For more details see <xref linkend="search-mapping-associated" />.</para> <para>These settings should be sufficient for now. For more details on @@ -408,10 +408,10 @@ <para>Hibernate Search will transparently index every entity persisted, updated or removed through Hibernate Core. However, you have to trigger an - inital indexing to populate the Lucene index with the data already present + initial indexing to populate the Lucene index with the data already present in your database. Once you have added the above properties and annotations it is time to trigger an initial batch index of your books. You can - achieve this by using one of the following code snipplets (see also <xref + achieve this by using one of the following code snippets (see also <xref linkend="search-batchindex" />):</para> <example> @@ -634,7 +634,7 @@ populated with the example code of this tutorial.</para> <example> - <title>Using the maven achetype to create tutorial sources</title> + <title>Using the Maven archetype to create tutorial sources</title> <programlisting>mvn archetype:create \ -DarchetypeGroupId=org.hibernate \ Modified: search/branches/Branch_3_1/src/main/docbook/en-US/modules/lucene-native.xml =================================================================== --- search/branches/Branch_3_1/src/main/docbook/en-US/modules/lucene-native.xml 2009-05-16 09:47:42 UTC (rev 16574) +++ search/branches/Branch_3_1/src/main/docbook/en-US/modules/lucene-native.xml 2009-05-16 09:54:26 UTC (rev 16575) @@ -81,7 +81,7 @@ citizen" rules.</para> <example> - <title>Accesing an <classname>IndexReader</classname></title> + <title>Accessing an <classname>IndexReader</classname></title> <programlisting>DirectoryProvider orderProvider = searchFactory.getDirectoryProviders(Order.class)[0]; DirectoryProvider clientProvider = searchFactory.getDirectoryProviders(Client.class)[0]; @@ -129,7 +129,7 @@ <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 follownig formula + 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) · @@ -205,7 +205,7 @@ <emphasis role="bold">@Similarity(impl = DummySimilarity.class)</emphasis> public class Book { ... -}</programlisting>As an exmaple, let's assume it is not important how often a +}</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 Modified: search/branches/Branch_3_1/src/main/docbook/en-US/modules/mapping.xml =================================================================== --- search/branches/Branch_3_1/src/main/docbook/en-US/modules/mapping.xml 2009-05-16 09:47:42 UTC (rev 16574) +++ search/branches/Branch_3_1/src/main/docbook/en-US/modules/mapping.xml 2009-05-16 09:54:26 UTC (rev 16575) @@ -73,7 +73,7 @@ <para>For each property (or attribute) of your entity, you have the ability to describe how it will be indexed. The default (no annotation - present) means that the property is completly ignored by the indexing + present) means that the property is completely ignored by the indexing process. <literal>@Field</literal> does declare a property as indexed. When indexing an element to a Lucene document you can specify how it is indexed:</para> @@ -88,7 +88,7 @@ <listitem> <para><literal>store</literal> : describe whether or not the property is stored in the Lucene index. You can store the value - <literal>Store.YES</literal> (comsuming more space in the index but + <literal>Store.YES</literal> (consuming more space in the index but allowing projection, see <xref linkend="projections" /> for more information), store it in a compressed way <literal>Store.COMPRESS</literal> (this does consume more CPU), or @@ -103,8 +103,8 @@ information store. The different values are <literal>Index.NO</literal> (no indexing, ie cannot be found by a query), <literal>Index.TOKENIZED</literal> (use an analyzer to - process the property), <literal>Index.UN_TOKENISED</literal> (no - analyzer pre processing), <literal>Index.NO_NORM</literal> (do not + process the property), <literal>Index.UN_TOKENIZED</literal> (no + analyzer pre-processing), <literal>Index.NO_NORMS</literal> (do not store the normalization data). The default value is <literal>TOKENIZED</literal>.</para> </listitem> @@ -162,7 +162,7 @@ <row> <entry - align="left">TermVector.WITH_POSITIONS_OFFSETS</entry> + align="left">TermVector.WITH_POSITION_OFFSETS</entry> <entry>Store the term vector, token position and offset information. This is a combination of the YES, WITH_OFFSETS @@ -275,7 +275,7 @@ <title>Embedded and associated objects</title> <para>Associated objects as well as embedded objects can be indexed as - part of the root entity index. This is ueful if you expect to search a + part of the root entity index. This is useful if you expect to search a given entity based on properties of associated objects. In the following example the aim is to return places where the associated city is Atlanta (In the Lucene query parser language, it would translate into @@ -334,7 +334,7 @@ <classname>Address</classname> object to keep the index up to date. To make sure the <literal><classname>Place</classname></literal> Lucene document is updated when it's <classname>Address</classname> changes, - you need to mark the other side of the birirectional relationship with + you need to mark the other side of the bidirectional relationship with <classname&gt;(a)ContainedIn&lt;/classname&gt;.&lt;/para&gt; <para><literal>@ContainedIn</literal> is only useful on associations @@ -417,7 +417,7 @@ </listitem> <listitem> - <para>addess.ownedBy_name</para> + <para>address.ownedBy_name</para> </listitem> </itemizedlist> @@ -434,7 +434,7 @@ graph contains a cyclic dependency of classes (not instances). For example, if <classname>Owner</classname> points to <classname>Place</classname>. Hibernate Search will stop including - Indexed embedded atttributes after reaching the expected depth (or the + Indexed embedded attributes after reaching the expected depth (or the object graph boundaries are reached). A class having a self reference is an example of cyclic dependency. In our example, because <literal>depth</literal> is set to 1, any @@ -519,7 +519,7 @@ <title>Boost factor</title> <para>Lucene has the notion of <emphasis>boost factor</emphasis>. It's a - way to give more weigth to a field or to an indexed element over others + way to give more weight to a field or to an indexed element over others during the indexation process. You can use <literal>@Boost</literal> at the @Field, method or class level.</para> @@ -649,7 +649,7 @@ <para>This separation of tasks - a tokenizer followed by a list of filters - allows for easy reuse of each individual component and let you build your customized analyzer in a very flexible way (just like - lego). Generally speaking the <classname>Tokenizer</classname> starts + Lego). Generally speaking the <classname>Tokenizer</classname> starts the analysis process by turning the character input into tokens which are then further processed by the <classname>TokenFilter</classname>s. Hibernate Search supports this infrastructure by utilizing the Solr @@ -661,7 +661,7 @@ depend on more libraries. For example, the <classname>PhoneticFilterFactory</classname> depends on <ulink url="http://commons.apache.org/codec">commons-codec</ulin...;. Your - distribution of Hibernate Search provides these dependecies in its + distribution of Hibernate Search provides these dependencies in its <filename>lib</filename> directory.</para> <example> @@ -749,7 +749,7 @@ Let check a few of them.</para> <table> - <title>Some of the tokenizers avalable</title> + <title>Some of the available tokenizers</title> <tgroup cols="3"> <thead> @@ -784,7 +784,7 @@ </table> <table> - <title>Some of the filters avalable</title> + <title>Some of the available filters</title> <tgroup cols="3"> <thead> @@ -860,7 +860,7 @@ <title>Analyzer discriminator (experimental)</title> <para>So far all the introduced ways to specify an analyzer were - static. However, there are usecases where it is useful to select an + static. However, there are use cases where it is useful to select an analyzer depending on the current state of the entity to be indexed, for example in multilingual application. For an <classname>BlogEntry</classname> class for example the analyzer could @@ -947,7 +947,7 @@ interface has to return the name of an existing analyzer definition if the analyzer should be set dynamically or <classname>null</classname> if the default analyzer should not be overridden. The given example - assumes that the language paramter is either 'de' or 'en' which + assumes that the language parameter is either 'de' or 'en' which matches the specified names in the <classname&gt;(a)AnalyzerDef&lt;/classname&gt;s.&lt;/para&gt; @@ -1076,7 +1076,7 @@ important is that when using a DateRange Query, you should know that the dates have to be expressed in GMT time.</para> - <para>Usually, storing the date up to the milisecond is not + <para>Usually, storing the date up to the millisecond is not necessary. <literal>@DateBridge</literal> defines the appropriate resolution you are willing to store in the index ( <literal> <literal&gt;(a)DateBridge(resolution=Resolution.DAY)&lt;/literal&gt; @@ -1213,8 +1213,8 @@ </example> <para>The <classname>ParameterizedBridge</classname> interface can be - implemented by <classname>StringBridge</classname> , - <classname>TwoWayStringBridge</classname> , + implemented by <classname>StringBridge</classname>, + <classname>TwoWayStringBridge</classname>, <classname>FieldBridge</classname> implementations.</para> <para>All implementations have to be thread-safe, but the parameters @@ -1276,13 +1276,13 @@ <section> <title>FieldBridge</title> - <para>Some usecases require more than a simple object to string + <para>Some use cases require more than a simple object to string translation when mapping a property to a Lucene index. To give you the greatest possible flexibility you can also implement a bridge as a <classname>FieldBridge</classname>. This interface gives you a property value and let you map it the way you want in your Lucene <classname>Document</classname>.The interface is very similar in its - concept to the Hibernate<classname> UserType</classname>'s.</para> + concept to the Hibernate<classname> UserType</classname>s.</para> <para>You can for example store a given property in two different document fields:</para> Modified: search/branches/Branch_3_1/src/main/docbook/en-US/modules/optimize.xml =================================================================== --- search/branches/Branch_3_1/src/main/docbook/en-US/modules/optimize.xml 2009-05-16 09:47:42 UTC (rev 16574) +++ search/branches/Branch_3_1/src/main/docbook/en-US/modules/optimize.xml 2009-05-16 09:54:26 UTC (rev 16575) @@ -35,7 +35,7 @@ During the optimization process the deletions will be applied which also effects the number of files in the Lucene Directory.</para> - <para>Optimising the Lucene index speeds up searches but has no effect on + <para>Optimizing the Lucene index speeds up searches but has no effect on the indexation (update) performance. During an optimization, searches can be performed, but will most likely be slowed down. All index updates will be stopped. It is recommended to schedule optimization:</para> @@ -61,7 +61,7 @@ </listitem> <listitem> - <para>or a certain amout of transactions </para> + <para>or a certain amount of transactions </para> </listitem> </itemizedlist> @@ -129,7 +129,7 @@ <para>Apache Lucene has a few parameters to influence how optimization is performed. Hibernate Search exposes those parameters.</para> - <para>Further index optimisation parameters include: <itemizedlist> + <para>Further index optimization parameters include: <itemizedlist> <listitem> <literal>hibernate.search.[default|&lt;indexname&gt;].indexwriter.[batch|transaction].max_buffered_docs</literal> </listitem> Modified: search/branches/Branch_3_1/src/main/docbook/en-US/modules/query.xml =================================================================== --- search/branches/Branch_3_1/src/main/docbook/en-US/modules/query.xml 2009-05-16 09:47:42 UTC (rev 16574) +++ search/branches/Branch_3_1/src/main/docbook/en-US/modules/query.xml 2009-05-16 09:54:26 UTC (rev 16575) @@ -58,7 +58,7 @@ </itemizedlist> <para>To access the querying facilities, you have to use an - <classname>FullTextSession</classname> . This Search specfic session wraps a + <classname>FullTextSession</classname>. This Search specific session wraps a regular <classname>org.hibernate.Session</classname> to provide query and indexing capabilities.</para> @@ -179,7 +179,7 @@ <section> <title>Pagination</title> - <para>Out of performace reasons it is recommended to restrict the + <para>Out of performance reasons it is recommended to restrict the number of returned objects per query. In fact is a very common use case anyway that the user navigates from one page to an other. The way to define pagination is exactly the way you would define pagination in @@ -313,8 +313,8 @@ </listitem> </itemizedlist> - <para>Projection is useful for another kind of usecases. Lucene - provides some metadata informations to the user about the results. By + <para>Projection is useful for another kind of use cases. Lucene + provides some metadata information to the user about the results. By using some special placeholders, the projection mechanism can retrieve them:</para> @@ -335,7 +335,7 @@ <itemizedlist> <listitem> - <para>FullTextQuery.THIS: returns the intialized and managed + <para>FullTextQuery.THIS: returns the initialized and managed entity (as a non projected query would have done).</para> </listitem> @@ -346,7 +346,7 @@ <listitem> <para>FullTextQuery.OBJECT_CLASS: returns the class of the - indexded entity.</para> + indexed entity.</para> </listitem> <listitem> @@ -471,7 +471,7 @@ the targeted data structure:</para> <example> - <title>Using ResultTransformer in conjuncton with projections</title> + <title>Using ResultTransformer in conjunction with projections</title> <programlisting>org.hibernate.search.FullTextQuery query = s.createFullTextQuery( luceneQuery, Book.class ); query.setProjection( "title", "mainAuthor.name" ); @@ -551,7 +551,7 @@ <para>Apache Lucene has a powerful feature that allows to filter query results according to a custom filtering process. This is a very powerful way to apply additional data restrictions, especially since filters can be - cached and reused. Some interesting usecases are:</para> + cached and reused. Some interesting use cases are:</para> <itemizedlist> <listitem> @@ -674,7 +674,7 @@ filter or filter factory of the targeted named filter definition.</para> <example> - <title>Using paramters in the actual filter implementation</title> + <title>Using parameters in the actual filter implementation</title> <programlisting>public class SecurityFilterFactory { private Integer level; @@ -704,7 +704,7 @@ <para>Note the method annotated <classname>@Key</classname> returning a <classname>FilterKey</classname> object. The returned object has a special contract: the key object must implement <methodname>equals()</methodname> - / <methodname>hashcode()</methodname> so that 2 keys are equal if and only + / <methodname>hashCode()</methodname> so that 2 keys are equal if and only if the given <classname>Filter</classname> types are the same and the set of parameters are the same. In other words, 2 filter keys are equal if and only if the filters from which the keys are generated can be interchanged. @@ -725,7 +725,7 @@ <para>In most cases, using the <literal>StandardFilterKey</literal> implementation will be good enough. It delegates the - <methodname>equals()</methodname> / <methodname>hashcode()</methodname> + <methodname>equals()</methodname> / <methodname>hashCode()</methodname> implementation to each of the parameters equals and hashcode methods.</para> @@ -734,11 +734,11 @@ of memory when needed. The hard reference cache keeps track of the most recently used filters and transforms the ones least used to <classname>SoftReferences</classname> when needed. Once the limit of the - hard reference cache is reached addtional filters are cached as + hard reference cache is reached additional filters are cached as <classname>SoftReferences</classname>. To adjust the size of the hard reference cache, use <literal>hibernate.search.filter.cache_strategy.size</literal> (defaults - to 128). For advance use of filter caching, you can implement your own + to 128). For advanced use of filter caching, you can implement your own <classname>FilterCachingStrategy</classname>. The classname is defined by <literal>hibernate.search.filter.cache_strategy</literal>.</para> @@ -769,12 +769,12 @@ (<classname>org.hibernate.search.filter.CachingWrapperFilter</classname>). In contrast to Lucene's version of this class <classname>SoftReference</classname>s are used together with a hard - reference count (see dicussion about filter cache). The hard reference + reference count (see discussion about filter cache). The hard reference count can be adjusted using <literal>hibernate.search.filter.cache_docidresults.size</literal> (defaults to 5). The wrapping behaviour can be controlled using the <literal&gt;(a)FullTextFilterDef.cache&lt;/literal&gt; parameter. There are three - differerent values for this parameter:</para> + different values for this parameter:</para> <para><informaltable align="left" width=""> <tgroup cols="2"> @@ -866,6 +866,6 @@ <para>If you wish to use some specific features of Lucene, you can always run Lucene specific queries. Check <xref linkend="search-lucene-native" /> - for more informations.</para> + for more information.</para> </section> </chapter>