nl.inl.blacklab.search.results

Class HitGroups

java.lang.Object

nl.inl.blacklab.search.results.Results<HitGroup>

nl.inl.blacklab.search.results.HitGroups

All Implemented Interfaces:

Iterable<HitGroup>, ResultGroups<Hit>, SearchResult

public class HitGroups
extends Results<HitGroup>
implements ResultGroups<Hit>

Groups results on the basis of a list of criteria. This class allows random access to the groups, and each group provides random access to the hits. Note that this means that all hits found must be retrieved, which may be unfeasible for large results sets.

Field Summary

Fields inherited from class nl.inl.blacklab.search.results.Results

hitsObjId, NO_LIMIT, results, threadPauser

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	HitGroups(Hits hits, HitProperty criteria, int maxResultsToStorePerGroup) Construct a ResultsGrouper object, by grouping the supplied hits.
protected	HitGroups(QueryInfo queryInfo, List<HitGroup> groups, HitProperty groupCriteria, SampleParameters sampleParameters, WindowStats windowStats)

Method Summary

Modifier and Type	Method and Description
boolean	doneProcessingAndCounting() Check if we're done retrieving/counting hits.
protected void	ensureResultsRead(int number) Ensure that we have read at least as many results as specified in the parameter.
HitGroups	filter(ResultProperty<HitGroup> property, PropertyValue value) Select only the hits where the specified property has the specified value.
static HitGroups	fromHits(Hits hits, HitProperty criteria, int maxResultsToStorePerGroup) Construct HitGroups from a list of hits.
static HitGroups	fromList(QueryInfo queryInfo, List<HitGroup> results, HitProperty groupCriteria, SampleParameters sampleParameters, WindowStats windowStats) Construct HitGroups from a list of HitGroup instances.
HitGroup	get(PropertyValue identity)
Map<PropertyValue,HitGroup>	getGroupMap()
ResultGroups<HitGroup>	group(ResultProperty<HitGroup> criteria, int maxResultsToStorePerGroup) Group these hits by a criterium (or several criteria).
HitProperty	groupCriteria() What were these results grouped on?
int	largestGroupSize() Return the size of the largest group
int	numberOfResultObjects() How many result objects does this search store? Used for estimating the cache size.
HitGroups	sample(SampleParameters sampleParameters) Take a sample of hits by wrapping an existing Hits object.
SampleParameters	sampleParameters() If this is a sample, return the sample parameters.
int	size() This is an alias of resultsProcessedTotal().
<P extends ResultProperty<HitGroup>> HitGroups	sort(P sortProp) Return a new Results object with these results sorted by the given property.
int	sumOfGroupSizes() Get the total number of hits
String	toString()
HitGroups	window(int first, int number) Get a window into this list of results.
WindowStats	windowStats() If this is a hits window, return the window stats.
HitGroups	withFewerStoredResults(int maximumNumberOfResultsPerGroup) Get an instance of this grouping with fewer stored results per group.

Methods inherited from class nl.inl.blacklab.search.results.Results

doFilter, doSample, doSort, doWindow, ensureAllResultsRead, field, get, index, isSample, isWindow, iterator, parallelStream, queryInfo, resultsCountedSoFar, resultsCountedTotal, resultsList, resultsObjId, resultsProcessedAtLeast, resultsProcessedSoFar, resultsProcessedTotal, resultsStats, resultsSubList, stream, threadPauser

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface nl.inl.blacklab.search.results.ResultGroups

field, get, index, queryInfo

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

HitGroups

protected HitGroups(Hits hits,
                    HitProperty criteria,
                    int maxResultsToStorePerGroup)

Construct a ResultsGrouper object, by grouping the supplied hits.

Parameters:

hits - the hits to group

criteria - the criteria to group on

maxResultsToStorePerGroup - how many results to store per group at most

HitGroups

protected HitGroups(QueryInfo queryInfo,
                    List<HitGroup> groups,
                    HitProperty groupCriteria,
                    SampleParameters sampleParameters,
                    WindowStats windowStats)

Method Detail

fromList

public static HitGroups fromList(QueryInfo queryInfo,
                                 List<HitGroup> results,
                                 HitProperty groupCriteria,
                                 SampleParameters sampleParameters,
                                 WindowStats windowStats)

Construct HitGroups from a list of HitGroup instances.

Parameters:

queryInfo - query info

results - list of groups

groupCriteria - what hits would be grouped by

sampleParameters - how groups were sampled, or null if not applicable

windowStats - what groups window this is, or null if not applicable

Returns:

grouped hits

fromHits

public static HitGroups fromHits(Hits hits,
                                 HitProperty criteria,
                                 int maxResultsToStorePerGroup)

Construct HitGroups from a list of hits.

Parameters:

hits - hits to group

criteria - criteria to group by

maxResultsToStorePerGroup - max results to store

Returns:

grouped hits

groupCriteria

public HitProperty groupCriteria()

Description copied from interface: ResultGroups

What were these results grouped on?

Specified by:

groupCriteria in interface ResultGroups<Hit>

Returns:

