[hibernate-commits] Hibernate SVN: r15395 - in search/trunk: doc/reference/en/modules and 1 other directories.

Author: hardy.ferentschik Date: 2008-10-27 06:38:07 -0400 (Mon, 27 Oct 2008) New Revision: 15395 Modified: search/trunk/common-build.xml search/trunk/doc/reference/en/modules/query.xml search/trunk/src/java/org/hibernate/search/annotations/FilterCacheModeType.java Log: javadoc updates; replaced references to CacheBitResults with FilterCacheModeType; added link attribute to javadoc ant target in order to link to Lucene online doc Modified: search/trunk/common-build.xml =================================================================== --- search/trunk/common-build.xml 2008-10-26 14:39:40 UTC (rev 15394) +++ search/trunk/common-build.xml 2008-10-27 10:38:07 UTC (rev 15395) @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="UTF-8"?> +<?xml version="1.0" encoding="UTF-8"?> <project name="common-build" default="dist" xmlns:artifact="urn:maven-artifact-ant" xmlns:ivy="antlib:fr.jayasoft.ivy.ant"> <description>Common properties and targets for the HibernateExt @@ -14,8 +14,8 @@ <property file="${user.home}/.ant.properties"/> <property name="src.dir" location="src/java"/> - <property name="test.dir" location="src/test"/> - <property name="test.resources.dir" location="src/test-resources"/> + <property name="test.dir" location="src/test"/> + <property name="test.resources.dir" location="src/test-resources"/> <property name="filter.dir" location="src/filters"/> <property name="lib.dir" location="lib"/> <property name="build.dir" location="build"/> @@ -199,20 +199,20 @@ <include name="lgpl.txt"/> </fileset> </copy> - </target> - - <target name="get.deps.core" depends="init" - description="retrieve the core dependencies"> - <ivy:resolve conf="default"/> - <ivy:retrieve pattern="${ivy.dep.dir}/core/[artifact].[ext]" - conf="default"/> - </target> - - <target name="get.deps.test" depends="init" - description="retrieve the test dependencies"> - <ivy:resolve conf="test"/> - <ivy:retrieve pattern="${ivy.dep.dir}/test/[artifact].[ext]" conf="test"/> + </target> + + <target name="get.deps.core" depends="init" + description="retrieve the core dependencies"> + <ivy:resolve conf="default"/> + <ivy:retrieve pattern="${ivy.dep.dir}/core/[artifact].[ext]" + conf="default"/> </target> + + <target name="get.deps.test" depends="init" + description="retrieve the test dependencies"> + <ivy:resolve conf="test"/> + <ivy:retrieve pattern="${ivy.dep.dir}/test/[artifact].[ext]" conf="test"/> + </target> <target name="copytest" description="Copy tests to dist dir" if="copy.test"> <mkdir dir="${dist.test.dir}"/> @@ -293,6 +293,7 @@ <packageset dir="${src.dir}" defaultexcludes="yes"> <include name="**/*"/> </packageset> + <link href="http://lucene.apache.org/java/2_4_0/api"/> </javadoc> </target> @@ -345,49 +346,49 @@ <mkdir dir="${testclasses.dir}"/> <copy todir="${testclasses.dir}" filtering="true" overwrite="true"> <fileset dir="${test.resources.dir}"> - <include name="*.properties"/> + <include name="*.properties"/> <include name="*.xml"/> </fileset> </copy> </target> - - <target name="instrument" depends="compiletest" - description="Instrument the persistent classes"> <!-- depends="jar" --> - - <taskdef name="instrument" - classname="org.hibernate.tool.instrument.javassist.InstrumentTask"> - <classpath refid="junit.classpath"/> - </taskdef> - - <instrument verbose="true"> - <fileset dir="${testclasses.dir}/org/hibernate/test"> - <include name="**/*.class"/> - <exclude name="**/*Test$*.class"/> - <exclude name="**/*Test.class"/> - <exclude name="**/*Tests.class"/> - </fileset> - </instrument> + + <target name="instrument" depends="compiletest" + description="Instrument the persistent classes"> <!-- depends="jar" --> + + <taskdef name="instrument" + classname="org.hibernate.tool.instrument.javassist.InstrumentTask"> + <classpath refid="junit.classpath"/> + </taskdef> + + <instrument verbose="true"> + <fileset dir="${testclasses.dir}/org/hibernate/test"> + <include name="**/*.class"/> + <exclude name="**/*Test$*.class"/> + <exclude name="**/*Test.class"/> + <exclude name="**/*Tests.class"/> + </fileset> + </instrument> </target> <target name="junitinstrument" depends="compiletest,instrument" - description="Run the instrument test suite"> - <for list="${targetdb}" param="db"> - <sequential> - <antcall target="test-resources"> - <param name="db" value="@{db}"/> - </antcall> - <mkdir dir="${instrumenttest.out.dir}/@{db}"/> - <echo>Running against db: @{db}</echo> - <junit printsummary="yes" haltonfailure="yes" dir="${basedir}" - maxmemory="256M" fork="yes" forkmode="perBatch"> - <classpath refid="junit.classpath"/> - <formatter type="plain"/> - <formatter type="xml"/> - <batchtest todir="${instrumenttest.out.dir}/@{db}" haltonfailure="no"> - <fileset refid="junit.batchtestset"/> - </batchtest> - </junit> - </sequential> + description="Run the instrument test suite"> + <for list="${targetdb}" param="db"> + <sequential> + <antcall target="test-resources"> + <param name="db" value="@{db}"/> + </antcall> + <mkdir dir="${instrumenttest.out.dir}/@{db}"/> + <echo>Running against db: @{db}</echo> + <junit printsummary="yes" haltonfailure="yes" dir="${basedir}" + maxmemory="256M" fork="yes" forkmode="perBatch"> + <classpath refid="junit.classpath"/> + <formatter type="plain"/> + <formatter type="xml"/> + <batchtest todir="${instrumenttest.out.dir}/@{db}" haltonfailure="no"> + <fileset refid="junit.batchtestset"/> + </batchtest> + </junit> + </sequential> </for> </target> Modified: search/trunk/doc/reference/en/modules/query.xml =================================================================== --- search/trunk/doc/reference/en/modules/query.xml 2008-10-26 14:39:40 UTC (rev 15394) +++ search/trunk/doc/reference/en/modules/query.xml 2008-10-27 10:38:07 UTC (rev 15395) @@ -627,7 +627,7 @@ implementation to each of the parameters equals and hashcode methods.</para> - <para>As mentioned before the defined filters are per default cache and + <para>As mentioned before the defined filters are per default cached and the cache uses a combination of hard and soft references to allow disposal of memory when needed. The hard reference cache keeps track of the most recently used filters and transforms the ones least used to @@ -646,20 +646,34 @@ <classname>CachingWrapperFilter.</classname> The wrapper will cache the <classname>BitSet</classname> returned from the <methodname>bits(IndexReader reader)</methodname> method to avoid - expensive recomputation.</para> + expensive recomputation. The <classname>BitSet</classname> uses one bit + per Document. If for example your index contains ten millions documents, + the <classname>BitSet</classname> structure will take 1.2 Mb of memory. It + is important to mention that the computed <classname>BitSet</classname> is + only cachable for the same <classname>IndexReader</classname> instance, + because the reader effectively represents the state of the index at the + moment it was opened. The document list cannot change within an opened + <classname>IndexReader</classname>. A different/new<classname> + IndexReader</classname> instance, however, works potentially on a + different set of <classname>Document</classname>s (either from a different + index or simply because the index has changed), hence the cached + <classname>BitSet</classname> has to be recomputed.</para> - <para>Hibernate Search also takes care of this aspect of caching. If the - <literal>cache</literal> flag of <classname>@FullTextFilterDef - </classname>is set to <literal>true</literal>, it will automatically wrap - the specified filter around a Hibernate specific implementation of - CachingWrapperFilter + <para>Hibernate Search also helps with this aspect of caching. Per default + the <literal>cache</literal> flag of <classname>@FullTextFilterDef + </classname>is set to + <literal>FilterCacheModeType.INSTANCE_AND_BITSETRESULTS</literal> which + will automatically cache the filter instance as well as wrap the specified + filter around a Hibernate specific implementation of + <classname>CachingWrapperFilter</classname> (<classname>org.hibernate.search.filter.CachingWrapperFilter</classname>). - In contrast to Lucene's version of this class SoftReferences are used - together with a hard reference count (see dicussion about filter cache). - The hard reference count can be adjusted using + 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 + count can be adjusted using <literal>hibernate.search.filter.cache_bit_results.size</literal> - (defaults to 5). The wrapping behaviour can be controlled by - <literal&gt;(a)FullTextFilterDef.cacheBitResult&lt;/literal&gt;. There are two + (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> <para><informaltable align="left" width=""> @@ -676,21 +690,34 @@ <tbody> <row> - <entry align="left">CacheBitResults.AUTOMATIC</entry> + <entry align="left">FilterCacheModeType.NONE</entry> - <entry>The use of <classname>CachingWrapperFilter</classname> - depends on the <literal>cache</literal> paramter of the filter - defintion. If <literal>cache</literal> is set to - <literal>true</literal> a wrapper will be used, otherwise not. - <literal>CacheBitResults.AUTOMATIC</literal> is the default - value.</entry> + <entry>No filter instance and no result is cached by Hibernate + Search. For every filter call, a new filter instance is created. + This setting might be useful for rapidly changing data sets or + heavily memory constrained environments. </entry> </row> <row> - <entry align="left">CacheBitResults.NO</entry> + <entry align="left">FilterCacheModeType.INSTANCE_ONLY</entry> - <entry>No wrapper will be used.</entry> + <entry>The filter instance is cached and reused across + concurrent <methodname>Filter.bits()</methodname> calls. + <classname>BitSet</classname> results are not cached. This + setting is useful when a filter uses its own specific caching + mechanism or the filter results change dynamically due to + application specific events making <classname>BitSet</classname> + caching in both cases unnecessary. </entry> </row> + + <row> + <entry + align="left">FilterCacheModeType.INSTANCE_AND_BITSETRESULTS</entry> + + <entry>Both the filter instance and the + <classname>BitSet</classname> results are cached. This is the + default value.</entry> + </row> </tbody> </tgroup> </informaltable>Last but not least - why should filters be cached? There Modified: search/trunk/src/java/org/hibernate/search/annotations/FilterCacheModeType.java =================================================================== --- search/trunk/src/java/org/hibernate/search/annotations/FilterCacheModeType.java 2008-10-26 14:39:40 UTC (rev 15394) +++ search/trunk/src/java/org/hibernate/search/annotations/FilterCacheModeType.java 2008-10-27 10:38:07 UTC (rev 15395) @@ -1,29 +1,35 @@ package org.hibernate.search.annotations; /** - * Cache mode strategy for Full Text filters + * Cache mode strategy for <code>FullTextFilterDef</code>s. * + * @see FullTextFilterDef * @author Emmanuel Bernard */ public enum FilterCacheModeType { /** - * No filter instance and no result is cached by Hibernate Search - * For every filter call, a new filter instance is created + * No filter instance and no result is cached by Hibernate Search. + * For every filter call, a new filter instance is created. */ NONE, /** * The filter instance is cached by Hibernate Search and reused across - * concurrent filter.bits() calls - * Results are not cache by Hibernate Search + * concurrent <code>Filter.bits()</code> calls. + * Results are not cached by Hibernate Search. + * + * @see org.apache.lucene.search.Filter#bits(org.apache.lucene.index.IndexReader) + */ INSTANCE_ONLY, /** - * Both the filter instance and the BitSet results are cached. + * Both the filter instance and the <code>BitSet</code> results are cached. * The filter instance is cached by Hibernate Search and reused across - * concurrent filter.bits() calls - * BitSet Results are cached per IndexReader + * concurrent <code>Filter.bits()</code> calls. + * <code>BitSet</code> results are cached per <code>IndexReader</code>. + * + * @see org.apache.lucene.search.Filter#bits(org.apache.lucene.index.IndexReader) */ INSTANCE_AND_BITSETRESULTS