-
Notifications
You must be signed in to change notification settings - Fork 0
/
MIGRATE.html
57 lines (57 loc) · 9.2 KB
/
MIGRATE.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
<html>
<head>
<title>Apache Lucene Migration Guide</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<h1 id="apache-lucene-migration-guide">Apache Lucene Migration Guide</h1>
<h2 id="changed-spi-lookups-for-codecs-and-analysis-changed-lucene-7873">Changed SPI lookups for codecs and analysis changed (<a href="https://issues.apache.org/jira/browse/LUCENE-7873">LUCENE-7873</a>)</h2>
<p>Due to serious problems with context class loaders in several frameworks (OSGI, Java 9 Jigsaw), the lookup of Codecs, PostingsFormats, DocValuesFormats and all analysis factories was changed to only inspect the current classloader that defined the interface class (<code>lucene-core.jar</code>). Normal applications should not encounter any issues with that change, because the application classloader (unnamed module in Java 9) can load all SPIs from all JARs from classpath.</p>
<p>For any code that relies on the old behaviour (e.g., certain web applications or components in application servers) one can manually instruct the Lucene SPI implementation to also inspect the context classloader. To do this, add this code to the early startup phase of your application before any Apache Lucene component is used:</p>
<pre><code>ClassLoader cl = Thread.currentThread().getContextClassLoader();
// Codecs:
PostingsFormat.reloadPostingsFormats(cl);
DocValuesFormat.reloadDocValuesFormats(cl);
Codec.reloadCodecs(cl);
// Analysis:
CharFilterFactory.reloadCharFilters(cl);
TokenFilterFactory.reloadTokenFilters(cl);
TokenizerFactory.reloadTokenizers(cl);
</code></pre>
<p>This code will reload all service providers from the given class loader (in our case the context class loader). Of course, instead of specifying the context class loader, it is receommended to use the application's main class loader or the module class loader.</p>
<p>If you are migrating your project to Java 9 Jigsaw module system, keep in mind that Lucene currently does not yet support <code>module-info.java</code> declarations of service provider impls (<code>provides</code> statement). It is therefore recommended to keep all of Lucene in one Uber-Module and not try to split Lucene into several modules. As soon as Lucene will migrate to Java 9 as minimum requirement, we will work on improving that.</p>
<p>For OSGI, the same applies. You have to create a bundle with all of Lucene for SPI to work correctly.</p>
<h2 id="customanalyzer-resources-lucene-7883">CustomAnalyzer resources (<a href="https://issues.apache.org/jira/browse/LUCENE-7883">LUCENE-7883</a>)##</h2>
<p>Lucene no longer uses the context class loader when resolving resources in CustomAnalyzer or ClassPathResourceLoader. Resources are only resolved against Lucene's class loader by default. Please use another builder method to change to a custom classloader.</p>
<h2 id="queryhashcode-and-queryequals-are-now-abstract-methods-lucene-7277">Query.hashCode and Query.equals are now abstract methods (<a href="https://issues.apache.org/jira/browse/LUCENE-7277">LUCENE-7277</a>)</h2>
<p>Any custom query subclasses should redeclare equivalence relationship according to the subclass's details. See code patterns used in existing core Lucene query classes for details.</p>
<h2 id="compressiontools-removed-lucene-7322">CompressionTools removed (<a href="https://issues.apache.org/jira/browse/LUCENE-7322">LUCENE-7322</a>)</h2>
<p>Per-field compression has been superseded by codec-level compression, which has the benefit of being able to compress several fields, or even documents at once, yielding better compression ratios. In case you would still like to compress on top of the codec, you can do it on the application side by using the utility classes from the java.util.zip package.</p>
<h2 id="explanationtohtml-removed-lucene-7360">Explanation.toHtml() removed (<a href="https://issues.apache.org/jira/browse/LUCENE-7360">LUCENE-7360</a>)</h2>
<p>Clients wishing to render Explanations as HTML should implement their own utilities for this.</p>
<h2 id="similaritycoord-and-booleanquerydisablecoord-removed-lucene-7369">Similarity.coord and BooleanQuery.disableCoord removed (<a href="https://issues.apache.org/jira/browse/LUCENE-7369">LUCENE-7369</a>)</h2>
<p>Coordination factors were a workaround for the fact that the ClassicSimilarity does not have strong enough term frequency saturation. This causes disjunctions to get better scores on documents that have many occurrences of a few query terms than on documents that match most clauses, which is most of time undesirable. The new BM25Similarity does not suffer from this problem since it has better saturation for the contribution of the term frequency so the coord factors have been removed from scores. Things now work as if coords were always disabled when constructing boolean queries.</p>
<h2 id="weightgetvaluefornormalization-and-weightnormalize-removed-lucene-7368">Weight.getValueForNormalization() and Weight.normalize() removed (<a href="https://issues.apache.org/jira/browse/LUCENE-7368">LUCENE-7368</a>)</h2>
<p>Query normalization's goal was to make scores comparable across queries, which was only implemented by the ClassicSimilarity. Since ClassicSimilarity is not the default similarity anymore, this functionality has been removed. Boosts are now propagated through Query#createWeight.</p>
<h2 id="analyzingqueryparser-removed-lucene-7355">AnalyzingQueryParser removed (<a href="https://issues.apache.org/jira/browse/LUCENE-7355">LUCENE-7355</a>)</h2>
<p>The functionality of AnalyzingQueryParser has been folded into the classic QueryParser, which now passes terms through Analyzer#normalize when generating queries.</p>
<h2 id="commonqueryparserconfigurationsetlowercaseexpandedterms-removed-lucene-7355">CommonQueryParserConfiguration.setLowerCaseExpandedTerms removed (<a href="https://issues.apache.org/jira/browse/LUCENE-7355">LUCENE-7355</a>)</h2>
<p>This option has been removed as expanded terms are now normalized through Analyzer#normalize.</p>
<h2 id="cache-key-and-close-listener-refactoring-lucene-7410">Cache key and close listener refactoring (<a href="https://issues.apache.org/jira/browse/LUCENE-7410">LUCENE-7410</a>)</h2>
<p>The way to access cache keys and add close listeners has been refactored in order to be less trappy. You should now use IndexReader.getReaderCacheHelper() to have manage caches that take deleted docs and doc values updates into account, and LeafReader.getCoreCacheHelper() to manage per-segment caches that do not take deleted docs and doc values updates into account.</p>
<h2 id="index-time-boosts-removal-lucene-6819">Index-time boosts removal (<a href="https://issues.apache.org/jira/browse/LUCENE-6819">LUCENE-6819</a>)</h2>
<p>Index-time boosts are not supported anymore. As a replacement, index-time scoring factors should be indexed in a doc value field and combined with the score at query time using FunctionScoreQuery for instance.</p>
<h2 id="grouping-collector-refactoring-lucene-7701">Grouping collector refactoring (<a href="https://issues.apache.org/jira/browse/LUCENE-7701">LUCENE-7701</a>)</h2>
<p>Groups are now defined by GroupSelector classes, making it easier to define new types of groups. Rather than having term or function specific collection classes, FirstPassGroupingCollector, AllGroupsCollector and AllGroupHeadsCollector are now concrete classes taking a GroupSelector.</p>
<p>SecondPassGroupingCollector is no longer specifically aimed at collecting TopDocs for each group, but instead takes a GroupReducer that will perform any type of reduction on the top groups collected on a first-pass. To reproduce the old behaviour of SecondPassGroupingCollector, you should instead use TopGroupsCollector.</p>
<h2 id="removed-legacy-numerics-lucene-7850">Removed legacy numerics (<a href="https://issues.apache.org/jira/browse/LUCENE-7850">LUCENE-7850</a>)</h2>
<p>Support for legacy numerics has been removed since legacy numerics had been deprecated since Lucene 6.0. Points should be used instead, see org.apache.lucene.index.PointValues for an introduction.</p>
<h2 id="topdocstotalhits-is-now-a-long-lucene-7872">TopDocs.totalHits is now a long (<a href="https://issues.apache.org/jira/browse/LUCENE-7872">LUCENE-7872</a>)</h2>
<p>TopDocs.totalHits is now a long so that TopDocs instances can be used to represent top hits that have more than 2B matches. This is necessary for the case that multiple TopDocs instances are merged together with TopDocs#merge as they might have more than 2B matches in total. However TopDocs instances returned by IndexSearcher will still have a total number of hits which is less than 2B since Lucene indexes are still bound to at most 2B documents, so it can safely be casted to an int in that case.</p>
<h2 id="prefixawaretokenfilter-and-prefixandsuffixawaretokenfilter-removed">PrefixAwareTokenFilter and PrefixAndSuffixAwareTokenFilter removed</h2>
<p>(<a href="https://issues.apache.org/jira/browse/LUCENE-7877">LUCENE-7877</a>)</p>
<p>Instead use ConcatentingTokenStream, which will allow for the use of custom attributes.</p>
<h2 id="fieldvaluequery-is-renamed-to-docvaluesfieldexistsquery-lucene-7899">FieldValueQuery is renamed to DocValuesFieldExistsQuery (<a href="https://issues.apache.org/jira/browse/LUCENE-7899">LUCENE-7899</a>)</h2>
<p>This query matches only documents that have a value for the specified doc values field.</p>
</body>
</html>