group criteria

sort

public <P extends ResultProperty<HitGroup>> HitGroups sort(P sortProp)

Description copied from class: Results

Return a new Results object with these results sorted by the given property. This keeps the existing sort (or lack of one) intact and allows you to cache different sorts of the same resultset. The result objects are reused between the two Results instances, so not too much additional memory is used.

Specified by:

sort in class Results<HitGroup>

Parameters:

sortProp - the property to sort on

Returns:

a new Results object with the same results, sorted in the specified way

ensureResultsRead

protected void ensureResultsRead(int number)

Description copied from class: Results

Ensure that we have read at least as many results as specified in the parameter.

Specified by:

ensureResultsRead in class Results<HitGroup>

Parameters:

number - the minimum number of results that will have been read when this method returns (unless there are fewer hits than this); if negative, reads all hits

sample

public HitGroups sample(SampleParameters sampleParameters)

Take a sample of hits by wrapping an existing Hits object.

Specified by:

sample in class Results<HitGroup>

Parameters:

sampleParameters - sample parameters

Returns:

the sample

sumOfGroupSizes

public int sumOfGroupSizes()

Get the total number of hits

Specified by:

sumOfGroupSizes in interface ResultGroups<Hit>

Returns:

the number of hits

largestGroupSize

public int largestGroupSize()

Return the size of the largest group

Specified by:

largestGroupSize in interface ResultGroups<Hit>

Returns:

size of the largest group

toString

public String toString()

Overrides:

toString in class Results<HitGroup>

get

public HitGroup get(PropertyValue identity)

Specified by:

get in interface ResultGroups<Hit>

size

public int size()

Description copied from class: Results

This is an alias of resultsProcessedTotal().

Specified by:

size in interface ResultGroups<Hit>

Overrides:

size in class Results<HitGroup>

Returns:

number of hits processed total

windowStats

public WindowStats windowStats()

Description copied from class: Results

If this is a hits window, return the window stats.

Overrides:

windowStats in class Results<HitGroup>

Returns:

window stats, or null if this is not a hits window

sampleParameters

public SampleParameters sampleParameters()

Description copied from class: Results

If this is a sample, return the sample parameters. Also includes the explicitly set or randomly chosen seed.

Overrides:

sampleParameters in class Results<HitGroup>

Returns:

sample parameters, or null if this is not a sample

window

public HitGroups window(int first,
                        int number)

Description copied from class: Results

Get a window into this list of results. Use this if you're displaying part of the resultset, like in a paging interface. It makes sure BlackLab only works with the results you want to display and doesn't do any unnecessary processing on the other hits. The resulting instance will has "window stats" to assist with paging, like figuring out if there hits before or after the window.

Specified by:

window in class Results<HitGroup>

Parameters:

first - first result in the window (0-based)

number - desired size of the window (if there's enough results)

Returns:

the window

filter

public HitGroups filter(ResultProperty<HitGroup> property,
                        PropertyValue value)

Description copied from class: Results

Select only the hits where the specified property has the specified value.

Specified by:

filter in class Results<HitGroup>

Parameters:

property - property to select on, e.g. "word left of hit"

value - value to select on, e.g. 'the'

Returns:

filtered hits

group

public ResultGroups<HitGroup> group(ResultProperty<HitGroup> criteria,
                                    int maxResultsToStorePerGroup)

Description copied from class: Results

Group these hits by a criterium (or several criteria).

Specified by:

group in class Results<HitGroup>

Parameters:

criteria - the hit property to group on

maxResultsToStorePerGroup - maximum number of results to store per group, or -1 for all

Returns:

a HitGroups object representing the grouped hits

withFewerStoredResults

public HitGroups withFewerStoredResults(int maximumNumberOfResultsPerGroup)

Description copied from interface: ResultGroups

Get an instance of this grouping with fewer stored results per group. This won't affect the group sizes, just the number of results that are stored per group.

Specified by:

withFewerStoredResults in interface ResultGroups<Hit>

Parameters:

maximumNumberOfResultsPerGroup - maximum number of results to store, or -1 for the same

Returns:

new grouping with fewer stored results

doneProcessingAndCounting

public boolean doneProcessingAndCounting()

Description copied from class: Results

Check if we're done retrieving/counting hits. If you're retrieving hits in a background thread, call this method from another thread to check if all hits have been processed.

Specified by:

doneProcessingAndCounting in class Results<HitGroup>

Returns:

true iff all hits have been retrieved/counted.

getGroupMap

public Map<PropertyValue,HitGroup> getGroupMap()

Specified by:

getGroupMap in interface ResultGroups<Hit>

numberOfResultObjects

public int numberOfResultObjects()

Description copied from interface: SearchResult

How many result objects does this search store? Used for estimating the cache size. Hits make up most of the storage of results objects, and they should take 24 bytes of memory, so we can use this number to make a reasonable approximation of memory usage. Note that this number can be misleading, because Hit objects are shared between results objects. But it's the best we have at the moment.

Specified by:

numberOfResultObjects in interface SearchResult

Returns:

how many hits are stored in this result object