LUCENE-5339: javadocs
git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/branches/lucene5339@1554710 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/lucene/core/src/java/org/apache/lucene/document/Field.java b/lucene/core/src/java/org/apache/lucene/document/Field.java
index 07e31e9..67294e9 100644
--- a/lucene/core/src/java/org/apache/lucene/document/Field.java
+++ b/lucene/core/src/java/org/apache/lucene/document/Field.java
@@ -554,7 +554,7 @@
return analyzer.tokenStream(name(), stringValue());
}
- throw new IllegalArgumentException("Field must have either TokenStream, String, Reader or Number value; this=" + this);
+ throw new IllegalArgumentException("Field must have either TokenStream, String, Reader or Number value; got " + this);
}
static final class StringTokenStream extends TokenStream {
diff --git a/lucene/facet/build.xml b/lucene/facet/build.xml
index d6ed7de..c7dcdcd 100644
--- a/lucene/facet/build.xml
+++ b/lucene/facet/build.xml
@@ -24,7 +24,7 @@
</description>
<property name="forbidden-sysout-excludes" value="
- org/apache/lucene/facet/util/PrintTaxonomyStats.class
+ org/apache/lucene/facet/taxonomy/PrintTaxonomyStats.class
"/>
<import file="../module-build.xml"/>
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/CachedOrdinalsReader.java b/lucene/facet/src/java/org/apache/lucene/facet/CachedOrdinalsReader.java
index dc3ca6d..03c1da4 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/CachedOrdinalsReader.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/CachedOrdinalsReader.java
@@ -59,6 +59,7 @@
private final Map<Object,CachedOrds> ordsCache = new WeakHashMap<Object,CachedOrds>();
+ /** Sole constructor. */
public CachedOrdinalsReader(OrdinalsReader source) {
this.source = source;
}
@@ -94,8 +95,11 @@
/** Holds the cached ordinals in two paralel {@code int[]} arrays. */
public static final class CachedOrds {
-
+
+ /** Index into {@link #ordinals} for each document. */
public final int[] offsets;
+
+ /** Holds ords for all docs. */
public final int[] ordinals;
/**
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/DocValuesOrdinalsReader.java b/lucene/facet/src/java/org/apache/lucene/facet/DocValuesOrdinalsReader.java
index 0f91f3b..ab257ae 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/DocValuesOrdinalsReader.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/DocValuesOrdinalsReader.java
@@ -30,10 +30,12 @@
public class DocValuesOrdinalsReader extends OrdinalsReader {
private final String field;
+ /** Default constructor. */
public DocValuesOrdinalsReader() {
this(FacetsConfig.DEFAULT_INDEX_FIELD_NAME);
}
+ /** Create this, with the specified indexed field name. */
public DocValuesOrdinalsReader(String field) {
this.field = field;
}
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/DrillSideways.java b/lucene/facet/src/java/org/apache/lucene/facet/DrillSideways.java
index 92c5229..4e7296e 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/DrillSideways.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/DrillSideways.java
@@ -66,9 +66,17 @@
*/
public class DrillSideways {
+ /** {@link IndexSearcher} passed to constructor. */
protected final IndexSearcher searcher;
+
+ /** {@link TaxonomyReader} passed to constructor. */
protected final TaxonomyReader taxoReader;
+
+ /** {@link SortedSetDocValuesReaderState} passed to
+ * constructor; can be null. */
protected final SortedSetDocValuesReaderState state;
+
+ /** {@link FacetsConfig} passed to constructor. */
protected final FacetsConfig config;
/** Create a new {@code DrillSideways} instance. */
@@ -371,6 +379,8 @@
return false;
}
+ /** Result of a drill sideways search, including the
+ * {@link Facets} and {@link TopDocs}. */
public static class DrillSidewaysResult {
/** Combined drill down & sideways results. */
public final Facets facets;
@@ -378,6 +388,7 @@
/** Hits. */
public final TopDocs hits;
+ /** Sole constructor. */
public DrillSidewaysResult(Facets facets, TopDocs hits) {
this.facets = facets;
this.hits = hits;
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/FacetResult.java b/lucene/facet/src/java/org/apache/lucene/facet/FacetResult.java
index 9c35b1e..b90622d 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/FacetResult.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/FacetResult.java
@@ -19,6 +19,7 @@
import java.util.Arrays;
+/** Counts or aggregates for a single dimension. */
public final class FacetResult {
/** Dimension that was requested. */
@@ -38,6 +39,7 @@
/** Child counts. */
public final LabelAndValue[] labelValues;
+ /** Sole constructor. */
public FacetResult(String dim, String[] path, Number value, LabelAndValue[] labelValues, int childCount) {
this.dim = dim;
this.path = path;
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/Facets.java b/lucene/facet/src/java/org/apache/lucene/facet/Facets.java
index b63a7c5..4842603 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/Facets.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/Facets.java
@@ -25,6 +25,10 @@
* @lucene.experimental */
public abstract class Facets {
+ /** Default constructor. */
+ public Facets() {
+ }
+
/** Returns the topN child labels under the specified
* path. Returns null if the specified path doesn't
* exist or if this dimension was never seen. */
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/FacetsCollector.java b/lucene/facet/src/java/org/apache/lucene/facet/FacetsCollector.java
index 33fd31d..4f52d57 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/FacetsCollector.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/FacetsCollector.java
@@ -62,11 +62,19 @@
*/
public final static class MatchingDocs {
+ /** Context for this segment. */
public final AtomicReaderContext context;
+
+ /** Which documents were seen. */
public final FixedBitSet bits;
+
+ /** Non-sparse scores array. */
public final float[] scores;
- public final int totalHits;
+ /** Total number of hits */
+ public final int totalHits;
+
+ /** Sole constructor. */
public MatchingDocs(AtomicReaderContext context, FixedBitSet bits, int totalHits, float[] scores) {
this.context = context;
this.bits = bits;
@@ -75,14 +83,18 @@
}
}
+ /** Default constructor */
public FacetsCollector() {
this(false);
}
+ /** Create this; if {@code keepScores} is true then a
+ * float[] is allocated to hold score of all hits. */
public FacetsCollector(boolean keepScores) {
this.keepScores = keepScores;
}
+ /** True if scores were saved. */
public boolean getKeepScores() {
return keepScores;
}
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/FacetsConfig.java b/lucene/facet/src/java/org/apache/lucene/facet/FacetsConfig.java
index 1152a57..a2dc94e 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/FacetsConfig.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/FacetsConfig.java
@@ -59,6 +59,8 @@
* @lucene.experimental */
public class FacetsConfig {
+ /** Which Lucene field holds the drill-downs and ords (as
+ * doc values). */
public static final String DEFAULT_INDEX_FIELD_NAME = "$facets";
private final Map<String,DimConfig> fieldTypes = new ConcurrentHashMap<String,DimConfig>();
@@ -84,6 +86,10 @@
/** Actual field where this dimension's facet labels
* should be indexed */
public String indexFieldName = DEFAULT_INDEX_FIELD_NAME;
+
+ /** Default constructor. */
+ public DimConfig() {
+ }
}
/** Default per-dimension configuration. */
@@ -148,6 +154,7 @@
ft.indexFieldName = indexFieldName;
}
+ /** Returns map of field name to {@link DimConfig}. */
public Map<String,DimConfig> getDimConfigs() {
return fieldTypes;
}
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/LabelAndValue.java b/lucene/facet/src/java/org/apache/lucene/facet/LabelAndValue.java
index 88b871a..018d6a6 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/LabelAndValue.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/LabelAndValue.java
@@ -17,6 +17,8 @@
* limitations under the License.
*/
+/** Single label and its value, usually contained in a
+ * {@link FacetResult}. */
public final class LabelAndValue {
/** Facet's label. */
public final String label;
@@ -24,6 +26,7 @@
/** Value associated with this label. */
public final Number value;
+ /** Sole constructor. */
public LabelAndValue(String label, Number value) {
this.label = label;
this.value = value;
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/MultiFacets.java b/lucene/facet/src/java/org/apache/lucene/facet/MultiFacets.java
index 3558776..00cead2 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/MultiFacets.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/MultiFacets.java
@@ -27,10 +27,13 @@
private final Map<String,Facets> dimToFacets;
private final Facets defaultFacets;
+ /** Create this, with no default {@link Facets}. */
public MultiFacets(Map<String,Facets> dimToFacets) {
this(dimToFacets, null);
}
+ /** Create this, with the specified default {@link Facets}
+ * for fields not included in {@code dimToFacets}. */
public MultiFacets(Map<String,Facets> dimToFacets, Facets defaultFacets) {
this.dimToFacets = dimToFacets;
this.defaultFacets = defaultFacets;
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/OrdinalsReader.java b/lucene/facet/src/java/org/apache/lucene/facet/OrdinalsReader.java
index 666fd70..8a3224e 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/OrdinalsReader.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/OrdinalsReader.java
@@ -26,14 +26,25 @@
public abstract class OrdinalsReader {
+ /** Returns ordinals for documents in one segment. */
public static abstract class OrdinalsSegmentReader {
/** Get the ordinals for this document. ordinals.offset
* must always be 0! */
public abstract void get(int doc, IntsRef ordinals) throws IOException;
+
+ /** Default constructor. */
+ public OrdinalsSegmentReader() {
+ }
+ }
+
+ /** Default constructor. */
+ public OrdinalsReader() {
}
/** Set current atomic reader. */
public abstract OrdinalsSegmentReader getReader(AtomicReaderContext context) throws IOException;
+ /** Returns the indexed field name this {@code
+ * OrdinalsReader} is reading from. */
public abstract String getIndexFieldName();
}
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndFloatQueue.java b/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndFloatQueue.java
index 91d9e6d9..e6972d4 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndFloatQueue.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndFloatQueue.java
@@ -23,11 +23,21 @@
* then tie break by smallest ord. */
public class TopOrdAndFloatQueue extends PriorityQueue<TopOrdAndFloatQueue.OrdAndValue> {
+ /** Holds a single entry. */
public static final class OrdAndValue {
+
+ /** Ordinal of the entry. */
public int ord;
+
+ /** Value associated with the ordinal. */
public float value;
+
+ /** Default constructor. */
+ public OrdAndValue() {
+ }
}
+ /** Sole constructor. */
public TopOrdAndFloatQueue(int topN) {
super(topN, false);
}
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndIntQueue.java b/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndIntQueue.java
index 06fffb7..b605441 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndIntQueue.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/TopOrdAndIntQueue.java
@@ -23,11 +23,21 @@
* then tie break by smallest ord. */
public class TopOrdAndIntQueue extends PriorityQueue<TopOrdAndIntQueue.OrdAndValue> {
+ /** Holds a single entry. */
public static final class OrdAndValue {
+
+ /** Ordinal of the entry. */
public int ord;
+
+ /** Value associated with the ordinal. */
public int value;
+
+ /** Default constructor. */
+ public OrdAndValue() {
+ }
}
+ /** Sole constructor. */
public TopOrdAndIntQueue(int topN) {
super(topN, false);
}
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/range/DoubleRange.java b/lucene/facet/src/java/org/apache/lucene/facet/range/DoubleRange.java
index 55f5747..21423cf 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/range/DoubleRange.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/range/DoubleRange.java
@@ -26,7 +26,7 @@
import org.apache.lucene.search.DocIdSet;
import org.apache.lucene.search.DocIdSetIterator;
import org.apache.lucene.search.Filter;
-import org.apache.lucene.search.NumericRangeFilter;
+import org.apache.lucene.search.NumericRangeFilter; // javadocs
import org.apache.lucene.util.Bits;
import org.apache.lucene.util.NumericUtils;
@@ -35,9 +35,16 @@
final double minIncl;
final double maxIncl;
+ /** Minimum. */
public final double min;
+
+ /** Maximum. */
public final double max;
+
+ /** True if the minimum value is inclusive. */
public final boolean minInclusive;
+
+ /** True if the maximum value is inclusive. */
public final boolean maxInclusive;
/** Create a DoubleRange. */
@@ -76,6 +83,7 @@
this.maxIncl = maxIn;
}
+ /** True if this range accepts the provided value. */
public boolean accept(double value) {
return value >= minIncl && value <= maxIncl;
}
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/range/LongRange.java b/lucene/facet/src/java/org/apache/lucene/facet/range/LongRange.java
index 209d780..e2ee915 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/range/LongRange.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/range/LongRange.java
@@ -26,7 +26,7 @@
import org.apache.lucene.search.DocIdSet;
import org.apache.lucene.search.DocIdSetIterator;
import org.apache.lucene.search.Filter;
-import org.apache.lucene.search.NumericRangeFilter;
+import org.apache.lucene.search.NumericRangeFilter; // javadocs
import org.apache.lucene.util.Bits;
/** Represents a range over long values. */
@@ -34,9 +34,16 @@
final long minIncl;
final long maxIncl;
+ /** Minimum. */
public final long min;
+
+ /** Maximum. */
public final long max;
+
+ /** True if the minimum value is inclusive. */
public final boolean minInclusive;
+
+ /** True if the maximum value is inclusive. */
public final boolean maxInclusive;
// TODO: can we require fewer args? (same for
@@ -74,6 +81,7 @@
this.maxIncl = maxIn;
}
+ /** True if this range accepts the provided value. */
public boolean accept(long value) {
return value >= minIncl && value <= maxIncl;
}
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/range/Range.java b/lucene/facet/src/java/org/apache/lucene/facet/range/Range.java
index 2e191aa..b003b7f 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/range/Range.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/range/Range.java
@@ -21,8 +21,11 @@
*
* @lucene.experimental */
public abstract class Range {
+
+ /** Label that identifies this range. */
public final String label;
+ /** Sole constructor. */
protected Range(String label) {
if (label == null) {
throw new NullPointerException("label cannot be null");
@@ -30,6 +33,7 @@
this.label = label;
}
+ /** Invoke this for a useless range. */
protected void failNoMatch() {
throw new IllegalArgumentException("range \"" + label + "\" matches nothing");
}
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/range/RangeFacetCounts.java b/lucene/facet/src/java/org/apache/lucene/facet/range/RangeFacetCounts.java
index 39257a7..cd5c541 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/range/RangeFacetCounts.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/range/RangeFacetCounts.java
@@ -30,9 +30,16 @@
*
* @lucene.experimental */
abstract class RangeFacetCounts extends Facets {
+ /** Ranges passed to constructor. */
protected final Range[] ranges;
+
+ /** Counts, initialized in by subclass. */
protected final int[] counts;
+
+ /** Our field name. */
protected final String field;
+
+ /** Total number of hits. */
protected int totCount;
/** Create {@code RangeFacetCounts}, using {@link
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetCounts.java b/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetCounts.java
index 7491817..a8fcfc6 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetCounts.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetCounts.java
@@ -54,7 +54,7 @@
* then used from a single thread, because it holds a
* thread-private instance of {@link SortedSetDocValues}.
*
- * <p><b>NOTE:<b/>: tie-break is by unicode sort order
+ * <p><b>NOTE:</b>: tie-break is by unicode sort order
*
* @lucene.experimental */
public class SortedSetDocValuesFacetCounts extends Facets {
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetField.java b/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetField.java
index 9bdf243..33e5381 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetField.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesFacetField.java
@@ -30,10 +30,14 @@
TYPE.setIndexed(true);
TYPE.freeze();
}
-
+
+ /** Dimension. */
public final String dim;
+
+ /** Label. */
public final String label;
+ /** Sole constructor. */
public SortedSetDocValuesFacetField(String dim, String label) {
super("dummy", TYPE);
this.dim = dim;
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesReaderState.java b/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesReaderState.java
index 442d778..2518e6c 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesReaderState.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/sortedset/SortedSetDocValuesReaderState.java
@@ -50,6 +50,8 @@
private final String field;
private final AtomicReader topReader;
private final int valueCount;
+
+ /** {@link IndexReader} passed to the constructor. */
public final IndexReader origReader;
/** Holds start/end range of ords, which maps to one
@@ -126,22 +128,27 @@
}
}
+ /** Return top-level doc values. */
public SortedSetDocValues getDocValues() throws IOException {
return topReader.getSortedSetDocValues(field);
}
+ /** Returns mapping from prefix to {@link OrdRange}. */
public Map<String,OrdRange> getPrefixToOrdRange() {
return prefixToOrdRange;
}
+ /** Returns the {@link OrdRange} for this dimension. */
public OrdRange getOrdRange(String dim) {
return prefixToOrdRange.get(dim);
}
+ /** Indexed field we are reading. */
public String getField() {
return field;
}
+ /** Number of unique labels. */
public int getSize() {
return valueCount;
}
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/AssociationFacetField.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/AssociationFacetField.java
index b217c36..b03591d 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/AssociationFacetField.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/AssociationFacetField.java
@@ -43,8 +43,13 @@
TYPE.freeze();
}
+ /** Dimension for this field. */
public final String dim;
+
+ /** Facet path for this field. */
public final String[] path;
+
+ /** Associated value. */
public final BytesRef assoc;
/** Creates this from {@code dim} and {@code path} and an
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FacetLabel.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FacetLabel.java
index 94a5df6..ee14e7f 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FacetLabel.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FacetLabel.java
@@ -21,8 +21,8 @@
import java.util.Arrays;
-import org.apache.lucene.facet.taxonomy.writercache.LruTaxonomyWriterCache;
-import org.apache.lucene.facet.taxonomy.writercache.NameHashIntCacheLRU;
+import org.apache.lucene.facet.taxonomy.writercache.LruTaxonomyWriterCache; // javadocs
+import org.apache.lucene.facet.taxonomy.writercache.NameHashIntCacheLRU; // javadocs
/**
* Holds a sequence of string components, specifying the hierarchical name of a
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FloatTaxonomyFacets.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FloatTaxonomyFacets.java
index db4413c..d82db6e 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FloatTaxonomyFacets.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/FloatTaxonomyFacets.java
@@ -30,13 +30,16 @@
* to a per-ords float[]. */
public abstract class FloatTaxonomyFacets extends TaxonomyFacets {
+ /** Per-ordinal value. */
protected final float[] values;
+ /** Sole constructor. */
protected FloatTaxonomyFacets(String indexFieldName, TaxonomyReader taxoReader, FacetsConfig config) throws IOException {
super(indexFieldName, taxoReader, config);
values = new float[taxoReader.getSize()];
}
+ /** Rolls up any single-valued hierarchical dimensions. */
protected void rollup() throws IOException {
// Rollup any necessary dims:
for(Map.Entry<String,DimConfig> ent : config.getDimConfigs().entrySet()) {
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/IntTaxonomyFacets.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/IntTaxonomyFacets.java
index 498e638..bfc5ed5 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/IntTaxonomyFacets.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/IntTaxonomyFacets.java
@@ -31,13 +31,16 @@
public abstract class IntTaxonomyFacets extends TaxonomyFacets {
+ /** Per-ordinal value. */
protected final int[] values;
+ /** Sole constructor. */
protected IntTaxonomyFacets(String indexFieldName, TaxonomyReader taxoReader, FacetsConfig config) throws IOException {
super(indexFieldName, taxoReader, config);
values = new int[taxoReader.getSize()];
}
+ /** Rolls up any single-valued hierarchical dimensions. */
protected void rollup() throws IOException {
// Rollup any necessary dims:
for(Map.Entry<String,DimConfig> ent : config.getDimConfigs().entrySet()) {
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/ParallelTaxonomyArrays.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/ParallelTaxonomyArrays.java
index e27ffe5..fbfd912 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/ParallelTaxonomyArrays.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/ParallelTaxonomyArrays.java
@@ -42,6 +42,10 @@
*/
public abstract class ParallelTaxonomyArrays {
+ /** Sole constructor. */
+ public ParallelTaxonomyArrays() {
+ }
+
/**
* Returns the parents array, where {@code parents[i]} denotes the parent of
* category ordinal {@code i}.
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/PrintTaxonomyStats.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/PrintTaxonomyStats.java
index b063ce2..e30e534 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/PrintTaxonomyStats.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/PrintTaxonomyStats.java
@@ -31,6 +31,11 @@
// java -cp ../build/core/classes/java:../build/facet/classes/java org.apache.lucene.facet.util.PrintTaxonomyStats -printTree /s2/scratch/indices/wikibig.trunk.noparents.facets.Lucene41.nd1M/facets
public class PrintTaxonomyStats {
+ /** Sole constructor. */
+ public PrintTaxonomyStats() {
+ }
+
+ /** Command-line tool. */
public static void main(String[] args) throws IOException {
boolean printTree = false;
String path = null;
@@ -52,6 +57,7 @@
dir.close();
}
+ /** Recursively prints stats for all ordinals. */
public static void printStats(TaxonomyReader r, PrintStream out, boolean printTree) throws IOException {
out.println(r.getSize() + " total categories.");
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/SearcherTaxonomyManager.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/SearcherTaxonomyManager.java
index bb868ff..c4169ee 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/SearcherTaxonomyManager.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/SearcherTaxonomyManager.java
@@ -43,7 +43,10 @@
/** Holds a matched pair of {@link IndexSearcher} and
* {@link TaxonomyReader} */
public static class SearcherAndTaxonomy {
+ /** Point-in-time {@link IndexSearcher}. */
public final IndexSearcher searcher;
+
+ /** Matching point-in-time {@link DirectoryTaxonomyReader}. */
public final DirectoryTaxonomyReader taxonomyReader;
/** Create a SearcherAndTaxonomy */
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacetSumValueSource.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacetSumValueSource.java
index dca4d4c..3839177 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacetSumValueSource.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacetSumValueSource.java
@@ -112,6 +112,11 @@
* hit; use this to aggregate the sum of all hit scores
* for each facet label. */
public static class ScoreValueSource extends ValueSource {
+
+ /** Sole constructor. */
+ public ScoreValueSource() {
+ }
+
@Override
public FunctionValues getValues(@SuppressWarnings("rawtypes") Map context, AtomicReaderContext readerContext) throws IOException {
final Scorer scorer = (Scorer) context.get("scorer");
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacets.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacets.java
index c4ace0b..0c4d586 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacets.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyFacets.java
@@ -25,6 +25,7 @@
import org.apache.lucene.facet.FacetResult;
import org.apache.lucene.facet.Facets;
+import org.apache.lucene.facet.FacetsConfig.DimConfig; // javadocs
import org.apache.lucene.facet.FacetsConfig;
/** Base class for all taxonomy-based facets impls. */
@@ -43,12 +44,24 @@
}
};
+ /** Index field name provided to the constructor. */
protected final String indexFieldName;
+
+ /** {@code TaxonomyReader} provided to the constructor. */
protected final TaxonomyReader taxoReader;
+
+ /** {@code FacetsConfig} provided to the constructor. */
protected final FacetsConfig config;
+
+ /** Maps parent ordinal to its child, or -1 if the parent
+ * is childless. */
protected final int[] children;
+
+ /** Maps an ordinal to its sibling, or -1 if there is no
+ * sibling. */
protected final int[] siblings;
+ /** Sole constructor. */
protected TaxonomyFacets(String indexFieldName, TaxonomyReader taxoReader, FacetsConfig config) throws IOException {
this.indexFieldName = indexFieldName;
this.taxoReader = taxoReader;
@@ -58,6 +71,9 @@
siblings = pta.siblings();
}
+ /** Throws {@code IllegalArgumentException} if the
+ * dimension is not recognized. Otherwise, returns the
+ * {@link DimConfig} for this dimension. */
protected FacetsConfig.DimConfig verifyDim(String dim) {
FacetsConfig.DimConfig dimConfig = config.getDimConfig(dim);
if (!dimConfig.indexFieldName.equals(indexFieldName)) {
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyReader.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyReader.java
index 921f5b2..a7b2240 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyReader.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/TaxonomyReader.java
@@ -89,6 +89,10 @@
}
}
+
+ /** Sole constructor. */
+ public TaxonomyReader() {
+ }
/**
* The root category (the category with the empty path) always has the ordinal
@@ -142,7 +146,7 @@
protected abstract TaxonomyReader doOpenIfChanged() throws IOException;
/**
- * @throws AlreadyClosedException if this IndexReader is closed
+ * Throws {@link AlreadyClosedException} if this IndexReader is closed
*/
protected final void ensureOpen() throws AlreadyClosedException {
if (getRefCount() <= 0) {
@@ -217,6 +221,7 @@
*/
public abstract int getOrdinal(FacetLabel categoryPath) throws IOException;
+ /** Returns ordinal for the dim + path. */
public int getOrdinal(String dim, String[] path) throws IOException {
String[] fullPath = new String[path.length+1];
fullPath[0] = dim;
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyReader.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyReader.java
index 931e3b8..0d4d6ce 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyReader.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyReader.java
@@ -208,10 +208,14 @@
}
}
+ /** Open the {@link DirectoryReader} from this {@link
+ * Directory}. */
protected DirectoryReader openIndexReader(Directory directory) throws IOException {
return DirectoryReader.open(directory);
}
+ /** Open the {@link DirectoryReader} from this {@link
+ * IndexWriter}. */
protected DirectoryReader openIndexReader(IndexWriter writer) throws IOException {
return DirectoryReader.open(writer, false);
}
@@ -342,6 +346,9 @@
}
}
+ /** Returns ordinal -> label mapping, up to the provided
+ * max ordinal or number of ordinals, whichever is
+ * smaller. */
public String toString(int max) {
ensureOpen();
StringBuilder sb = new StringBuilder();
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyWriter.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyWriter.java
index edf25f6..9d5b24d 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyWriter.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/directory/DirectoryTaxonomyWriter.java
@@ -326,6 +326,7 @@
return new Cl2oTaxonomyWriterCache(1024, 0.15f, 3);
}
+ /** Create this with {@code OpenMode.CREATE_OR_APPEND}. */
public DirectoryTaxonomyWriter(Directory d) throws IOException {
this(d, OpenMode.CREATE_OR_APPEND);
}
@@ -840,12 +841,16 @@
* and size-1.
*/
public void setSize(int size) throws IOException;
+
+ /** Record a mapping. */
public void addMapping(int origOrdinal, int newOrdinal) throws IOException;
+
/**
* Call addDone() to say that all addMapping() have been done.
* In some implementations this might free some resources.
*/
public void addDone() throws IOException;
+
/**
* Return the map from the taxonomy's original (consecutive) ordinals
* to the new taxonomy's ordinals. If the map has to be read from disk
@@ -862,6 +867,11 @@
*/
public static final class MemoryOrdinalMap implements OrdinalMap {
int[] map;
+
+ /** Sole constructor. */
+ public MemoryOrdinalMap() {
+ }
+
@Override
public void setSize(int taxonomySize) {
map = new int[taxonomySize];
@@ -885,6 +895,7 @@
File tmpfile;
DataOutputStream out;
+ /** Sole constructor. */
public DiskOrdinalMap(File tmpfile) throws FileNotFoundException {
this.tmpfile = tmpfile;
out = new DataOutputStream(new BufferedOutputStream(
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/Cl2oTaxonomyWriterCache.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/Cl2oTaxonomyWriterCache.java
index abbac2d..9d678f0 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/Cl2oTaxonomyWriterCache.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/Cl2oTaxonomyWriterCache.java
@@ -39,6 +39,7 @@
private volatile CompactLabelToOrdinal cache;
+ /** Sole constructor. */
public Cl2oTaxonomyWriterCache(int initialCapcity, float loadFactor, int numHashArrays) {
this.cache = new CompactLabelToOrdinal(initialCapcity, loadFactor, numHashArrays);
this.initialCapcity = initialCapcity;
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CollisionMap.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CollisionMap.java
index bcd3b9a..28cc8ee 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CollisionMap.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CollisionMap.java
@@ -70,10 +70,12 @@
this.threshold = (int) (this.capacity * this.loadFactor);
}
+ /** How many mappings. */
public int size() {
return this.size;
}
+ /** How many slots are allocated. */
public int capacity() {
return this.capacity;
}
@@ -103,6 +105,9 @@
this.threshold = (int) (this.capacity * this.loadFactor);
}
+ /** Return the mapping, or {@link
+ * LabelToOrdinal#INVALID_ORDINAL} if the label isn't
+ * recognized. */
public int get(FacetLabel label, int hash) {
int bucketIndex = indexFor(hash, this.capacity);
Entry e = this.entries[bucketIndex];
@@ -117,6 +122,7 @@
return e.cid;
}
+ /** Add another mapping. */
public int addLabel(FacetLabel label, int hash, int cid) {
int bucketIndex = indexFor(hash, this.capacity);
for (Entry e = this.entries[bucketIndex]; e != null; e = e.next) {
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CompactLabelToOrdinal.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CompactLabelToOrdinal.java
index 4db48a9..a9af612 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CompactLabelToOrdinal.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/CompactLabelToOrdinal.java
@@ -55,6 +55,7 @@
*/
public class CompactLabelToOrdinal extends LabelToOrdinal {
+ /** Default maximum load factor. */
public static final float DefaultLoadFactor = 0.15f;
static final char TERMINATOR_CHAR = 0xffff;
@@ -68,6 +69,7 @@
private int threshold;
private float loadFactor;
+ /** How many labels. */
public int sizeOfMap() {
return this.collisionMap.size();
}
@@ -75,6 +77,7 @@
private CompactLabelToOrdinal() {
}
+ /** Sole constructor. */
public CompactLabelToOrdinal(int initialCapacity, float loadFactor,
int numHashArrays) {
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LabelToOrdinal.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LabelToOrdinal.java
index 33b60fe..49473be 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LabelToOrdinal.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LabelToOrdinal.java
@@ -26,9 +26,17 @@
*/
public abstract class LabelToOrdinal {
+ /** How many ordinals we've seen. */
protected int counter;
+
+ /** Returned by {@link #getOrdinal} when the label isn't
+ * recognized. */
public static final int INVALID_ORDINAL = -2;
+ /** Default constructor. */
+ public LabelToOrdinal() {
+ }
+
/**
* return the maximal Ordinal assigned so far
*/
@@ -52,7 +60,7 @@
public abstract void addLabel(FacetLabel label, int ordinal);
/**
- * @return the ordinal assigned to the given label,
+ * Returns the ordinal assigned to the given label,
* or {@link #INVALID_ORDINAL} if the label cannot be found in this table.
*/
public abstract int getOrdinal(FacetLabel label);
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LruTaxonomyWriterCache.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LruTaxonomyWriterCache.java
index 7bdbb2c..1393a0d 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LruTaxonomyWriterCache.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/LruTaxonomyWriterCache.java
@@ -32,10 +32,19 @@
* For guaranteed correctness - not relying on no-collisions in the hash
* function, LRU_STRING should be used.
*/
- public enum LRUType { LRU_HASHED, LRU_STRING }
+ public enum LRUType {
+ /** Use the label's hash as the key; this can lead to
+ * silent conflicts! */
+ LRU_HASHED,
+
+ /** Use the label as the hash key; this is always
+ * correct but will usually use more RAM. */
+ LRU_STRING
+ }
private NameIntCacheLRU cache;
+ /** Creates this with {@link LRUType#LRU_HASHED} method. */
public LruTaxonomyWriterCache(int cacheSize) {
// TODO (Facet): choose between NameHashIntCacheLRU and NameIntCacheLRU.
// For guaranteed correctness - not relying on no-collisions in the hash
@@ -46,6 +55,7 @@
this(cacheSize, LRUType.LRU_HASHED);
}
+ /** Creates this with the specified method. */
public LruTaxonomyWriterCache(int cacheSize, LRUType lruType) {
// TODO (Facet): choose between NameHashIntCacheLRU and NameIntCacheLRU.
// For guaranteed correctness - not relying on no-collisions in the hash
diff --git a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/NameIntCacheLRU.java b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/NameIntCacheLRU.java
index f43b6b1..1626ada 100644
--- a/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/NameIntCacheLRU.java
+++ b/lucene/facet/src/java/org/apache/lucene/facet/taxonomy/writercache/NameIntCacheLRU.java
@@ -42,10 +42,12 @@
createCache(maxCacheSize);
}
+ /** Maximum number of cache entries before eviction. */
public int getMaxSize() {
return maxCacheSize;
}
+ /** Number of entries currently in the cache. */
public int getSize() {
return cache.size();
}
