You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by rm...@apache.org on 2012/04/22 01:10:21 UTC
svn commit: r1328746 - in
/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene:
analysis/package.html document/package.html index/package.html
search/package.html search/payloads/package.html
search/similarities/package.html search/spans/package.html
Author: rmuir
Date: Sat Apr 21 23:10:20 2012
New Revision: 1328746
URL: http://svn.apache.org/viewvc?rev=1328746&view=rev
Log:
LUCENE-3732: fix broken links and outdated information in core package.htmls
Modified:
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/package.html
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/document/package.html
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/index/package.html
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/package.html
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/payloads/package.html
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/similarities/package.html
lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/spans/package.html
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/package.html
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/package.html?rev=1328746&r1=1328745&r2=1328746&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/package.html (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/package.html Sat Apr 21 23:10:20 2012
@@ -149,7 +149,7 @@ and proximity searches (though sentence
{@link org.apache.lucene.document.Field}s.
</li>
<li>
- The modules/analysis library located at the root of the Lucene distribution has a number of different Analyzer implementations to solve a variety
+ The analysis library located at the root of the Lucene distribution has a number of different Analyzer implementations to solve a variety
of different problems related to searching. Many of the Analyzers are designed to analyze non-English languages.
</li>
<li>
@@ -158,7 +158,7 @@ and proximity searches (though sentence
</ol>
<p>
Analysis is one of the main causes of performance degradation during indexing. Simply put, the more you analyze the slower the indexing (in most cases).
- Perhaps your application would be just fine using the simple WhitespaceTokenizer combined with a StopFilter. The contrib/benchmark library can be useful
+ Perhaps your application would be just fine using the simple WhitespaceTokenizer combined with a StopFilter. The benchmark/ library can be useful
for testing out the speed of the analysis process.
</p>
<h2>Invoking the Analyzer</h2>
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/document/package.html
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/document/package.html?rev=1328746&r1=1328745&r2=1328746&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/document/package.html (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/document/package.html Sat Apr 21 23:10:20 2012
@@ -36,9 +36,7 @@ package also provides utilities for work
<p>First and foremost, a {@link org.apache.lucene.document.Document} is something created by the user application. It is your job
to create Documents based on the content of the files you are working with in your application (Word, txt, PDF, Excel or any other format.)
How this is done is completely up to you. That being said, there are many tools available in other projects that can make
- the process of taking a file and converting it into a Lucene {@link org.apache.lucene.document.Document}. To see an example of this,
- take a look at the Lucene <a href="../../../../../../gettingstarted.html" target="top">demo</a> and the associated source code
- for extracting content from HTML.
+ the process of taking a file and converting it into a Lucene {@link org.apache.lucene.document.Document}.
</p>
<p>The {@link org.apache.lucene.document.DateTools} is a utility class to make dates and times searchable
(remember, Lucene only searches text). {@link org.apache.lucene.document.IntField}, {@link org.apache.lucene.document.LongField},
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/index/package.html
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/index/package.html?rev=1328746&r1=1328745&r2=1328746&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/index/package.html (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/index/package.html Sat Apr 21 23:10:20 2012
@@ -21,5 +21,6 @@
</head>
<body>
Code to maintain and access indices.
+<!-- TODO: add a BASIC overview here, including code examples of using postings apis -->
</body>
</html>
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/package.html
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/package.html?rev=1328746&r1=1328745&r2=1328746&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/package.html (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/package.html Sat Apr 21 23:10:20 2012
@@ -40,164 +40,171 @@ org.apache.lucene.search.IndexSearcher#s
org.apache.lucene.search.IndexSearcher#search(Query,Filter,int)}.
<!-- FILL IN MORE HERE -->
+ <!-- TODO: this page over-links the same things too many times -->
</p>
<a name="query"></a>
<h2>Query Classes</h2>
<h4>
- <a href="TermQuery.html">TermQuery</a>
+ {@link org.apache.lucene.search.TermQuery TermQuery}
</h4>
<p>Of the various implementations of
- <a href="Query.html">Query</a>, the
- <a href="TermQuery.html">TermQuery</a>
- is the easiest to understand and the most often used in applications. A <a
- href="TermQuery.html">TermQuery</a> matches all the documents that contain the
+ {@link org.apache.lucene.search.Query Query}, the
+ {@link org.apache.lucene.search.TermQuery TermQuery}
+ is the easiest to understand and the most often used in applications. A
+ {@link org.apache.lucene.search.TermQuery TermQuery} matches all the documents that contain the
specified
- <a href="../index/Term.html">Term</a>,
+ {@link org.apache.lucene.index.Term Term},
which is a word that occurs in a certain
- <a href="../document/Field.html">Field</a>.
- Thus, a <a href="TermQuery.html">TermQuery</a> identifies and scores all
- <a href="../document/Document.html">Document</a>s that have a <a
- href="../document/Field.html">Field</a> with the specified string in it.
- Constructing a <a
- href="TermQuery.html">TermQuery</a>
+ {@link org.apache.lucene.document.Field Field}.
+ Thus, a {@link org.apache.lucene.search.TermQuery TermQuery} identifies and scores all
+ {@link org.apache.lucene.document.Document Document}s that have a
+ {@link org.apache.lucene.document.Field Field} with the specified string in it.
+ Constructing a {@link org.apache.lucene.search.TermQuery TermQuery}
is as simple as:
<pre>
TermQuery tq = new TermQuery(new Term("fieldName", "term"));
- </pre>In this example, the <a href="Query.html">Query</a> identifies all <a
- href="../document/Document.html">Document</a>s that have the <a
- href="../document/Field.html">Field</a> named <tt>"fieldName"</tt>
+ </pre>In this example, the {@link org.apache.lucene.search.Query Query} identifies all
+ {@link org.apache.lucene.document.Document Document}s that have the
+ {@link org.apache.lucene.document.Field Field} named <tt>"fieldName"</tt>
containing the word <tt>"term"</tt>.
</p>
<h4>
- <a href="BooleanQuery.html">BooleanQuery</a>
+ {@link org.apache.lucene.search.BooleanQuery BooleanQuery}
</h4>
<p>Things start to get interesting when one combines multiple
- <a href="TermQuery.html">TermQuery</a> instances into a <a
- href="BooleanQuery.html">BooleanQuery</a>.
- A <a href="BooleanQuery.html">BooleanQuery</a> contains multiple
- <a href="BooleanClause.html">BooleanClause</a>s,
- where each clause contains a sub-query (<a href="Query.html">Query</a>
- instance) and an operator (from <a
- href="BooleanClause.Occur.html">BooleanClause.Occur</a>)
+ {@link org.apache.lucene.search.TermQuery TermQuery} instances into a
+ {@link org.apache.lucene.search.BooleanQuery BooleanQuery}.
+ A {@link org.apache.lucene.search.BooleanQuery BooleanQuery} contains multiple
+ {@link org.apache.lucene.search.BooleanClause BooleanClause}s,
+ where each clause contains a sub-query ({@link org.apache.lucene.search.Query Query}
+ instance) and an operator (from
+ {@link org.apache.lucene.search.BooleanClause.Occur BooleanClause.Occur})
describing how that sub-query is combined with the other clauses:
<ol>
- <li><p>SHOULD — Use this operator when a clause can occur in the result set, but is not required.
+ <li><p>{@link org.apache.lucene.search.BooleanClause.Occur#SHOULD SHOULD} — Use this operator when a clause can occur in the result set, but is not required.
If a query is made up of all SHOULD clauses, then every document in the result
set matches at least one of these clauses.</p></li>
- <li><p>MUST — Use this operator when a clause is required to occur in the result set. Every
+ <li><p>{@link org.apache.lucene.search.BooleanClause.Occur#MUST MUST} — Use this operator when a clause is required to occur in the result set. Every
document in the result set will match
all such clauses.</p></li>
- <li><p>MUST NOT — Use this operator when a
+ <li><p>{@link org.apache.lucene.search.BooleanClause.Occur#MUST_NOT MUST NOT} — Use this operator when a
clause must not occur in the result set. No
document in the result set will match
any such clauses.</p></li>
</ol>
Boolean queries are constructed by adding two or more
- <a href="BooleanClause.html">BooleanClause</a>
- instances. If too many clauses are added, a <a href="BooleanQuery.TooManyClauses.html">TooManyClauses</a>
+ {@link org.apache.lucene.search.BooleanClause BooleanClause}
+ instances. If too many clauses are added, a {@link org.apache.lucene.search.BooleanQuery.TooManyClauses TooManyClauses}
exception will be thrown during searching. This most often occurs
- when a <a href="Query.html">Query</a>
- is rewritten into a <a href="BooleanQuery.html">BooleanQuery</a> with many
- <a href="TermQuery.html">TermQuery</a> clauses,
- for example by <a href="WildcardQuery.html">WildcardQuery</a>.
+ when a {@link org.apache.lucene.search.Query Query}
+ is rewritten into a {@link org.apache.lucene.search.BooleanQuery BooleanQuery} with many
+ {@link org.apache.lucene.search.TermQuery TermQuery} clauses,
+ for example by {@link org.apache.lucene.search.WildcardQuery WildcardQuery}.
The default setting for the maximum number
of clauses 1024, but this can be changed via the
- static method <a href="BooleanQuery.html#setMaxClauseCount(int)">setMaxClauseCount</a>
- in <a href="BooleanQuery.html">BooleanQuery</a>.
+ static method {@link org.apache.lucene.search.BooleanQuery#setMaxClauseCount(int)}.
</p>
<h4>Phrases</h4>
<p>Another common search is to find documents containing certain phrases. This
- is handled two different ways:
+ is handled three different ways:
<ol>
<li>
- <p><a href="PhraseQuery.html">PhraseQuery</a>
+ <p>{@link org.apache.lucene.search.PhraseQuery PhraseQuery}
— Matches a sequence of
- <a href="../index/Term.html">Terms</a>.
- <a href="PhraseQuery.html">PhraseQuery</a> uses a slop factor to determine
+ {@link org.apache.lucene.index.Term Term}s.
+ {@link org.apache.lucene.search.PhraseQuery PhraseQuery} uses a slop factor to determine
how many positions may occur between any two terms in the phrase and still be considered a match.</p>
</li>
<li>
- <p><a href="spans/SpanNearQuery.html">SpanNearQuery</a>
+ <p>{@link org.apache.lucene.search.MultiPhraseQuery MultiPhraseQuery}
+ — A more general form of PhraseQuery that accepts multiple Terms
+ for a position in the phrase. For example, this can be used to perform phrase queries that also
+ incorporate synonyms.
+ </li>
+ <li>
+ <p>{@link org.apache.lucene.search.spans.SpanNearQuery SpanNearQuery}
— Matches a sequence of other
- <a href="spans/SpanQuery.html">SpanQuery</a>
- instances. <a href="spans/SpanNearQuery.html">SpanNearQuery</a> allows for
+ {@link org.apache.lucene.search.spans.SpanQuery SpanQuery}
+ instances. {@link org.apache.lucene.search.spans.SpanNearQuery SpanNearQuery} allows for
much more
- complicated phrase queries since it is constructed from other <a
- href="spans/SpanQuery.html">SpanQuery</a>
- instances, instead of only <a href="TermQuery.html">TermQuery</a>
+ complicated phrase queries since it is constructed from other
+ {@link org.apache.lucene.search.spans.SpanQuery SpanQuery}
+ instances, instead of only {@link org.apache.lucene.search.TermQuery TermQuery}
instances.</p>
</li>
</ol>
</p>
<h4>
- <a href="TermRangeQuery.html">TermRangeQuery</a>
+ {@link org.apache.lucene.search.TermRangeQuery TermRangeQuery}
</h4>
<p>The
- <a href="TermRangeQuery.html">TermRangeQuery</a>
+ {@link org.apache.lucene.search.TermRangeQuery TermRangeQuery}
matches all documents that occur in the
exclusive range of a lower
- <a href="../index/Term.html">Term</a>
+ {@link org.apache.lucene.index.Term Term}
and an upper
- <a href="../index/Term.html">Term</a>.
- according to {@link java.lang.String#compareTo(String)}. It is not intended
- for numerical ranges, use <a href="NumericRangeQuery.html">NumericRangeQuery</a> instead.
+ {@link org.apache.lucene.index.Term Term}
+ according to {@link org.apache.lucene.index.TermsEnum#getComparator TermsEnum.getComparator()}. It is not intended
+ for numerical ranges, use {@link org.apache.lucene.search.NumericRangeQuery NumericRangeQuery} instead.
For example, one could find all documents
- that have terms beginning with the letters <tt>a</tt> through <tt>c</tt>. This type of <a
- href="Query.html">Query</a> is frequently used to
+ that have terms beginning with the letters <tt>a</tt> through <tt>c</tt>. This type of
+ {@link org.apache.lucene.search.Query} is frequently used to
find
documents that occur in a specific date range.
</p>
<h4>
- <a href="NumericRangeQuery.html">NumericRangeQuery</a>
+ {@link org.apache.lucene.search.NumericRangeQuery NumericRangeQuery}
</h4>
<p>The
- <a href="NumericRangeQuery.html">NumericRangeQuery</a>
+ {@link org.apache.lucene.search.NumericRangeQuery NumericRangeQuery}
matches all documents that occur in a numeric range.
For NumericRangeQuery to work, you must index the values
- using a one of the numeric fields (<a href="../document/IntField.html">IntField</a>,
- <a href="../document/LongField.html">LongField</a>, <a href="../document/FloatField.html">FloatField</a>,
- or <a href="../document/DoubleField.html">DoubleField</a>).
+ using a one of the numeric fields ({@link org.apache.lucene.document.IntField IntField},
+ {@link org.apache.lucene.document.LongField LongField}, {@link org.apache.lucene.document.FloatField FloatField},
+ or {@link org.apache.lucene.document.DoubleField DoubleField}).
</p>
<h4>
- <a href="PrefixQuery.html">PrefixQuery</a>,
- <a href="WildcardQuery.html">WildcardQuery</a>
+ {@link org.apache.lucene.search.PrefixQuery PrefixQuery},
+ {@link org.apache.lucene.search.WildcardQuery WildcardQuery},
+ {@link org.apache.lucene.search.RegexpQuery RegexpQuery}
</h4>
<p>While the
- <a href="PrefixQuery.html">PrefixQuery</a>
+ {@link org.apache.lucene.search.PrefixQuery PrefixQuery}
has a different implementation, it is essentially a special case of the
- <a href="WildcardQuery.html">WildcardQuery</a>.
- The <a href="PrefixQuery.html">PrefixQuery</a> allows an application
- to identify all documents with terms that begin with a certain string. The <a
- href="WildcardQuery.html">WildcardQuery</a> generalizes this by allowing
+ {@link org.apache.lucene.search.WildcardQuery WildcardQuery}.
+ The {@link org.apache.lucene.search.PrefixQuery PrefixQuery} allows an application
+ to identify all documents with terms that begin with a certain string. The
+ {@link org.apache.lucene.search.WildcardQuery WildcardQuery} generalizes this by allowing
for the use of <tt>*</tt> (matches 0 or more characters) and <tt>?</tt> (matches exactly one character) wildcards.
- Note that the <a href="WildcardQuery.html">WildcardQuery</a> can be quite slow. Also
+ Note that the {@link org.apache.lucene.search.WildcardQuery WildcardQuery} can be quite slow. Also
note that
- <a href="WildcardQuery.html">WildcardQuery</a> should
+ {@link org.apache.lucene.search.WildcardQuery WildcardQuery} should
not start with <tt>*</tt> and <tt>?</tt>, as these are extremely slow.
- To remove this protection and allow a wildcard at the beginning of a term, see method
- <a href="../queryParser/QueryParser.html#setAllowLeadingWildcard(boolean)">setAllowLeadingWildcard</a> in
- <a href="../queryParser/QueryParser.html">QueryParser</a>.
+ Some QueryParsers may not allow this by default, but provide a <code>setAllowLeadingWildcard</code> method
+ to remove protection.
+ The {@link org.apache.lucene.search.RegexpQuery RegexpQuery} is even more general than WildcardQuery,
+ allowing an application to identify all documents with terms that match a regular expression pattern.
</p>
<h4>
- <a href="FuzzyQuery.html">FuzzyQuery</a>
+ {@link org.apache.lucene.search.FuzzyQuery FuzzyQuery}
</h4>
<p>A
- <a href="FuzzyQuery.html">FuzzyQuery</a>
+ {@link org.apache.lucene.search.FuzzyQuery FuzzyQuery}
matches documents that contain terms similar to the specified term. Similarity is
determined using
<a href="http://en.wikipedia.org/wiki/Levenshtein">Levenshtein (edit) distance</a>.
@@ -206,58 +213,9 @@ org.apache.lucene.search.IndexSearcher#s
<a name="changingSimilarity"></a>
<h2>Changing Similarity</h2>
-<p>Chances are <a href="DefaultSimilarity.html">DefaultSimilarity</a> is sufficient for all
- your searching needs.
- However, in some applications it may be necessary to customize your <a
- href="Similarity.html">Similarity</a> implementation. For instance, some
- applications do not need to
- distinguish between shorter and longer documents (see <a
- href="http://www.gossamer-threads.com/lists/lucene/java-user/38967#38967">a "fair" similarity</a>).</p>
-
-<p>To change <a href="Similarity.html">Similarity</a>, one must do so for both indexing and
- searching, and the changes must happen before
- either of these actions take place. Although in theory there is nothing stopping you from changing mid-stream, it
- just isn't well-defined what is going to happen.
-</p>
+See the {@link org.apache.lucene.search.similarities} package documentation for information
+on the available scoring models and extending or changing Similarity.
-<p>To make this change, implement your own <a href="Similarity.html">Similarity</a> (likely
- you'll want to simply subclass
- <a href="DefaultSimilarity.html">DefaultSimilarity</a>) and then use the new
- class by calling
- <a href="../index/IndexWriter.html#setSimilarity(org.apache.lucene.search.Similarity)">IndexWriter.setSimilarity</a>
- before indexing and
- <a href="Searcher.html#setSimilarity(org.apache.lucene.search.Similarity)">Searcher.setSimilarity</a>
- before searching.
-</p>
-
-<p>
- If you are interested in use cases for changing your similarity, see the Lucene users's mailing list at <a
- href="http://www.nabble.com/Overriding-Similarity-tf2128934.html">Overriding Similarity</a>.
- In summary, here are a few use cases:
- <ol>
- <li><p><a href="api/org/apache/lucene/misc/SweetSpotSimilarity.html">SweetSpotSimilarity</a> — <a
- href="api/org/apache/lucene/misc/SweetSpotSimilarity.html">SweetSpotSimilarity</a> gives small increases
- as the frequency increases a small amount
- and then greater increases when you hit the "sweet spot", i.e. where you think the frequency of terms is
- more significant.</p></li>
- <li><p>Overriding tf — In some applications, it doesn't matter what the score of a document is as long as a
- matching term occurs. In these
- cases people have overridden Similarity to return 1 from the tf() method.</p></li>
- <li><p>Changing Length Normalization — By overriding <a
- href="Similarity.html#lengthNorm(java.lang.String,%20int)">lengthNorm</a>,
- it is possible to discount how the length of a field contributes
- to a score. In <a href="DefaultSimilarity.html">DefaultSimilarity</a>,
- lengthNorm = 1 / (numTerms in field)^0.5, but if one changes this to be
- 1 / (numTerms in field), all fields will be treated
- <a href="http://www.gossamer-threads.com/lists/lucene/java-user/38967#38967">"fairly"</a>.</p></li>
- </ol>
- In general, Chris Hostetter sums it up best in saying (from <a
- href="http://www.gossamer-threads.com/lists/lucene/java-user/39125#39125">the Lucene users's mailing list</a>):
- <blockquote>[One would override the Similarity in] ... any situation where you know more about your data then just
- that
- it's "text" is a situation where it *might* make sense to to override your
- Similarity method.</blockquote>
-</p>
<a name="scoring"></a>
<h2>Changing Scoring — Expert Level</h2>
@@ -270,112 +228,130 @@ org.apache.lucene.search.IndexSearcher#s
<span >three main classes</span>:
<ol>
<li>
- <a href="Query.html">Query</a> — The abstract object representation of the
+ {@link org.apache.lucene.search.Query Query} — The abstract object representation of the
user's information need.</li>
<li>
- <a href="Weight.html">Weight</a> — The internal interface representation of
+ {@link org.apache.lucene.search.Weight Weight} — The internal interface representation of
the user's Query, so that Query objects may be reused.</li>
<li>
- <a href="Scorer.html">Scorer</a> — An abstract class containing common
+ {@link org.apache.lucene.search.Scorer Scorer} — An abstract class containing common
functionality for scoring. Provides both scoring and explanation capabilities.</li>
</ol>
Details on each of these classes, and their children, can be found in the subsections below.
</p>
<h4>The Query Class</h4>
<p>In some sense, the
- <a href="Query.html">Query</a>
+ {@link org.apache.lucene.search.Query Query}
class is where it all begins. Without a Query, there would be
nothing to score. Furthermore, the Query class is the catalyst for the other scoring classes as it
is often responsible
for creating them or coordinating the functionality between them. The
- <a href="Query.html">Query</a> class has several methods that are important for
+ {@link org.apache.lucene.search.Query Query} class has several methods that are important for
derived classes:
<ol>
- <li>createWeight(Searcher searcher) — A
- <a href="Weight.html">Weight</a> is the internal representation of the
+ <li>{@link org.apache.lucene.search.Query#createWeight(IndexSearcher) createWeight(IndexSearcher searcher} — A
+ {@link org.apache.lucene.search.Weight Weight} is the internal representation of the
Query, so each Query implementation must
provide an implementation of Weight. See the subsection on <a
href="#The Weight Interface">The Weight Interface</a> below for details on implementing the Weight
interface.</li>
- <li>rewrite(IndexReader reader) — Rewrites queries into primitive queries. Primitive queries are:
- <a href="TermQuery.html">TermQuery</a>,
- <a href="BooleanQuery.html">BooleanQuery</a>, <span
- >and other queries that implement Query.html#createWeight(Searcher searcher)</span></li>
+ <li>{@link org.apache.lucene.search.Query#rewrite(IndexReader) rewrite(IndexReader reader} — Rewrites queries into primitive queries. Primitive queries are:
+ {@link org.apache.lucene.search.TermQuery TermQuery},
+ {@link org.apache.lucene.search.BooleanQuery BooleanQuery}, <span
+ >and other queries that implement {@link org.apache.lucene.search.Query#createWeight(IndexSearcher) createWeight(IndexSearcher searcher)}</span></li>
</ol>
</p>
<h4>The Weight Interface</h4>
<p>The
- <a href="Weight.html">Weight</a>
+ {@link org.apache.lucene.search.Weight Weight}
interface provides an internal representation of the Query so that it can be reused. Any
- <a href="Searcher.html">Searcher</a>
+ {@link org.apache.lucene.search.IndexSearcher IndexSearcher}
dependent state should be stored in the Weight implementation,
- not in the Query class. The interface defines six methods that must be implemented:
+ not in the Query class. The interface defines five methods that must be implemented:
<ol>
<li>
- <a href="Weight.html#getQuery()">Weight#getQuery()</a> — Pointer to the
+ {@link org.apache.lucene.search.Weight#getQuery getQuery()} — Pointer to the
Query that this Weight represents.</li>
<li>
- <a href="Weight.html#getValue()">Weight#getValue()</a> — The weight for
- this Query. For example, the TermQuery.TermWeight value is
- equal to the idf^2 * boost * queryNorm <!-- DOUBLE CHECK THIS --></li>
- <li>
- <a href="Weight.html#sumOfSquaredWeights()">
- Weight#sumOfSquaredWeights()</a> — The sum of squared weights. For TermQuery, this is (idf *
- boost)^2</li>
- <li>
- <a href="Weight.html#normalize(float)">
- Weight#normalize(float)</a> — Determine the query normalization factor. The query normalization may
+ {@link org.apache.lucene.search.Weight#getValueForNormalization() getValueForNormalization()} —
+ A weight can return a floating point value to indicate its magnitude for query normalization. Typically
+ a weight such as TermWeight that scores via a {@link org.apache.lucene.search.similarities.Similarity Similarity}
+ will just defer to the Similarity's implementation:
+ {@link org.apache.lucene.search.similarities.Similarity.SimWeight#getValueForNormalization SimWeight#getValueForNormalization()}.
+ For example, with {@link org.apache.lucene.search.similarities.TFIDFSimilarity Lucene's classic vector-space formula}, this
+ is implemented as the sum of squared weights: <code>(idf * boost)<sup>2</sup></code></li>
+ <li>
+ {@link org.apache.lucene.search.Weight#normalize(float,float) normalize(float norm, float topLevelBoost)} —
+ Performs query normalization:
+ <ul>
+ <li><code>topLevelBoost</code>: A query-boost factor from any wrapping queries that should be multiplied into every
+ document's score. For example, a TermQuery that is wrapped within a BooleanQuery with a boost of <code>5</code> would
+ receive this value at this time. This allows the TermQuery (the leaf node in this case) to compute this up-front
+ a single time (e.g. by multiplying into the IDF), rather than for every document.</li>
+ <li><code>norm</code>: Passes in a a normalization factor which may
allow for comparing scores between queries.</li>
- <li>
- <a href="Weight.html#scorer(org.apache.lucene.index.AtomicReaderContext, boolean, boolean)">
- Weight#scorer(AtomicReaderContext, boolean, boolean)</a> — Construct a new
- <a href="Scorer.html">Scorer</a>
- for this Weight. See
- <a href="#The Scorer Class">The Scorer Class</a>
- below for help defining a Scorer. As the name implies, the
- Scorer is responsible for doing the actual scoring of documents given the Query.
+ </ul>
+ Typically a weight such as TermWeight
+ that scores via a {@link org.apache.lucene.search.similarities.Similarity Similarity} will just defer to the Similarity's implementation:
+ {@link org.apache.lucene.search.similarities.Similarity.SimWeight#normalize SimWeight#normalize(float,float)}.</li>
+ <li>
+ {@link org.apache.lucene.search.Weight#scorer(org.apache.lucene.index.AtomicReaderContext, boolean, boolean, org.apache.lucene.util.Bits)
+ scorer(AtomicReaderContext context, boolean scoresDocsInOrder, boolean topScorer, Bits acceptDocs)} —
+ Construct a new {@link org.apache.lucene.search.Scorer Scorer} for this Weight. See <a href="#The Scorer Class">The Scorer Class</a>
+ below for help defining a Scorer. As the name implies, the Scorer is responsible for doing the actual scoring of documents
+ given the Query.
</li>
<li>
- <a href="Weight.html#explain(org.apache.lucene.search.Searcher, org.apache.lucene.index.AtomicReaderContext, int)">
- Weight#explain(Searcher, AtomicReaderContext, int)</a> — Provide a means for explaining why a given document was
- scored
- the way it was.</li>
+ {@link org.apache.lucene.search.Weight#explain(org.apache.lucene.index.AtomicReaderContext, int)
+ explain(AtomicReaderContext context, int doc)} — Provide a means for explaining why a given document was
+ scored the way it was.
+ Typically a weight such as TermWeight
+ that scores via a {@link org.apache.lucene.search.similarities.Similarity Similarity} will make use of the Similarity's implementations:
+ {@link org.apache.lucene.search.similarities.Similarity.ExactSimScorer#explain(int, Explanation) ExactSimScorer#explain(int doc, Explanation freq)},
+ and {@link org.apache.lucene.search.similarities.Similarity.SloppySimScorer#explain(int, Explanation) SloppySimScorer#explain(int doc, Explanation freq)}
+ </li>
+ </li>
</ol>
</p>
<h4>The Scorer Class</h4>
<p>The
- <a href="Scorer.html">Scorer</a>
+ {@link org.apache.lucene.search.Scorer Scorer}
abstract class provides common scoring functionality for all Scorer implementations and
is the heart of the Lucene scoring process. The Scorer defines the following abstract (some of them are not
yet abstract, but will be in future versions and should be considered as such now) methods which
- must be implemented (some of them inherited from <a href="DocIdSetIterator.html">DocIdSetIterator</a> ):
+ must be implemented (some of them inherited from {@link org.apache.lucene.search.DocIdSetIterator DocIdSetIterator}):
<ol>
<li>
- <a href="DocIdSetIterator.html#nextDoc()">DocIdSetIterator#nextDoc()</a> — Advances to the next
- document that matches this Query, returning true if and only
- if there is another document that matches.</li>
- <li>
- <a href="DocIdSetIterator.html#docID()">DocIdSetIterator#docID()</a> — Returns the id of the
- <a href="../document/Document.html">Document</a>
- that contains the match. It is not valid until next() has been called at least once.
+ {@link org.apache.lucene.search.Scorer#nextDoc nextDoc()} — Advances to the next
+ document that matches this Query, returning true if and only if there is another document that matches.</li>
+ <li>
+ {@link org.apache.lucene.search.Scorer#docID docID()} — Returns the id of the
+ {@link org.apache.lucene.document.Document Document} that contains the match.
</li>
<li>
- <a href="Scorer.html#score(org.apache.lucene.search.Collector)">Scorer#score(Collector)</a> —
- Scores and collects all matching documents using the given Collector.
+ {@link org.apache.lucene.search.Scorer#score score()} — Return the score of the
+ current document. This value can be determined in any appropriate way for an application. For instance, the
+ {@link org.apache.lucene.search.TermScorer TermScorer} simply defers to the configured Similarity:
+ {@link org.apache.lucene.search.similarities.Similarity.ExactSimScorer#score(int, int) ExactSimScorer.score(int doc, int freq)}.
</li>
<li>
- <a href="Scorer.html#score()">Scorer#score()</a> — Return the score of the
- current document. This value can be determined in any
- appropriate way for an application. For instance, the
- <a href="http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/TermScorer.java?view=log">TermScorer</a>
- returns the tf * Weight.getValue() * fieldNorm.
+ {@link org.apache.lucene.search.Scorer#freq freq()} — Returns the number of matches
+ for the current document. This value can be determined in any appropriate way for an application. For instance, the
+ {@link org.apache.lucene.search.TermScorer TermScorer} simply defers to the term frequency from the inverted index:
+ {@link org.apache.lucene.index.DocsEnum#freq DocsEnum.freq()}.
</li>
<li>
- <a href="DocIdSetIterator.html#advance(int)">DocIdSetIterator#advance(int)</a> — Skip ahead in
+ {@link org.apache.lucene.search.Scorer#advance advance()} — Skip ahead in
the document matches to the document whose id is greater than
or equal to the passed in value. In many instances, advance can be
implemented more efficiently than simply looping through all the matching documents until
- the target document is identified.</li>
+ the target document is identified.
+ </li>
+ <li>
+ {@link org.apache.lucene.search.Scorer#getChildren getChildren()} — Returns any child subscorers
+ underneath this scorer. This allows for users to navigate the scorer hierarchy and receive more fine-grained
+ details on the scoring process.
+ </li>
</ol>
</p>
<h4>Why would I want to add my own Query?</h4>
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/payloads/package.html
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/payloads/package.html?rev=1328746&r1=1328745&r2=1328746&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/payloads/package.html (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/payloads/package.html Sat Apr 21 23:10:20 2012
@@ -25,8 +25,8 @@
</DIV>
<div>
<ol>
- <li><a href="./PayloadTermQuery.html">PayloadTermQuery</a> -- Boost a term's score based on the value of the payload located at that term.</li>
- <li><a href="./PayloadNearQuery.html">PayloadNearQuery</a> -- A <a href="../spans/SpanNearQuery.html">SpanNearQuery</a> that factors in the value of the payloads located
+ <li>{@link org.apache.lucene.search.payloads.PayloadTermQuery PayloadTermQuery} -- Boost a term's score based on the value of the payload located at that term.</li>
+ <li>{@link org.apache.lucene.search.payloads.PayloadNearQuery PayloadNearQuery} -- A {@link org.apache.lucene.search.spans.SpanNearQuery SpanNearQuery} that factors in the value of the payloads located
at each of the positions where the spans occur.</li>
</ol>
</div>
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/similarities/package.html
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/similarities/package.html?rev=1328746&r1=1328745&r2=1328746&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/similarities/package.html (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/similarities/package.html Sat Apr 21 23:10:20 2012
@@ -105,7 +105,7 @@ implement the {@link org.apache.lucene.s
and {@link org.apache.lucene.search.similarities.SimilarityBase#toString()}
methods.</p>
-<p>Another options is to extend one of the <a href="#framework">frameworks</a>
+<p>Another option is to extend one of the <a href="#framework">frameworks</a>
based on {@link org.apache.lucene.search.similarities.SimilarityBase}. These
Similarities are implemented modularly, e.g.
{@link org.apache.lucene.search.similarities.DFRSimilarity} delegates
Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/spans/package.html
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/spans/package.html?rev=1328746&r1=1328745&r2=1328746&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/spans/package.html (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/spans/package.html Sat Apr 21 23:10:20 2012
@@ -26,29 +26,30 @@ The calculus of spans.
<ul>
-<li>A <a href="SpanTermQuery.html">SpanTermQuery</a> matches all spans
-containing a particular <a href="../../index/Term.html">Term</a>.</li>
+<li>A {@link org.apache.lucene.search.spans.SpanTermQuery SpanTermQuery} matches all spans
+containing a particular {@link org.apache.lucene.index.Term Term}.</li>
-<li> A <a href="SpanNearQuery.html">SpanNearQuery</a> matches spans
+<li> A {@link org.apache.lucene.search.spans.SpanNearQuery SpanNearQuery} matches spans
which occur near one another, and can be used to implement things like
-phrase search (when constructed from <a
-href="SpanTermQuery.html">SpanTermQueries</a>) and inter-phrase
-proximity (when constructed from other <a
-href="SpanNearQuery.html">SpanNearQueries</a>).</li>
+phrase search (when constructed from {@link org.apache.lucene.search.spans.SpanTermQuery}s)
+and inter-phrase proximity (when constructed from other {@link org.apache.lucene.search.spans.SpanNearQuery}s).</li>
-<li>A <a href="SpanOrQuery.html">SpanOrQuery</a> merges spans from a
-number of other <a href="SpanQuery.html">SpanQueries</a>.</li>
+<li>A {@link org.apache.lucene.search.spans.SpanOrQuery SpanOrQuery} merges spans from a
+number of other {@link org.apache.lucene.search.spans.SpanQuery}s.</li>
-<li>A <a href="SpanNotQuery.html">SpanNotQuery</a> removes spans
-matching one <a href="SpanQuery.html">SpanQuery</a> which overlap
+<li>A {@link org.apache.lucene.search.spans.SpanNotQuery SpanNotQuery} removes spans
+matching one {@link org.apache.lucene.search.spans.SpanQuery SpanQuery} which overlap
another. This can be used, e.g., to implement within-paragraph
search.</li>
-<li>A <a href="SpanFirstQuery.html">SpanFirstQuery</a> matches spans
+<li>A {@link org.apache.lucene.search.spans.SpanFirstQuery SpanFirstQuery} matches spans
matching <code>q</code> whose end position is less than
<code>n</code>. This can be used to constrain matches to the first
part of the document.</li>
+<li>A {@link org.apache.lucene.search.spans.SpanPositionRangeQuery SpanPositionRangeQuery} is
+a more general form of SpanFirstQuery that can constrain matches to arbitrary portions of the document.</li>
+
</ul>
In all cases, output spans are minimally inclusive. In other words, a