diff --git a/src/Lucene.Net.Grouping/GroupingSearch.cs b/src/Lucene.Net.Grouping/GroupingSearch.cs index baca7eb329..c5d471c926 100644 --- a/src/Lucene.Net.Grouping/GroupingSearch.cs +++ b/src/Lucene.Net.Grouping/GroupingSearch.cs @@ -30,37 +30,108 @@ namespace Lucene.Net.Search.Grouping /// /// Convenience class to perform grouping in a non distributed environment. + /// + /// LUCENENET Note: This class has been significantly changed from Lucene. + /// The previous implementation combined field, function, and doc block grouping + /// into one large class and required the use of Java's generic type erasure and + /// wildcard generics to handle the different types of grouping. This implementation + /// splits the different types of grouping into separate classes and uses a common + /// base class to handle the common functionality. + /// + /// This class contains three static factory methods to create instances of the + /// different types of grouping: + /// + /// + /// + /// - Constructs a instance + /// that groups documents by index terms using the . + /// The group field can only have one token per document. This means that the field must not be analysed. + /// + /// + /// + /// + /// - Constructs a instance + /// that groups documents by function using a instance. + /// + /// + /// + /// + /// - Constructs a instance + /// that groups documents by doc block. This method can only be used when documents belonging in a group are indexed in one block. + /// + /// + /// + /// These types each return a type that behaves like the original GroupingSearch class, + /// but specific to the type of grouping being performed. + /// + /// It is not required to use these methods; you can also create instances of the + /// specific grouping classes directly which will be closer to the original Lucene + /// usage. + /// /// @lucene.experimental /// + /// + /// + /// public static class GroupingSearch { + /// + /// Constructs a instance that groups documents by index terms using the . + /// The group field can only have one token per document. This means that the field must not be analysed. + /// + /// The name of the field to group by. + /// A instance. public static FieldGroupingSearch ByField(string groupField) { return new FieldGroupingSearch(groupField); } + /// + /// Constructs a instance that groups documents by function using a instance. + /// + /// The function to group by specified as + /// The context of the specified groupFunction + /// The type of the mutable value + /// A instance. public static FunctionGroupingSearch ByFunction(ValueSource groupFunction, IDictionary valueSourceContext) where TMutableValue : MutableValue { return new FunctionGroupingSearch(groupFunction, valueSourceContext); } + /// + /// Constructs a instance that groups documents by doc block. + /// This method can only be used when documents belonging in a group are indexed in one block. + /// + /// The filter that marks the last document in all doc blocks + /// The type of the group value + /// A instance. public static DocBlockGroupingSearch ByDocBlock(Filter groupEndDocs) { return new DocBlockGroupingSearch(groupEndDocs); } } + /// + /// A grouping search that groups documents by index terms using the . + /// The group field can only have one token per document. This means that the field must not be analysed. + /// + /// public class FieldGroupingSearch : AbstractFieldOrFunctionGroupingSearch { private readonly string groupField; private int initialSize = 128; + /// + /// Constructs a instance that groups documents by index terms using the . + /// + /// The name of the field to group by. public FieldGroupingSearch(string groupField) { this.groupField = groupField; } + /// public override TopGroups Search(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit) { int topN = groupOffset + groupLimit; @@ -179,7 +250,6 @@ public override TopGroups Search(IndexSearcher searcher, Filter filter } } - /// /// Sets the initial size of some internal used data structures. /// This prevents growing data structures many times. This can improve the performance of the grouping at the cost of @@ -199,18 +269,29 @@ public virtual FieldGroupingSearch SetInitialSize(int initialSize) } } + /// + /// A grouping search that groups documents by function using a instance. + /// + /// The type of the mutable value + /// public class FunctionGroupingSearch : AbstractFieldOrFunctionGroupingSearch where T : MutableValue { private readonly ValueSource groupFunction; private readonly IDictionary /* Map */ valueSourceContext; + /// + /// Constructs a instance that groups documents by function using a instance. + /// + /// The function to group by specified as + /// The context of the specified groupFunction public FunctionGroupingSearch(ValueSource groupFunction, IDictionary /* Map */ valueSourceContext) { this.groupFunction = groupFunction; this.valueSourceContext = valueSourceContext; } + /// public override TopGroups Search(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit) { int topN = groupOffset + groupLimit; @@ -332,15 +413,26 @@ public override TopGroups Search(IndexSearcher searcher, Filter filter, Query } } + /// + /// A grouping search that groups documents by doc block. + /// This class can only be used when documents belonging in a group are indexed in one block. + /// + /// The type of the group value public class DocBlockGroupingSearch : AbstractGroupingSearch { private readonly Filter groupEndDocs; + /// + /// Constructs a instance that groups documents by doc block. + /// This class can only be used when documents belonging in a group are indexed in one block. + /// + /// The filter that marks the last document in all doc blocks public DocBlockGroupingSearch(Filter groupEndDocs) { this.groupEndDocs = groupEndDocs; } + /// public override TopGroups Search(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit) { int topN = groupOffset + groupLimit; @@ -351,6 +443,10 @@ public override TopGroups Search(IndexSearcher searcher, Filter filter, Query } } + /// + /// Abstract base class for grouping search implementations that groups documents by index terms or function. + /// + /// The type of the group value public abstract class AbstractFieldOrFunctionGroupingSearch : AbstractGroupingSearch { // LUCENENET: Converted to protected properties @@ -469,6 +565,10 @@ public virtual IBits GetAllGroupHeads() } } + /// + /// Abstract base class for grouping search implementations. + /// + /// The type of the group value public abstract class AbstractGroupingSearch { // LUCENENET: Converted to protected properties @@ -480,11 +580,28 @@ public abstract class AbstractGroupingSearch protected bool FillSortFields { get; private set; } protected bool IncludeScores { get; private set; } = true; + /// + /// Executes a grouped search. Both the first pass and second pass are executed on the specified searcher. + /// + /// The instance to execute the grouped search on. + /// The query to execute with the grouping + /// The group offset + /// The number of groups to return from the specified group offset + /// the grouped result as a instance public TopGroups Search(IndexSearcher searcher, Query query, int groupOffset, int groupLimit) { return Search(searcher, null, query, groupOffset, groupLimit); } + /// + /// Executes a grouped search. Both the first pass and second pass are executed on the specified searcher. + /// + /// The instance to execute the grouped search on. + /// The filter to execute with the grouping + /// The query to execute with the grouping + /// The group offset + /// The number of groups to return from the specified group offset + /// the grouped result as a instance public abstract TopGroups Search(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit); ///