| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.apache.lucene.search; |
| |
| |
| import java.util.Objects; |
| |
| import org.apache.lucene.index.Term; |
| import org.apache.lucene.index.TermsEnum; // javadocs |
| import org.apache.lucene.util.BytesRef; |
| /** |
| * Contains statistics for a specific term |
| * <p> |
| * This class holds statistics for this term across all documents for scoring purposes: |
| * <ul> |
| * <li> {@link #docFreq}: number of documents this term occurs in. |
| * <li> {@link #totalTermFreq}: number of tokens for this term. |
| * </ul> |
| * <p> |
| * The following conditions are always true: |
| * <ul> |
| * <li> All statistics are positive integers: never zero or negative. |
| * <li> {@code docFreq} <= {@code totalTermFreq} |
| * <li> {@code docFreq} <= {@code sumDocFreq} of the collection |
| * <li> {@code totalTermFreq} <= {@code sumTotalTermFreq} of the collection |
| * </ul> |
| * <p> |
| * Values may include statistics on deleted documents that have not yet been merged away. |
| * <p> |
| * Be careful when performing calculations on these values because they are represented |
| * as 64-bit integer values, you may need to cast to {@code double} for your use. |
| * @lucene.experimental |
| */ |
| // TODO: actually add missing cross-checks to guarantee TermStatistics is in bounds of CollectionStatistics, |
| // otherwise many similarity functions will implode. |
| public class TermStatistics { |
| private final BytesRef term; |
| private final long docFreq; |
| private final long totalTermFreq; |
| |
| /** |
| * Creates statistics instance for a term. |
| * @param term Term bytes |
| * @param docFreq number of documents containing the term in the collection. |
| * @param totalTermFreq number of occurrences of the term in the collection. |
| * @throws NullPointerException if {@code term} is {@code null}. |
| * @throws IllegalArgumentException if {@code docFreq} is negative or zero. |
| * @throws IllegalArgumentException if {@code totalTermFreq} is less than {@code docFreq}. |
| */ |
| public TermStatistics(BytesRef term, long docFreq, long totalTermFreq) { |
| Objects.requireNonNull(term); |
| if (docFreq <= 0) { |
| throw new IllegalArgumentException("docFreq must be positive, docFreq: " + docFreq); |
| } |
| if (totalTermFreq <= 0) { |
| throw new IllegalArgumentException("totalTermFreq must be positive, totalTermFreq: " + totalTermFreq); |
| } |
| if (totalTermFreq < docFreq) { |
| throw new IllegalArgumentException("totalTermFreq must be at least docFreq, totalTermFreq: " + totalTermFreq + ", docFreq: " + docFreq); |
| } |
| this.term = term; |
| this.docFreq = docFreq; |
| this.totalTermFreq = totalTermFreq; |
| } |
| |
| /** |
| * The term text. |
| * <p> |
| * This value is never {@code null}. |
| * @return term's text, not {@code null} |
| */ |
| public final BytesRef term() { |
| return term; |
| } |
| |
| /** |
| * The number of documents this term occurs in. |
| * <p> |
| * This is the document-frequency for the term: the count of documents |
| * where the term appears at least one time. |
| * <p> |
| * This value is always a positive number, and never |
| * exceeds {@link #totalTermFreq}. It also cannot exceed {@link CollectionStatistics#sumDocFreq()}. |
| * @return document frequency, in the range [1 .. {@link #totalTermFreq()}] |
| * @see TermsEnum#docFreq() |
| */ |
| public final long docFreq() { |
| return docFreq; |
| } |
| |
| /** |
| * The total number of occurrences of this term. |
| * <p> |
| * This is the token count for the term: the number of times it appears in the field across all documents. |
| * <p> |
| * This value is always a positive number, always at least {@link #docFreq()}, |
| * and never exceeds {@link CollectionStatistics#sumTotalTermFreq()}. |
| * @return number of occurrences, in the range [{@link #docFreq()} .. {@link CollectionStatistics#sumTotalTermFreq()}] |
| * @see TermsEnum#totalTermFreq() |
| */ |
| public final long totalTermFreq() { |
| return totalTermFreq; |
| } |
| |
| @Override |
| public String toString() { |
| StringBuilder sb = new StringBuilder(); |
| sb.append("term="); |
| sb.append('"'); |
| sb.append(Term.toString(term())); |
| sb.append('"'); |
| sb.append(",docFreq="); |
| sb.append(docFreq()); |
| sb.append(",totalTermFreq="); |
| sb.append(totalTermFreq()); |
| return sb.toString(); |
| } |
| } |