You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucenenet.apache.org by ni...@apache.org on 2016/11/10 11:34:05 UTC
[54/58] [abbrv] lucenenet git commit: Grouping: Fixed up
documentation comments and license headers
Grouping: Fixed up documentation comments and license headers
Project: http://git-wip-us.apache.org/repos/asf/lucenenet/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucenenet/commit/a0a61e24
Tree: http://git-wip-us.apache.org/repos/asf/lucenenet/tree/a0a61e24
Diff: http://git-wip-us.apache.org/repos/asf/lucenenet/diff/a0a61e24
Branch: refs/heads/grouping
Commit: a0a61e243005254e8a92358456fb34a77a678f4d
Parents: d0838cc
Author: Shad Storhaug <sh...@shadstorhaug.com>
Authored: Mon Nov 7 05:30:06 2016 +0700
Committer: Shad Storhaug <sh...@shadstorhaug.com>
Committed: Tue Nov 8 02:48:33 2016 +0700
----------------------------------------------------------------------
.../AbstractAllGroupHeadsCollector.cs | 29 +-
.../AbstractAllGroupsCollector.cs | 17 +
.../AbstractDistinctValuesCollector.cs | 21 ++
.../AbstractFirstPassGroupingCollector.cs | 28 +-
.../AbstractGroupFacetCollector.cs | 116 ++++---
.../AbstractSecondPassGroupingCollector.cs | 38 +-
.../BlockGroupingCollector.cs | 138 +++++---
src/Lucene.Net.Grouping/CollectedSearchGroup.cs | 21 +-
.../Function/FunctionAllGroupHeadsCollector.cs | 38 +-
.../Function/FunctionAllGroupsCollector.cs | 28 +-
.../Function/FunctionDistinctValuesCollector.cs | 27 +-
.../FunctionFirstPassGroupingCollector.cs | 17 +
.../FunctionSecondPassGroupingCollector.cs | 17 +
src/Lucene.Net.Grouping/GroupDocs.cs | 1 +
src/Lucene.Net.Grouping/GroupingSearch.cs | 345 ++++++++++---------
src/Lucene.Net.Grouping/SearchGroup.cs | 73 +++-
.../Term/TermAllGroupHeadsCollector.cs | 110 ++++--
.../Term/TermAllGroupsCollector.cs | 17 +
.../Term/TermDistinctValuesCollector.cs | 38 +-
.../Term/TermFirstPassGroupingCollector.cs | 17 +
.../Term/TermGroupFacetCollector.cs | 52 ++-
.../Term/TermSecondPassGroupingCollector.cs | 17 +
src/Lucene.Net.Grouping/TopGroups.cs | 2 +-
.../AbstractGroupingTestCase.cs | 17 +
.../AllGroupHeadsCollectorTest.cs | 17 +
.../AllGroupsCollectorTest.cs | 17 +
.../DistinctValuesCollectorTest.cs | 17 +
.../GroupFacetCollectorTest.cs | 17 +
.../GroupingSearchTest.cs | 17 +
29 files changed, 934 insertions(+), 375 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/AbstractAllGroupHeadsCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/AbstractAllGroupHeadsCollector.cs b/src/Lucene.Net.Grouping/AbstractAllGroupHeadsCollector.cs
index 279805e..bf3d984 100644
--- a/src/Lucene.Net.Grouping/AbstractAllGroupHeadsCollector.cs
+++ b/src/Lucene.Net.Grouping/AbstractAllGroupHeadsCollector.cs
@@ -3,6 +3,29 @@ using System.Collections.Generic;
namespace Lucene.Net.Search.Grouping
{
+ /*
+ * 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.
+ */
+
+ /// <summary>
+ /// This collector specializes in collecting the most relevant document (group head) for each group that match the query.
+ ///
+ /// @lucene.experimental
+ /// </summary>
+ /// <typeparam name="GH"></typeparam>
public abstract class AbstractAllGroupHeadsCollector<GH> : AbstractAllGroupHeadsCollector
where GH : AbstractAllGroupHeadsCollector_GroupHead
{
@@ -127,12 +150,10 @@ namespace Lucene.Net.Search.Grouping
/// Contains the result of group head retrieval.
/// To prevent new object creations of this class for every collect.
/// </summary>
- public class TemporalResult
+ protected class TemporalResult
{
-
public GH groupHead;
public bool stop;
-
}
}
@@ -144,7 +165,7 @@ namespace Lucene.Net.Search.Grouping
/// </para>
/// </summary>
/// <remarks>
- /// LUCENENET: moved this class from of the <see cref="AbstractAllGroupHeadsCollector{TGroupValue}"/>,
+ /// LUCENENET: moved this class from being a nested class of <see cref="AbstractAllGroupHeadsCollector{TGroupValue}"/>,
/// made it non-generic so the generic closing type doesn't need to be specified in classes that
/// use <see cref="AbstractAllGroupHeadsCollector_GroupHead"/> as a generic closing type, and renamed
/// it from GroupHead to <see cref="AbstractAllGroupHeadsCollector_GroupHead"/> to avoid naming conflicts with nested classes
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/AbstractAllGroupsCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/AbstractAllGroupsCollector.cs b/src/Lucene.Net.Grouping/AbstractAllGroupsCollector.cs
index 6f1edb4..a40d0d7 100644
--- a/src/Lucene.Net.Grouping/AbstractAllGroupsCollector.cs
+++ b/src/Lucene.Net.Grouping/AbstractAllGroupsCollector.cs
@@ -3,6 +3,23 @@ using System.Linq;
namespace Lucene.Net.Search.Grouping
{
+ /*
+ * 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.
+ */
+
/// <summary>
/// A collector that collects all groups that match the
/// query. Only the group value is collected, and the order
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/AbstractDistinctValuesCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/AbstractDistinctValuesCollector.cs b/src/Lucene.Net.Grouping/AbstractDistinctValuesCollector.cs
index f832b1b..5acc02f 100644
--- a/src/Lucene.Net.Grouping/AbstractDistinctValuesCollector.cs
+++ b/src/Lucene.Net.Grouping/AbstractDistinctValuesCollector.cs
@@ -2,6 +2,23 @@
namespace Lucene.Net.Search.Grouping
{
+ /*
+ * 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.
+ */
+
/// <summary>
/// A second pass grouping collector that keeps track of distinct values for a specified field for the top N group.
///
@@ -80,6 +97,10 @@ namespace Lucene.Net.Search.Grouping
/// <typeparam name="GC"></typeparam>
public interface IAbstractDistinctValuesCollector<out GC>
{
+ /// <summary>
+ /// Returns all unique values for each top N group.
+ /// </summary>
+ /// <returns>all unique values for each top N group</returns>
IEnumerable<GC> Groups { get; }
}
}
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/AbstractFirstPassGroupingCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/AbstractFirstPassGroupingCollector.cs b/src/Lucene.Net.Grouping/AbstractFirstPassGroupingCollector.cs
index aae0591..62440f1 100644
--- a/src/Lucene.Net.Grouping/AbstractFirstPassGroupingCollector.cs
+++ b/src/Lucene.Net.Grouping/AbstractFirstPassGroupingCollector.cs
@@ -7,6 +7,23 @@ using System.Linq;
namespace Lucene.Net.Search.Grouping
{
+ /*
+ * 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.
+ */
+
/// <summary>
/// FirstPassGroupingCollector is the first of two passes necessary
/// to collect grouped hits. This pass gathers the top N sorted
@@ -14,7 +31,7 @@ namespace Lucene.Net.Search.Grouping
/// is internally collected.
///
/// <para>
- /// See {@link org.apache.lucene.search.grouping} for more
+ /// See <a href="https://github.com/apache/lucene-solr/blob/releases/lucene-solr/4.8.0/lucene/grouping/src/java/org/apache/lucene/search/grouping/package.html">org.apache.lucene.search.grouping</a> for more
/// details including a full code example.
/// </para>
/// @lucene.experimental
@@ -39,7 +56,7 @@ namespace Lucene.Net.Search.Grouping
/// Create the first pass collector.
/// </summary>
/// <param name="groupSort">
- /// The {@link Sort} used to sort the
+ /// The <see cref="Sort"/> used to sort the
/// groups. The top sorted document within each group
/// according to groupSort, determines how that group
/// sorts against other groups. This must be non-null,
@@ -404,12 +421,11 @@ namespace Lucene.Net.Search.Grouping
/// <summary>
/// LUCENENET specific interface used to apply covariance to TGroupValue
+ /// to simulate Java's wildcard generics.
/// </summary>
/// <typeparam name="TGroupValue"></typeparam>
public interface IAbstractFirstPassGroupingCollector<out TGroupValue>
{
- // LUCENENET NOTE: We must use IEnumerable rather than ICollection here because we need
- // this to be covariant
/// <summary>
/// Returns top groups, starting from offset. This may
/// return null, if no groups were collected, or if the
@@ -418,6 +434,10 @@ namespace Lucene.Net.Search.Grouping
/// <param name="groupOffset">The offset in the collected groups</param>
/// <param name="fillFields">Whether to fill to <see cref="SearchGroup.sortValues"/></param>
/// <returns>top groups, starting from offset</returns>
+ /// <remarks>
+ /// LUCENENET NOTE: We must use <see cref="IEnumerable{TGroupValue}"/> rather than
+ /// <see cref="ICollection{TGroupValue}"/> here because we need this to be covariant
+ /// </remarks>
IEnumerable<ISearchGroup<TGroupValue>> GetTopGroups(int groupOffset, bool fillFields);
}
}
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/AbstractGroupFacetCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/AbstractGroupFacetCollector.cs b/src/Lucene.Net.Grouping/AbstractGroupFacetCollector.cs
index 9a079e8..6e3e014 100644
--- a/src/Lucene.Net.Grouping/AbstractGroupFacetCollector.cs
+++ b/src/Lucene.Net.Grouping/AbstractGroupFacetCollector.cs
@@ -4,6 +4,23 @@ using System.Collections.Generic;
namespace Lucene.Net.Search.Grouping
{
+ /*
+ * 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.
+ */
+
/// <summary>
/// Base class for computing grouped facets.
/// @lucene.experimental
@@ -28,17 +45,18 @@ namespace Lucene.Net.Search.Grouping
segmentResults = new List<AbstractSegmentResult>();
}
- /**
- * Returns grouped facet results that were computed over zero or more segments.
- * Grouped facet counts are merged from zero or more segment results.
- *
- * @param size The total number of facets to include. This is typically offset + limit
- * @param minCount The minimum count a facet entry should have to be included in the grouped facet result
- * @param orderByCount Whether to sort the facet entries by facet entry count. If <code>false</code> then the facets
- * are sorted lexicographically in ascending order.
- * @return grouped facet results
- * @throws IOException If I/O related errors occur during merging segment grouped facet counts.
- */
+ /// <summary>
+ /// Returns grouped facet results that were computed over zero or more segments.
+ /// Grouped facet counts are merged from zero or more segment results.
+ /// </summary>
+ /// <param name="size">The total number of facets to include. This is typically offset + limit</param>
+ /// <param name="minCount">The minimum count a facet entry should have to be included in the grouped facet result</param>
+ /// <param name="orderByCount">
+ /// Whether to sort the facet entries by facet entry count. If <c>false</c> then the facets
+ /// are sorted lexicographically in ascending order.
+ /// </param>
+ /// <returns>grouped facet results</returns>
+ /// <exception cref="IOException">If I/O related errors occur during merging segment grouped facet counts.</exception>
public GroupedFacetResult MergeSegmentResults(int size, int minCount, bool orderByCount)
{
if (segmentFacetCounts != null)
@@ -126,9 +144,9 @@ namespace Lucene.Net.Search.Grouping
}
}
- /**
- * The grouped facet result. Containing grouped facet entries, total count and total missing count.
- */
+ /// <summary>
+ /// The grouped facet result. Containing grouped facet entries, total count and total missing count.
+ /// </summary>
public class GroupedFacetResult
{
private readonly static IComparer<FacetEntry> orderByCountAndValue = new OrderByCountAndValueComparer();
@@ -175,14 +193,13 @@ namespace Lucene.Net.Search.Grouping
}
}
- /**
- * Returns a list of facet entries to be rendered based on the specified offset and limit.
- * The facet entries are retrieved from the facet entries collected during merging.
- *
- * @param offset The offset in the collected facet entries during merging
- * @param limit The number of facets to return starting from the offset.
- * @return a list of facet entries to be rendered based on the specified offset and limit
- */
+ /// <summary>
+ /// Returns a list of facet entries to be rendered based on the specified offset and limit.
+ /// The facet entries are retrieved from the facet entries collected during merging.
+ /// </summary>
+ /// <param name="offset">The offset in the collected facet entries during merging</param>
+ /// <param name="limit">The number of facets to return starting from the offset.</param>
+ /// <returns>a list of facet entries to be rendered based on the specified offset and limit</returns>
public List<FacetEntry> GetFacetEntries(int offset, int limit)
{
List<FacetEntry> entries = new List<FacetEntry>();
@@ -205,11 +222,9 @@ namespace Lucene.Net.Search.Grouping
return entries;
}
- /**
- * Returns the sum of all facet entries counts.
- *
- * @return the sum of all facet entries counts
- */
+ /// <summary>
+ /// Gets the sum of all facet entries counts.
+ /// </summary>
public int TotalCount
{
get
@@ -218,11 +233,9 @@ namespace Lucene.Net.Search.Grouping
}
}
- /**
- * Returns the number of groups that didn't have a facet value.
- *
- * @return the number of groups that didn't have a facet value
- */
+ /// <summary>
+ /// Gets the number of groups that didn't have a facet value.
+ /// </summary>
public int TotalMissingCount
{
get
@@ -232,9 +245,9 @@ namespace Lucene.Net.Search.Grouping
}
}
- /**
- * Represents a facet entry with a value and a count.
- */
+ /// <summary>
+ /// Represents a facet entry with a value and a count.
+ /// </summary>
public class FacetEntry
{
@@ -275,9 +288,9 @@ namespace Lucene.Net.Search.Grouping
'}';
}
- /**
- * @return The value of this facet entry
- */
+ /// <summary>
+ /// Gets the value of this facet entry
+ /// </summary>
public BytesRef Value
{
get
@@ -286,9 +299,9 @@ namespace Lucene.Net.Search.Grouping
}
}
- /**
- * @return The count (number of groups) of this facet entry.
- */
+ /// <summary>
+ /// Gets the count (number of groups) of this facet entry.
+ /// </summary>
public int Count
{
get
@@ -298,10 +311,14 @@ namespace Lucene.Net.Search.Grouping
}
}
- /**
- * Contains the local grouped segment counts for a particular segment.
- * Each <code>SegmentResult</code> must be added together.
- */
+ /// <summary>
+ /// Contains the local grouped segment counts for a particular segment.
+ /// Each <see cref="AbstractSegmentResult"/> must be added together.
+ /// </summary>
+ /// <remarks>
+ /// LUCENENET NOTE: Renamed from SegmentResult to AbstractSegmentResult
+ /// to avoid naming conflicts with subclasses.
+ /// </remarks>
protected internal abstract class AbstractSegmentResult
{
protected internal readonly int[] counts;
@@ -320,11 +337,10 @@ namespace Lucene.Net.Search.Grouping
this.maxTermPos = maxTermPos;
}
- /**
- * Go to next term in this <code>SegmentResult</code> in order to retrieve the grouped facet counts.
- *
- * @throws IOException If I/O related errors occur
- */
+ /// <summary>
+ /// Go to next term in this <see cref="AbstractSegmentResult"/> in order to retrieve the grouped facet counts.
+ /// </summary>
+ /// <exception cref="IOException">If I/O related errors occur</exception>
protected internal abstract void NextTerm();
}
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/AbstractSecondPassGroupingCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/AbstractSecondPassGroupingCollector.cs b/src/Lucene.Net.Grouping/AbstractSecondPassGroupingCollector.cs
index de3feb6..e8aedc8 100644
--- a/src/Lucene.Net.Grouping/AbstractSecondPassGroupingCollector.cs
+++ b/src/Lucene.Net.Grouping/AbstractSecondPassGroupingCollector.cs
@@ -6,6 +6,23 @@ using System.Linq;
namespace Lucene.Net.Search.Grouping
{
+ /*
+ * 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.
+ */
+
/// <summary>
/// SecondPassGroupingCollector is the second of two passes
/// necessary to collect grouped docs. This pass gathers the
@@ -13,7 +30,7 @@ namespace Lucene.Net.Search.Grouping
/// first pass. Concrete subclasses define what a group is and how it
/// is internally collected.
/// <para>
- /// See {@link org.apache.lucene.search.grouping} for more
+ /// See <a href="https://github.com/apache/lucene-solr/blob/releases/lucene-solr/4.8.0/lucene/grouping/src/java/org/apache/lucene/search/grouping/package.html">org.apache.lucene.search.grouping</a> for more
/// details including a full code example.
/// </para>
/// @lucene.experimental
@@ -87,13 +104,12 @@ namespace Lucene.Net.Search.Grouping
}
}
- /**
- * Returns the group the specified doc belongs to or <code>null</code> if no group could be retrieved.
- *
- * @param doc The specified doc
- * @return the group the specified doc belongs to or <code>null</code> if no group could be retrieved
- * @throws IOException If an I/O related error occurred
- */
+ /// <summary>
+ /// Returns the group the specified doc belongs to or <c>null</c> if no group could be retrieved.
+ /// </summary>
+ /// <param name="doc">The specified doc</param>
+ /// <returns>the group the specified doc belongs to or <c>null</c> if no group could be retrieved</returns>
+ /// <exception cref="IOException">If an I/O related error occurred</exception>
protected abstract AbstractSecondPassGroupingCollector.SearchGroupDocs<TGroupValue> RetrieveGroup(int doc);
public override AtomicReaderContext NextReader
@@ -142,6 +158,11 @@ namespace Lucene.Net.Search.Grouping
}
+ /// <summary>
+ /// LUCENENET specific class used to simulate the syntax used
+ /// to access nested classes of <see cref="AbstractAllGroupHeadsCollector{GH}"/>
+ /// without referencing the generic closing type.
+ /// </summary>
public class AbstractSecondPassGroupingCollector
{
/// <summary>
@@ -166,6 +187,7 @@ namespace Lucene.Net.Search.Grouping
/// <summary>
/// LUCENENET specific interface used to apply covariance to TGroupValue
+ /// to simulate Java's wildcard generics.
/// </summary>
/// <typeparam name="TGroupValue"></typeparam>
public interface IAbstractSecondPassGroupingCollector<out TGroupValue>
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/BlockGroupingCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/BlockGroupingCollector.cs b/src/Lucene.Net.Grouping/BlockGroupingCollector.cs
index c7fd34c..0f3549f 100644
--- a/src/Lucene.Net.Grouping/BlockGroupingCollector.cs
+++ b/src/Lucene.Net.Grouping/BlockGroupingCollector.cs
@@ -6,6 +6,23 @@ using System.Diagnostics;
namespace Lucene.Net.Search.Grouping
{
+ /*
+ * 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.
+ */
+
// TODO: this sentence is too long for the class summary.
/// <summary>
/// BlockGroupingCollector performs grouping with a
@@ -32,7 +49,7 @@ namespace Lucene.Net.Search.Grouping
/// you to ensure this was the case.
/// </para>
/// <para>
- /// See {@link org.apache.lucene.search.grouping} for more
+ /// See <a href="https://github.com/apache/lucene-solr/blob/releases/lucene-solr/4.8.0/lucene/grouping/src/java/org/apache/lucene/search/grouping/package.html">org.apache.lucene.search.grouping</a> for more
/// details including a full code example.
/// </para>
/// @lucene.experimental
@@ -247,24 +264,28 @@ namespace Lucene.Net.Search.Grouping
subDocUpto = 0;
}
- /**
- * Create the single pass collector.
- *
- * @param groupSort The {@link Sort} used to sort the
- * groups. The top sorted document within each group
- * according to groupSort, determines how that group
- * sorts against other groups. This must be non-null,
- * ie, if you want to groupSort by relevance use
- * Sort.RELEVANCE.
- * @param topNGroups How many top groups to keep.
- * @param needsScores true if the collected documents
- * require scores, either because relevance is included
- * in the withinGroupSort or because you plan to pass true
- * for either getSscores or getMaxScores to {@link
- * #getTopGroups}
- * @param lastDocPerGroup a {@link Filter} that marks the
- * last document in each group.
- */
+ /// <summary>
+ /// Create the single pass collector.
+ /// </summary>
+ /// <param name="groupSort">
+ /// The <see cref="Sort"/> used to sort the
+ /// groups. The top sorted document within each group
+ /// according to groupSort, determines how that group
+ /// sorts against other groups. This must be non-null,
+ /// ie, if you want to groupSort by relevance use
+ /// <see cref="Sort.RELEVANCE"/>.
+ /// </param>
+ /// <param name="topNGroups">How many top groups to keep.</param>
+ /// <param name="needsScores">
+ /// true if the collected documents
+ /// require scores, either because relevance is included
+ /// in the withinGroupSort or because you plan to pass true
+ /// for either GetScores or GetMaxScores to <see cref="GetTopGroups(Sort, int, int, int, bool)"/>
+ /// </param>
+ /// <param name="lastDocPerGroup">
+ /// a <see cref="Filter"/> that marks the
+ /// last document in each group.
+ /// </param>
public BlockGroupingCollector(Sort groupSort, int topNGroups, bool needsScores, Filter lastDocPerGroup)
{
@@ -305,32 +326,68 @@ namespace Lucene.Net.Search.Grouping
// typically they will be presented as a "single" result
// in the UI?
- /** Returns the grouped results. Returns null if the
- * number of groups collected is <= groupOffset.
- *
- * <p><b>NOTE</b>: This collector is unable to compute
- * the groupValue per group so it will always be null.
- * This is normally not a problem, as you can obtain the
- * value just like you obtain other values for each
- * matching document (eg, via stored fields, via
- * FieldCache, etc.)
- *
- * @param withinGroupSort The {@link Sort} used to sort
- * documents within each group. Passing null is
- * allowed, to sort by relevance.
- * @param groupOffset Which group to start from
- * @param withinGroupOffset Which document to start from
- * within each group
- * @param maxDocsPerGroup How many top documents to keep
- * within each group.
- * @param fillSortFields If true then the Comparable
- * values for the sort fields will be set
- */
+ /// <summary>
+ /// Returns the grouped results. Returns null if the
+ /// number of groups collected is <= groupOffset.
+ ///
+ /// <para>
+ /// <b>NOTE</b>: This collector is unable to compute
+ /// the groupValue per group so it will always be null.
+ /// This is normally not a problem, as you can obtain the
+ /// value just like you obtain other values for each
+ /// matching document (eg, via stored fields, via
+ /// FieldCache, etc.)
+ /// </para>
+ /// </summary>
+ /// <param name="withinGroupSort">
+ /// The <see cref="Sort"/> used to sort
+ /// documents within each group. Passing null is
+ /// allowed, to sort by relevance.
+ /// </param>
+ /// <param name="groupOffset">Which group to start from</param>
+ /// <param name="withinGroupOffset">
+ /// Which document to start from within each group
+ /// </param>
+ /// <param name="maxDocsPerGroup">
+ /// How many top documents to keep within each group.
+ /// </param>
+ /// <param name="fillSortFields">
+ /// If true then the Comparable values for the sort fields will be set
+ /// </param>
public ITopGroups<object> GetTopGroups(Sort withinGroupSort, int groupOffset, int withinGroupOffset, int maxDocsPerGroup, bool fillSortFields)
{
return GetTopGroups<object>(withinGroupSort, groupOffset, withinGroupOffset, maxDocsPerGroup, fillSortFields);
}
+ /// <summary>
+ /// Returns the grouped results. Returns null if the
+ /// number of groups collected is <= groupOffset.
+ ///
+ /// <para>
+ /// <b>NOTE</b>: This collector is unable to compute
+ /// the groupValue per group so it will always be null.
+ /// This is normally not a problem, as you can obtain the
+ /// value just like you obtain other values for each
+ /// matching document (eg, via stored fields, via
+ /// FieldCache, etc.)
+ /// </para>
+ /// </summary>
+ /// <typeparam name="TGroupValue">The expected return type for group value</typeparam>
+ /// <<param name="withinGroupSort">
+ /// The <see cref="Sort"/> used to sort
+ /// documents within each group. Passing null is
+ /// allowed, to sort by relevance.
+ /// </param>
+ /// <param name="groupOffset">Which group to start from</param>
+ /// <param name="withinGroupOffset">
+ /// Which document to start from within each group
+ /// </param>
+ /// <param name="maxDocsPerGroup">
+ /// How many top documents to keep within each group.
+ /// </param>
+ /// <param name="fillSortFields">
+ /// If true then the Comparable values for the sort fields will be set
+ /// </param>
public ITopGroups<TGroupValue> GetTopGroups<TGroupValue>(Sort withinGroupSort, int groupOffset, int withinGroupOffset, int maxDocsPerGroup, bool fillSortFields)
{
@@ -595,7 +652,6 @@ namespace Lucene.Net.Search.Grouping
{
comparators[i] = comparators[i].SetNextReader(value);
}
-
}
}
}
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/CollectedSearchGroup.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/CollectedSearchGroup.cs b/src/Lucene.Net.Grouping/CollectedSearchGroup.cs
index 51a905f..39e0d92 100644
--- a/src/Lucene.Net.Grouping/CollectedSearchGroup.cs
+++ b/src/Lucene.Net.Grouping/CollectedSearchGroup.cs
@@ -1,8 +1,25 @@
\ufeffnamespace Lucene.Net.Search.Grouping
{
+ /*
+ * 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.
+ */
+
/// <summary>
- /// Expert: representation of a group in {@link AbstractFirstPassGroupingCollector},
- /// tracking the top doc and {@link FieldComparator} slot.
+ /// Expert: representation of a group in <see cref="AbstractFirstPassGroupingCollector{TGroupValue}"/>,
+ /// tracking the top doc and <see cref="FieldComparator"/> slot.
/// @lucene.internal
/// </summary>
/// <typeparam name="TGroupValue"></typeparam>
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/Function/FunctionAllGroupHeadsCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/Function/FunctionAllGroupHeadsCollector.cs b/src/Lucene.Net.Grouping/Function/FunctionAllGroupHeadsCollector.cs
index 70aa484..70a2033 100644
--- a/src/Lucene.Net.Grouping/Function/FunctionAllGroupHeadsCollector.cs
+++ b/src/Lucene.Net.Grouping/Function/FunctionAllGroupHeadsCollector.cs
@@ -6,6 +6,23 @@ using System.Collections.Generic;
namespace Lucene.Net.Search.Grouping.Function
{
+ /*
+ * 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.
+ */
+
/// <summary>
/// An implementation of <see cref="AbstractAllGroupHeadsCollector"/> for retrieving the most relevant groups when grouping
/// by <see cref="ValueSource"/>.
@@ -24,13 +41,12 @@ namespace Lucene.Net.Search.Grouping.Function
private AtomicReaderContext readerContext;
private Scorer scorer;
- /**
- * Constructs a {@link FunctionAllGroupHeadsCollector} instance.
- *
- * @param groupBy The {@link ValueSource} to group by
- * @param vsContext The ValueSource context
- * @param sortWithinGroup The sort within a group
- */
+ /// <summary>
+ /// Constructs a <see cref="FunctionAllGroupHeadsCollector"/> instance.
+ /// </summary>
+ /// <param name="groupBy">The <see cref="ValueSource"/> to group by</param>
+ /// <param name="vsContext">The <see cref="ValueSource"/> context</param>
+ /// <param name="sortWithinGroup">The sort within a group</param>
public FunctionAllGroupHeadsCollector(ValueSource groupBy, IDictionary /* Map<?, ?> */ vsContext, Sort sortWithinGroup)
: base(sortWithinGroup.GetSort().Length)
{
@@ -103,9 +119,11 @@ namespace Lucene.Net.Search.Grouping.Function
}
}
- /** Holds current head document for a single group.
- *
- * @lucene.experimental */
+ /// <summary>
+ /// Holds current head document for a single group.
+ ///
+ /// @lucene.experimental
+ /// </summary>
public class GroupHead : AbstractAllGroupHeadsCollector_GroupHead
{
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/Function/FunctionAllGroupsCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/Function/FunctionAllGroupsCollector.cs b/src/Lucene.Net.Grouping/Function/FunctionAllGroupsCollector.cs
index c5c7623..be73a9a 100644
--- a/src/Lucene.Net.Grouping/Function/FunctionAllGroupsCollector.cs
+++ b/src/Lucene.Net.Grouping/Function/FunctionAllGroupsCollector.cs
@@ -6,6 +6,23 @@ using System.Collections.Generic;
namespace Lucene.Net.Search.Grouping.Function
{
+ /*
+ * 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.
+ */
+
/// <summary>
/// A collector that collects all groups that match the
/// query. Only the group value is collected, and the order
@@ -27,12 +44,11 @@ namespace Lucene.Net.Search.Grouping.Function
private FunctionValues.AbstractValueFiller filler;
private MutableValue mval;
- /**
- * Constructs a {@link FunctionAllGroupsCollector} instance.
- *
- * @param groupBy The {@link ValueSource} to group by
- * @param vsContext The ValueSource context
- */
+ /// <summary>
+ /// Constructs a <see cref="FunctionAllGroupsCollector"/> instance.
+ /// </summary>
+ /// <param name="groupBy">The <see cref="ValueSource"/> to group by</param>
+ /// <param name="vsContext">The <see cref="ValueSource"/> context</param>
public FunctionAllGroupsCollector(ValueSource groupBy, IDictionary /* Map<?, ?> */ vsContext)
{
this.vsContext = vsContext;
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/Function/FunctionDistinctValuesCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/Function/FunctionDistinctValuesCollector.cs b/src/Lucene.Net.Grouping/Function/FunctionDistinctValuesCollector.cs
index 22f2395..409cc67 100644
--- a/src/Lucene.Net.Grouping/Function/FunctionDistinctValuesCollector.cs
+++ b/src/Lucene.Net.Grouping/Function/FunctionDistinctValuesCollector.cs
@@ -7,6 +7,23 @@ using System.Collections.Generic;
namespace Lucene.Net.Search.Grouping.Function
{
+ /*
+ * 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.
+ */
+
/// <summary>
/// Function based implementation of <see cref="AbstractDistinctValuesCollector"/>.
///
@@ -65,11 +82,11 @@ namespace Lucene.Net.Search.Grouping.Function
}
}
-
-
- /** Holds distinct values for a single group.
- *
- * @lucene.experimental */
+ /// <summary>
+ /// Holds distinct values for a single group.
+ ///
+ /// @lucene.experimental
+ /// </summary>
public class GroupCount : AbstractDistinctValuesCollector.GroupCount<MutableValue>
{
internal GroupCount(MutableValue groupValue)
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/Function/FunctionFirstPassGroupingCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/Function/FunctionFirstPassGroupingCollector.cs b/src/Lucene.Net.Grouping/Function/FunctionFirstPassGroupingCollector.cs
index 18f9fb6..fcf102d 100644
--- a/src/Lucene.Net.Grouping/Function/FunctionFirstPassGroupingCollector.cs
+++ b/src/Lucene.Net.Grouping/Function/FunctionFirstPassGroupingCollector.cs
@@ -5,6 +5,23 @@ using System.Collections;
namespace Lucene.Net.Search.Grouping.Function
{
+ /*
+ * 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.
+ */
+
/// <summary>
/// Concrete implementation of <see cref="AbstractFirstPassGroupingCollector{TGroupValue}"/> that groups based on
/// <see cref="ValueSource"/> instances.
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/Function/FunctionSecondPassGroupingCollector.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/Function/FunctionSecondPassGroupingCollector.cs b/src/Lucene.Net.Grouping/Function/FunctionSecondPassGroupingCollector.cs
index ec1fccb..027ea55 100644
--- a/src/Lucene.Net.Grouping/Function/FunctionSecondPassGroupingCollector.cs
+++ b/src/Lucene.Net.Grouping/Function/FunctionSecondPassGroupingCollector.cs
@@ -6,6 +6,23 @@ using System.Collections.Generic;
namespace Lucene.Net.Search.Grouping.Function
{
+ /*
+ * 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.
+ */
+
/// <summary>
/// Concrete implementation of <see cref="AbstractSecondPassGroupingCollector{TGroupValue}"/> that groups based on
/// <see cref="ValueSource"/> instances.
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/GroupDocs.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/GroupDocs.cs b/src/Lucene.Net.Grouping/GroupDocs.cs
index cc1a7c6..c997e30 100644
--- a/src/Lucene.Net.Grouping/GroupDocs.cs
+++ b/src/Lucene.Net.Grouping/GroupDocs.cs
@@ -71,6 +71,7 @@ namespace Lucene.Net.Search.Grouping
/// <summary>
/// LUCENENET specific interface used to apply covariance to TGroupValue
+ /// to simulate Java's wildcard generics.
/// </summary>
/// <typeparam name="TGroupValue"></typeparam>
public interface IGroupDocs<out TGroupValue>
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/GroupingSearch.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/GroupingSearch.cs b/src/Lucene.Net.Grouping/GroupingSearch.cs
index c9353d8..5bb98c5 100644
--- a/src/Lucene.Net.Grouping/GroupingSearch.cs
+++ b/src/Lucene.Net.Grouping/GroupingSearch.cs
@@ -9,6 +9,23 @@ using System.Collections.Generic;
namespace Lucene.Net.Search.Grouping
{
+ /*
+ * 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.
+ */
+
/// <summary>
/// Convenience class to perform grouping in a non distributed environment.
/// @lucene.experimental
@@ -39,36 +56,33 @@ namespace Lucene.Net.Search.Grouping
private ICollection /* Collection<?> */ matchingGroups;
private Bits matchingGroupHeads;
- /**
- * Constructs a <code>GroupingSearch</code> instance that groups documents by index terms using the {@link FieldCache}.
- * The group field can only have one token per document. This means that the field must not be analysed.
- *
- * @param groupField The name of the field to group by.
- */
+ /// <summary>
+ /// Constructs a <see cref="GroupingSearch"/> instance that groups documents by index terms using the <see cref="FieldCache"/>.
+ /// The group field can only have one token per document. This means that the field must not be analysed.
+ /// </summary>
+ /// <param name="groupField">The name of the field to group by.</param>
public GroupingSearch(string groupField)
: this(groupField, null, null, null)
{
}
- /**
- * Constructs a <code>GroupingSearch</code> instance that groups documents by function using a {@link ValueSource}
- * instance.
- *
- * @param groupFunction The function to group by specified as {@link ValueSource}
- * @param valueSourceContext The context of the specified groupFunction
- */
+ /// <summary>
+ /// Constructs a <see cref="GroupingSearch"/> instance that groups documents by function using a <see cref="ValueSource"/>
+ /// instance.
+ /// </summary>
+ /// <param name="groupFunction">The function to group by specified as <see cref="ValueSource"/></param>
+ /// <param name="valueSourceContext">The context of the specified groupFunction</param>
public GroupingSearch(ValueSource groupFunction, IDictionary /* Map<?, ?> */ valueSourceContext)
: this(null, groupFunction, valueSourceContext, null)
{
}
- /**
- * Constructor for grouping documents by doc block.
- * This constructor can only be used when documents belonging in a group are indexed in one block.
- *
- * @param groupEndDocs The filter that marks the last document in all doc blocks
- */
+ /// <summary>
+ /// Constructor for grouping documents by doc block.
+ /// This constructor can only be used when documents belonging in a group are indexed in one block.
+ /// </summary>
+ /// <param name="groupEndDocs">The filter that marks the last document in all doc blocks</param>
public GroupingSearch(Filter groupEndDocs)
: this(null, null, null, groupEndDocs)
{
@@ -82,37 +96,46 @@ namespace Lucene.Net.Search.Grouping
this.groupEndDocs = groupEndDocs;
}
- /**
- * Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.
- *
- * @param searcher The {@link org.apache.lucene.search.IndexSearcher} instance to execute the grouped search on.
- * @param query The query to execute with the grouping
- * @param groupOffset The group offset
- * @param groupLimit The number of groups to return from the specified group offset
- * @return the grouped result as a {@link TopGroups} instance
- * @throws IOException If any I/O related errors occur
- */
+ /// <summary>
+ /// Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.
+ /// </summary>
+ /// <param name="searcher">The <see cref="IndexSearcher"/> instance to execute the grouped search on.</param>
+ /// <param name="query">The query to execute with the grouping</param>
+ /// <param name="groupOffset">The group offset</param>
+ /// <param name="groupLimit">The number of groups to return from the specified group offset</param>
+ /// <returns>the grouped result as a <see cref="ITopGroups{Object}"/> instance</returns>
+ /// <exception cref="IOException">If any I/O related errors occur</exception>
public ITopGroups<object> Search(IndexSearcher searcher, Query query, int groupOffset, int groupLimit)
{
return Search<object>(searcher, null, query, groupOffset, groupLimit);
}
+
+ /// <summary>
+ /// Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.
+ /// </summary>
+ /// <typeparam name="TGroupValue">The expected return type of the search.</typeparam>
+ /// <param name="searcher">The <see cref="IndexSearcher"/> instance to execute the grouped search on.</param>
+ /// <param name="query">The query to execute with the grouping</param>
+ /// <param name="groupOffset">The group offset</param>
+ /// <param name="groupLimit">The number of groups to return from the specified group offset</param>
+ /// <returns>the grouped result as a <see cref="ITopGroups{Object}"/> instance</returns>
+ /// <exception cref="IOException">If any I/O related errors occur</exception>
public ITopGroups<TGroupValue> Search<TGroupValue>(IndexSearcher searcher, Query query, int groupOffset, int groupLimit)
{
return Search<TGroupValue>(searcher, null, query, groupOffset, groupLimit);
}
- /**
- * Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.
- *
- * @param searcher The {@link org.apache.lucene.search.IndexSearcher} instance to execute the grouped search on.
- * @param filter The filter to execute with the grouping
- * @param query The query to execute with the grouping
- * @param groupOffset The group offset
- * @param groupLimit The number of groups to return from the specified group offset
- * @return the grouped result as a {@link TopGroups} instance
- * @throws IOException If any I/O related errors occur
- */
+ /// <summary>
+ /// Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.
+ /// </summary>
+ /// <param name="searcher">The <see cref="IndexSearcher"/> instance to execute the grouped search on.</param>
+ /// <param name="filter">The filter to execute with the grouping</param>
+ /// <param name="query">The query to execute with the grouping</param>
+ /// <param name="groupOffset">The group offset</param>
+ /// <param name="groupLimit">The number of groups to return from the specified group offset</param>
+ /// <returns>the grouped result as a <see cref="ITopGroups{Object}"/> instance</returns>
+ /// <exception cref="IOException">If any I/O related errors occur</exception>
public ITopGroups<object> Search(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit)
{
if (groupFunction != null)
@@ -133,6 +156,17 @@ namespace Lucene.Net.Search.Grouping
}
}
+ /// <summary>
+ /// Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.
+ /// </summary>
+ /// <typeparam name="TGroupValue">The expected return type of the search.</typeparam>
+ /// <param name="searcher">The <see cref="IndexSearcher"/> instance to execute the grouped search on.</param>
+ /// <param name="filter">The filter to execute with the grouping</param>
+ /// <param name="query">The query to execute with the grouping</param>
+ /// <param name="groupOffset">The group offset</param>
+ /// <param name="groupLimit">The number of groups to return from the specified group offset</param>
+ /// <returns>the grouped result as a <see cref="ITopGroups{Object}"/> instance</returns>
+ /// <exception cref="IOException">If any I/O related errors occur</exception>
public ITopGroups<TGroupValue> Search<TGroupValue>(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit)
{
if (groupField != null || groupFunction != null)
@@ -149,19 +183,6 @@ namespace Lucene.Net.Search.Grouping
}
}
- //protected ITopGroups<object> GroupByFieldOrFunction(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit)
- //{
- // // LUCENENET TODO: Perhaps there is a better way to infer type without resorting to hard-coding them here, but
- // // the original GroupByFieldOrFunction is already aware of the underlying type based on the FirstPassGroupingCollector
- // // and SecondPassGroupingCollector.
- // if (groupFunction != null)
- // {
- // return GroupByFieldOrFunction<MutableValue>(searcher, filter, query, groupOffset, groupLimit);
- // }
-
- // return GroupByFieldOrFunction<BytesRef>(searcher, filter, query, groupOffset, groupLimit);
- //}
-
protected ITopGroups<TGroupValue> GroupByFieldOrFunction<TGroupValue>(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit)
{
int topN = groupOffset + groupLimit;
@@ -323,15 +344,14 @@ namespace Lucene.Net.Search.Grouping
return c.GetTopGroups<TGroupValue>(sortWithinGroup, groupOffset, groupDocsOffset, topNInsideGroup, fillSortFields);
}
- /**
- * Enables caching for the second pass search. The cache will not grow over a specified limit in MB.
- * The cache is filled during the first pass searched and then replayed during the second pass searched.
- * If the cache grows beyond the specified limit, then the cache is purged and not used in the second pass search.
- *
- * @param maxCacheRAMMB The maximum amount in MB the cache is allowed to hold
- * @param cacheScores Whether to cache the scores
- * @return <code>this</code>
- */
+ /// <summary>
+ /// Enables caching for the second pass search. The cache will not grow over a specified limit in MB.
+ /// The cache is filled during the first pass searched and then replayed during the second pass searched.
+ /// If the cache grows beyond the specified limit, then the cache is purged and not used in the second pass search.
+ /// </summary>
+ /// <param name="maxCacheRAMMB">The maximum amount in MB the cache is allowed to hold</param>
+ /// <param name="cacheScores">Whether to cache the scores</param>
+ /// <returns><c>this</c></returns>
public GroupingSearch SetCachingInMB(double maxCacheRAMMB, bool cacheScores)
{
this.maxCacheRAMMB = maxCacheRAMMB;
@@ -340,15 +360,14 @@ namespace Lucene.Net.Search.Grouping
return this;
}
- /**
- * Enables caching for the second pass search. The cache will not contain more than the maximum specified documents.
- * The cache is filled during the first pass searched and then replayed during the second pass searched.
- * If the cache grows beyond the specified limit, then the cache is purged and not used in the second pass search.
- *
- * @param maxDocsToCache The maximum number of documents the cache is allowed to hold
- * @param cacheScores Whether to cache the scores
- * @return <code>this</code>
- */
+ /// <summary>
+ /// Enables caching for the second pass search. The cache will not contain more than the maximum specified documents.
+ /// The cache is filled during the first pass searched and then replayed during the second pass searched.
+ /// If the cache grows beyond the specified limit, then the cache is purged and not used in the second pass search.
+ /// </summary>
+ /// <param name="maxDocsToCache">The maximum number of documents the cache is allowed to hold</param>
+ /// <param name="cacheScores">Whether to cache the scores</param>
+ /// <returns><c>this</c></returns>
public GroupingSearch SetCaching(int maxDocsToCache, bool cacheScores)
{
this.maxDocsToCache = maxDocsToCache;
@@ -357,11 +376,10 @@ namespace Lucene.Net.Search.Grouping
return this;
}
- /**
- * Disables any enabled cache.
- *
- * @return <code>this</code>
- */
+ /// <summary>
+ /// Disables any enabled cache.
+ /// </summary>
+ /// <returns><c>this</c></returns>
public GroupingSearch DisableCaching()
{
this.maxCacheRAMMB = null;
@@ -369,163 +387,162 @@ namespace Lucene.Net.Search.Grouping
return this;
}
- /**
- * Specifies how groups are sorted.
- * Defaults to {@link Sort#RELEVANCE}.
- *
- * @param groupSort The sort for the groups.
- * @return <code>this</code>
- */
+ /// <summary>
+ /// Specifies how groups are sorted.
+ /// Defaults to <see cref="Sort.RELEVANCE"/>.
+ /// </summary>
+ /// <param name="groupSort">The sort for the groups.</param>
+ /// <returns><c>this</c></returns>
public GroupingSearch SetGroupSort(Sort groupSort)
{
this.groupSort = groupSort;
return this;
}
- /**
- * Specified how documents inside a group are sorted.
- * Defaults to {@link Sort#RELEVANCE}.
- *
- * @param sortWithinGroup The sort for documents inside a group
- * @return <code>this</code>
- */
+ /// <summary>
+ /// Specified how documents inside a group are sorted.
+ /// Defaults to <see cref="Sort.RELEVANCE"/>.
+ /// </summary>
+ /// <param name="sortWithinGroup">The sort for documents inside a group</param>
+ /// <returns><c>this</c></returns>
public GroupingSearch SetSortWithinGroup(Sort sortWithinGroup)
{
this.sortWithinGroup = sortWithinGroup;
return this;
}
- /**
- * Specifies the offset for documents inside a group.
- *
- * @param groupDocsOffset The offset for documents inside a
- * @return <code>this</code>
- */
+ /// <summary>
+ /// Specifies the offset for documents inside a group.
+ /// </summary>
+ /// <param name="groupDocsOffset">The offset for documents inside a</param>
+ /// <returns><c>this</c></returns>
public GroupingSearch SetGroupDocsOffset(int groupDocsOffset)
{
this.groupDocsOffset = groupDocsOffset;
return this;
}
- /**
- * Specifies the number of documents to return inside a group from the specified groupDocsOffset.
- *
- * @param groupDocsLimit The number of documents to return inside a group
- * @return <code>this</code>
- */
+ /// <summary>
+ /// Specifies the number of documents to return inside a group from the specified groupDocsOffset.
+ /// </summary>
+ /// <param name="groupDocsLimit">The number of documents to return inside a group</param>
+ /// <returns><c>this</c></returns>
public GroupingSearch SetGroupDocsLimit(int groupDocsLimit)
{
this.groupDocsLimit = groupDocsLimit;
return this;
}
- /**
- * Whether to also fill the sort fields per returned group and groups docs.
- *
- * @param fillSortFields Whether to also fill the sort fields per returned group and groups docs
- * @return <code>this</code>
- */
+ /// <summary>
+ /// Whether to also fill the sort fields per returned group and groups docs.
+ /// </summary>
+ /// <param name="fillSortFields">Whether to also fill the sort fields per returned group and groups docs</param>
+ /// <returns><c>this</c></returns>
public GroupingSearch SetFillSortFields(bool fillSortFields)
{
this.fillSortFields = fillSortFields;
return this;
}
- /**
- * Whether to include the scores per doc inside a group.
- *
- * @param includeScores Whether to include the scores per doc inside a group
- * @return <code>this</code>
- */
+ /// <summary>
+ /// Whether to include the scores per doc inside a group.
+ /// </summary>
+ /// <param name="includeScores">Whether to include the scores per doc inside a group</param>
+ /// <returns><c>this</c></returns>
public GroupingSearch SetIncludeScores(bool includeScores)
{
this.includeScores = includeScores;
return this;
}
- /**
- * Whether to include the score of the most relevant document per group.
- *
- * @param includeMaxScore Whether to include the score of the most relevant document per group
- * @return <code>this</code>
- */
+ /// <summary>
+ /// Whether to include the score of the most relevant document per group.
+ /// </summary>
+ /// <param name="includeMaxScore">Whether to include the score of the most relevant document per group</param>
+ /// <returns><c>this</c></returns>
public GroupingSearch SetIncludeMaxScore(bool includeMaxScore)
{
this.includeMaxScore = includeMaxScore;
return this;
}
- /**
- * Whether to also compute all groups matching the query.
- * This can be used to determine the number of groups, which can be used for accurate pagination.
- * <p/>
- * When grouping by doc block the number of groups are automatically included in the {@link TopGroups} and this
- * option doesn't have any influence.
- *
- * @param allGroups to also compute all groups matching the query
- * @return <code>this</code>
- */
+ /// <summary>
+ /// Whether to also compute all groups matching the query.
+ /// This can be used to determine the number of groups, which can be used for accurate pagination.
+ /// <para>
+ /// When grouping by doc block the number of groups are automatically included in the <see cref="TopGroups"/> and this
+ /// option doesn't have any influence.
+ /// </para>
+ /// </summary>
+ /// <param name="allGroups">to also compute all groups matching the query</param>
+ /// <returns><c>this</c></returns>
public GroupingSearch SetAllGroups(bool allGroups)
{
this.allGroups = allGroups;
return this;
}
- /**
- * If {@link #setAllGroups(boolean)} was set to <code>true</code> then all matching groups are returned, otherwise
- * an empty collection is returned.
- *
- * @param <T> The group value type. This can be a {@link BytesRef} or a {@link MutableValue} instance. If grouping
- * by doc block this the group value is always <code>null</code>.
- * @return all matching groups are returned, or an empty collection
- */
+ /// <summary>
+ /// If <see cref="SetAllGroups(bool)"/> was set to <c>true</c> then all matching groups are returned, otherwise
+ /// an empty collection is returned.
+ /// </summary>
+ /// <typeparam name="T">The group value type. This can be a <see cref="BytesRef"/> or a <see cref="MutableValue"/> instance.
+ /// If grouping by doc block this the group value is always <c>null</c>.</typeparam>
+ /// <returns>all matching groups are returned, or an empty collection</returns>
public ICollection<T> GetAllMatchingGroups<T>()
{
return (ICollection<T>)matchingGroups;
}
- // LUCENENET specific used to get the groups if the type is unknown (since the above
- // method will crash if the wrong type is used)
+ /// <summary>
+ /// If <see cref="SetAllGroups(bool)"/> was set to <c>true</c> then all matching groups are returned, otherwise
+ /// an empty collection is returned.
+ /// </summary>
+ /// <returns>all matching groups are returned, or an empty collection</returns>
+ /// <remarks>
+ /// LUCENENET specific used to get the groups if the type is unknown or if the code expects
+ /// any type, since <see cref="GetAllMatchingGroups{T}"/>
+ /// will throw an exception if the return type is incorrect.
+ /// </remarks>
public ICollection GetAllMatchingGroups()
{
return matchingGroups;
}
- /**
- * Whether to compute all group heads (most relevant document per group) matching the query.
- * <p/>
- * This feature isn't enabled when grouping by doc block.
- *
- * @param allGroupHeads Whether to compute all group heads (most relevant document per group) matching the query
- * @return <code>this</code>
- */
+ /// <summary>
+ /// Whether to compute all group heads (most relevant document per group) matching the query.
+ /// <para>
+ /// This feature isn't enabled when grouping by doc block.
+ /// </para>
+ /// </summary>
+ /// <param name="allGroupHeads">Whether to compute all group heads (most relevant document per group) matching the query</param>
+ /// <returns><c>this</c></returns>
public GroupingSearch SetAllGroupHeads(bool allGroupHeads)
{
this.allGroupHeads = allGroupHeads;
return this;
}
- /**
- * Returns the matching group heads if {@link #setAllGroupHeads(boolean)} was set to true or an empty bit set.
- *
- * @return The matching group heads if {@link #setAllGroupHeads(boolean)} was set to true or an empty bit set
- */
+ /// <summary>
+ /// Returns the matching group heads if <see cref="SetAllGroupHeads(bool)"/> was set to true or an empty bit set.
+ /// </summary>
+ /// <returns>The matching group heads if <see cref="SetAllGroupHeads(bool)"/> was set to true or an empty bit set</returns>
public Bits GetAllGroupHeads()
{
return matchingGroupHeads;
}
- /**
- * 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
- * more initial RAM.
- * <p/>
- * The {@link #setAllGroups} and {@link #setAllGroupHeads} features use this option.
- * Defaults to 128.
- *
- * @param initialSize The initial size of some internal used data structures
- * @return <code>this</code>
- */
+ /// <summary>
+ /// 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
+ /// more initial RAM.
+ /// <para>
+ /// The <see cref="SetAllGroups(bool)"/> and <see cref="SetAllGroupHeads(bool)"/> features use this option.
+ /// Defaults to 128.
+ /// </para>
+ /// </summary>
+ /// <param name="initialSize">The initial size of some internal used data structures</param>
+ /// <returns><c>this</c></returns>
public GroupingSearch SetInitialSize(int initialSize)
{
this.initialSize = initialSize;
http://git-wip-us.apache.org/repos/asf/lucenenet/blob/a0a61e24/src/Lucene.Net.Grouping/SearchGroup.cs
----------------------------------------------------------------------
diff --git a/src/Lucene.Net.Grouping/SearchGroup.cs b/src/Lucene.Net.Grouping/SearchGroup.cs
index 23140bc..bbf2082 100644
--- a/src/Lucene.Net.Grouping/SearchGroup.cs
+++ b/src/Lucene.Net.Grouping/SearchGroup.cs
@@ -6,21 +6,43 @@ using System.Linq;
namespace Lucene.Net.Search.Grouping
{
+ /*
+ * 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.
+ */
+
/// <summary>
/// Represents a group that is found during the first pass search.
+ ///
/// @lucene.experimental
/// </summary>
/// <typeparam name="TGroupValue"></typeparam>
public class SearchGroup<TGroupValue> : ISearchGroup<TGroupValue>
{
- /** The value that defines this group */
+ /// <summary>
+ /// The value that defines this group
+ /// </summary>
public TGroupValue GroupValue { get; set; }
- /** The sort values used during sorting. These are the
- * groupSort field values of the highest rank document
- * (by the groupSort) within the group. Can be
- * <code>null</code> if <code>fillFields=false</code> had
- * been passed to {@link AbstractFirstPassGroupingCollector#getTopGroups} */
+ /// <summary>
+ /// The sort values used during sorting. These are the
+ /// groupSort field values of the highest rank document
+ /// (by the groupSort) within the group. Can be
+ /// <c>null</c> if <c>fillFields=false</c> had
+ /// been passed to <see cref="AbstractFirstPassGroupingCollector{TGroupValue}.GetTopGroups(int, bool)"/>
+ /// </summary>
public object[] SortValues { get; set; }
public override string ToString()
@@ -96,7 +118,10 @@ namespace Lucene.Net.Search.Grouping
}
}
- // Holds all shards currently on the same group
+ /// <summary>
+ /// Holds all shards currently on the same group
+ /// </summary>
+ /// <typeparam name="T"></typeparam>
private class MergedGroup<T>
{
@@ -373,16 +398,17 @@ namespace Lucene.Net.Search.Grouping
}
}
-
- /** Merges multiple collections of top groups, for example
- * obtained from separate index shards. The provided
- * groupSort must match how the groups were sorted, and
- * the provided SearchGroups must have been computed
- * with fillFields=true passed to {@link
- * AbstractFirstPassGroupingCollector#getTopGroups}.
- *
- * <p>NOTE: this returns null if the topGroups is empty.
- */
+ /// <summary>
+ /// Merges multiple collections of top groups, for example
+ /// obtained from separate index shards. The provided
+ /// groupSort must match how the groups were sorted, and
+ /// the provided SearchGroups must have been computed
+ /// with <c>fillFields=true</c> passed to
+ /// <see cref="AbstractFirstPassGroupingCollector{TGroupValue}.GetTopGroups(int, bool)"/>.
+ /// <para>
+ /// NOTE: this returns null if the topGroups is empty.
+ /// </para>
+ /// </summary>
public static ICollection<SearchGroup<T>> Merge<T>(IList<IEnumerable<ISearchGroup<T>>> topGroups, int offset, int topN, Sort groupSort)
{
if (topGroups.Count == 0)
@@ -399,12 +425,23 @@ namespace Lucene.Net.Search.Grouping
/// <summary>
/// LUCENENET specific interface used to provide covariance
- /// with the TGroupValue type
+ /// with the TGroupValue type to simulate Java's wildcard generics.
/// </summary>
/// <typeparam name="TGroupValue"></typeparam>
public interface ISearchGroup<out TGroupValue>
{
+ /// <summary>
+ /// The value that defines this group
+ /// </summary>
TGroupValue GroupValue { get; }
+
+ /// <summary>
+ /// The sort values used during sorting. These are the
+ /// groupSort field values of the highest rank document
+ /// (by the groupSort) within the group. Can be
+ /// <c>null</c> if <c>fillFields=false</c> had
+ /// been passed to <see cref="AbstractFirstPassGroupingCollector{TGroupValue}.GetTopGroups(int, bool)"/>
+ /// </summary>
object[] SortValues { get; set; }
}
}