uk.ac.starlink.table.join

Interface Coverage

All Known Implementing Classes:

CuboidCoverage, SkyCoverage

public interface Coverage

Provides a compact representation of a region of space. An instance of this class is in general mutable, and starts off empty but can be extended by feeding it tuples via the extend(java.lang.Object[]) method. Once populated, tests for inclusion of other tuples in the coverage thus represented can be performed by use of the createTestFactory() method.

The details of how the accumulated set of input tuples affects the inclusion of test tuples are determined by the nature of the matching a given coverage implementation is designed to support. When used for crossmatching, the idea is that the coverage represents the region of space in which an external tuple must be included in order to be a potential match.

Instances of this class are not thread-safe, so should not be used from multiple threads concurrently.

Since:

8 Jun 2022

Author:

Mark Taylor

Field Summary

Fields

Modifier and Type	Field and Description
static Coverage	FULL Instance representing full coverage.

Method Summary

Modifier and Type	Method and Description
String	coverageText() Provides a short, human-readable indication of the coverage.
java.util.function.Supplier<java.util.function.Predicate<Object[]>>	createTestFactory() Returns a supplier for an object that can test whether given tuples are considered to fall within the current state of this coverage object.
void	extend(Object[] tuple) Extends this coverage by adding a tuple to it.
void	intersection(Coverage other) Narrows this coverage object to contain only the intersection of its current state and the supplied coverage.
boolean	isEmpty() Returns true if the coverage represents the empty set.
void	union(Coverage other) Modifies the state of this coverage object as if all the tuples fed to the other had been fed to this one as well as its current contents.

Field Detail

FULL

static final Coverage FULL

Instance representing full coverage. The createTestFactory() test always returns true. Note that in accordance with the general contract, the set operations are only supported for use with compatible coverage objects, so attempting to perform an intersection with another coverage instance will fail (with an UnsupportedOperationException).

Method Detail

extend

void extend(Object[] tuple)

Extends this coverage by adding a tuple to it. The tuple contains the coordinates of a row from a table suitable for use with this coverage. The state of this coverage object should not depend on the order in which tuples are submitted.

Parameters:

tuple - coordinate data

createTestFactory

java.util.function.Supplier<java.util.function.Predicate<Object[]>> createTestFactory()

Returns a supplier for an object that can test whether given tuples are considered to fall within the current state of this coverage object. The returned Supplier must be thread-safe, and should not be affected by subsequent changes to the state of this coverage object. The Predicates it dispenses however are not required to be thread-safe, and must not be used concurrently from different threads.

Returns:

supplier of tuple inclusion tests

isEmpty

boolean isEmpty()

Returns true if the coverage represents the empty set.

Returns:

true iff the createTestFactory() test is guaranteed to return false

intersection

void intersection(Coverage other)

Narrows this coverage object to contain only the intersection of its current state and the supplied coverage.

Parameters:

other - different coverage object of a type assumed compatible with this object

union

void union(Coverage other)

Modifies the state of this coverage object as if all the tuples fed to the other had been fed to this one as well as its current contents.

Parameters:

other - different coverage object of a type assumed compatible with this object

coverageText

String coverageText()

Provides a short, human-readable indication of the coverage.

Returns:

string representation