nl.inl.blacklab.search.results

Class Results<T>

java.lang.Object

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

Type Parameters:

T - result type, e.g. Hit

All Implemented Interfaces:

Iterable<T>, SearchResult

Direct Known Subclasses:

DocGroups, DocResults, HitGroups, Hits, TermFrequencyList

public abstract class Results<T>
extends Object
implements SearchResult, Iterable<T>

A list of results of some type.

Field Summary

Fields

Modifier and Type	Field and Description
protected int	hitsObjId Unique id of this Hits instance (for debugging)
static int	NO_LIMIT When setting how many hits to retrieve/count/store in group, this means "no limit".
protected List<T>	results The results.
protected ThreadPauser	threadPauser Helper object for pausing threads (making sure queries don't hog the CPU for way too long).

Constructor Summary

Constructors

Constructor and Description
Results(QueryInfo queryInfo)

Method Summary

Modifier and Type	Method and Description
protected static <T> List<T>	doFilter(Results<T> results, ResultProperty<T> property, PropertyValue value)
abstract boolean	doneProcessingAndCounting() Check if we're done retrieving/counting hits.
protected static <T> List<T>	doSample(Results<T> source, SampleParameters sampleParameters)
protected static <P extends ResultProperty<T>,T> List<T>	doSort(Results<T> results, P sortProp)
protected static <T> List<T>	doWindow(Results<T> results, int first, int number)
protected void	ensureAllResultsRead() Ensure that we have read all results.
protected abstract void	ensureResultsRead(int number) Ensure that we have read at least as many results as specified in the parameter.
AnnotatedField	field() Get the field these hits are from.
abstract Results<T>	filter(ResultProperty<T> property, PropertyValue value) Select only the hits where the specified property has the specified value.
T	get(int i) Return the specified hit.
abstract ResultGroups<T>	group(ResultProperty<T> criteria, int maxResultsToStorePerGroup) Group these hits by a criterium (or several criteria).
BlackLabIndex	index() Get the index these hits are from.
boolean	isSample() Is this sampled from another instance?
boolean	isWindow() Is this a hits window?
Iterator<T>	iterator() Return an iterator over these hits.
Stream<T>	parallelStream() Return a parallel stream of these hits.
QueryInfo	queryInfo() Get information about the original query.
protected int	resultsCountedSoFar()
protected int	resultsCountedTotal()
protected List<T>	resultsList() Get the list of results.
int	resultsObjId()
protected boolean	resultsProcessedAtLeast(int lowerBound)
protected int	resultsProcessedSoFar()
protected int	resultsProcessedTotal()
ResultsStats	resultsStats()
protected List<T>	resultsSubList(int fromIndex, int toIndex) Get part of the list of results.
abstract Results<T>	sample(SampleParameters sampleParameters) Take a sample of results.
SampleParameters	sampleParameters() If this is a sample, return the sample parameters.
int	size() This is an alias of resultsProcessedTotal().
abstract <P extends ResultProperty<T>> Results<T>	sort(P sortProp) Return a new Results object with these results sorted by the given property.
Stream<T>	stream() Return a stream of these hits.
ThreadPauser	threadPauser()
String	toString()
abstract Results<T>	window(int first, int windowSize) Get a window into this list of results.
WindowStats	windowStats() If this is a hits window, return the window stats.

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.SearchResult

numberOfResultObjects

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

NO_LIMIT

public static final int NO_LIMIT

When setting how many hits to retrieve/count/store in group, this means "no limit".

See Also:

Constant Field Values

hitsObjId

protected final int hitsObjId

Unique id of this Hits instance (for debugging)

threadPauser

protected ThreadPauser threadPauser

Helper object for pausing threads (making sure queries don't hog the CPU for way too long).

results

protected List<T> results

The results.

Constructor Detail

Results

public Results(QueryInfo queryInfo)

Method Detail

doSample

protected static <T> List<T> doSample(Results<T> source,
                                      SampleParameters sampleParameters)

doWindow

protected static <T> List<T> doWindow(Results<T> results,
                                      int first,
                                      int number)

doFilter

protected static <T> List<T> doFilter(Results<T> results,
                                      ResultProperty<T> property,
                                      PropertyValue value)

doSort

protected static <P extends ResultProperty<T>,T> List<T> doSort(Results<T> results,
                                                                P sortProp)

queryInfo

public QueryInfo queryInfo()

Get information about the original query. This includes the index, field, max. settings, and max. stats (whether the max. settings were reached).

Returns:

query info

field

public AnnotatedField field()

Get the field these hits are from.

Returns:

field

index

public BlackLabIndex index()

Get the index these hits are from.

Returns:

index

resultsObjId

public int resultsObjId()

threadPauser

public ThreadPauser threadPauser()

isWindow

public boolean isWindow()

Is this a hits window?

Returns:

true if it's a window, false if not

windowStats

public WindowStats windowStats()

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

Returns:

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

isSample

public boolean isSample()

Is this sampled from another instance?

Returns:

true if it's a sample, false if not

sampleParameters

public SampleParameters sampleParameters()

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

Returns:

sample parameters, or null if this is not a sample

stream

public Stream<T> stream()

Return a stream of these hits.

Returns:

stream

parallelStream

public Stream<T> parallelStream()

Return a parallel stream of these hits.

Returns:

stream

iterator

public Iterator<T> iterator()

Return an iterator over these hits.

Specified by:

iterator in interface Iterable<T>

Returns:

the iterator

get

public T get(int i)

Return the specified hit.

Parameters:

i - index of the desired hit

Returns:

the hit, or null if it's beyond the last hit

group

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

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

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

filter

public abstract Results<T> filter(ResultProperty<T> property,
                                  PropertyValue value)

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

Parameters:

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

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

Returns:

filtered hits

sort

public abstract <P extends ResultProperty<T>> Results<T> sort(P sortProp)

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.

Parameters:

sortProp - the property to sort on

Returns:

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

sample

public abstract Results<T> sample(SampleParameters sampleParameters)

Take a sample of results.

Parameters:

sampleParameters - sample parameters

Returns:

the sample

window

public abstract Results<T> window(int first,
                                  int windowSize)

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.

Parameters:

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

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

Returns:

the window

toString

public String toString()

Overrides:

toString in class Object

ensureResultsRead

protected abstract void ensureResultsRead(int number)

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

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

ensureAllResultsRead

protected void ensureAllResultsRead()

Ensure that we have read all results.

resultsStats

public ResultsStats resultsStats()

resultsProcessedAtLeast

protected boolean resultsProcessedAtLeast(int lowerBound)

size

public int size()

This is an alias of resultsProcessedTotal().

Returns:

number of hits processed total

resultsProcessedTotal

protected int resultsProcessedTotal()

resultsProcessedSoFar

protected int resultsProcessedSoFar()

resultsCountedSoFar

protected int resultsCountedSoFar()

resultsCountedTotal

protected int resultsCountedTotal()

resultsSubList

protected List<T> resultsSubList(int fromIndex,
                                 int toIndex)

Get part of the list of results. Clients shouldn't use this. Used internally for certain performance-sensitive operations like sorting. The returned list is a view backed by the results list. If toIndex is out of range, no exception is thrown, but a smaller list is returned.

Returns:

the list of hits

resultsList

protected List<T> resultsList()

Get the list of results. Clients shouldn't use this. Used internally for certain performance-sensitive operations like sorting.

Returns:

the list of hits

doneProcessingAndCounting

public abstract boolean doneProcessingAndCounting()

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.

Returns:

true iff all hits have been retrieved/counted.