Package org.apache.sis.internal.sql.feature

Class FeatureStream

java.lang.Object

org.apache.sis.internal.stream.BaseStreamWrapper<T,Stream<T>>

org.apache.sis.internal.stream.StreamWrapper<T>

org.apache.sis.internal.stream.DeferredStream<AbstractFeature>

org.apache.sis.internal.sql.feature.FeatureStream

All Implemented Interfaces:

AutoCloseable, BaseStream<AbstractFeature,Stream<AbstractFeature>>, Stream<AbstractFeature>

final class FeatureStream
extends DeferredStream<AbstractFeature>

A stream of Feature instances from a table. This implementation intercepts some Stream method calls such as count(), distinct(), skip(long) and limit(long) in order to delegate the operation to the underlying SQL database.

Optimization strategies are also propagated to streams obtained using map(Function) and StreamWrapper.mapToDouble(ToDoubleFunction). However, for result consistency, no optimization is stacked anymore after either filter(Predicate) or StreamWrapper.flatMap(Function) operations are called, because they modify volumetry (the count of stream elements is not bound 1 to 1 to query result rows).

Since:

1.1

Version:

1.1

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.stream.Stream

Stream.Builder<T extends Object>

Field Summary

Fields

Modifier and Type	Field	Description
private long	count	Maximum number of rows to return, or 0 for no limit.
private boolean	distinct	Whether all returned feature instances should be unique.
private SelectionClauseWriter	filterToSQL	The visitor to use for converting filters/expressions to SQL statements.
private boolean	hasComparator	true if at least one comparator given to sorted(Comparator) is implemented using Java code instead of using SQL statements.
private boolean	hasPredicates	true if at least one predicate given to filter(Predicate) is implemented using Java code instead of using SQL statements.
private long	offset	Number of rows to skip in underlying SQL query, or 0 for none.
private SelectionClause	selection	The SQL fragment on the right side of the WHERE keyword.
private SortBy<? super AbstractFeature>	sort	The ORDER BY clauses, or null if none.
private final Table	table	The table which is the source of features.

Constructor Summary

Constructors

Constructor	Description
FeatureStream(Table table, boolean parallel)	Creates a new stream of features.

Method Summary

Modifier and Type	Method	Description
long	count()	Counts the number of elements in the table.
protected Spliterator<AbstractFeature>	createSourceIterator()	Creates the iterator which will provide the actual feature instances.
Stream<AbstractFeature>	distinct()	Requests this stream to return distinct feature instances.
private Stream<AbstractFeature>	empty()	Marks this stream as inactive and returns an empty stream.
Stream<AbstractFeature>	filter(Predicate<? super AbstractFeature> predicate)	Returns a stream with features of this stream that match the given predicate.
private Connection	getConnection()	Acquires a connection to the database.
private boolean	isPagined()	Returns true if either count or offset is set.
Stream<AbstractFeature>	limit(long maxSize)	Truncates this stream to the given number of elements.
private void	makeReadOnly(Connection connection)	Makes the given connection read-only and apply some configuration for better performances.
<R> Stream<R>	map(Function<? super AbstractFeature,? extends R> mapper)	Returns a stream with results of applying the given function to the elements of this stream.
Stream<AbstractFeature>	skip(long n)	Discards the specified number of elements.
Stream<AbstractFeature>	sorted()	Returns an equivalent stream that is sorted by feature natural order.
Stream<AbstractFeature>	sorted(Comparator<? super AbstractFeature> comparator)	Returns a stream with features of this stream sorted using the given comparator.
String	toString()	Returns a string representation of this stream for debugging purposes.
Stream<AbstractFeature>	unordered()	Returns an equivalent stream that is unordered.

Methods inherited from class org.apache.sis.internal.stream.DeferredStream

setCloseHandler

Methods inherited from class org.apache.sis.internal.stream.StreamWrapper

allMatch, anyMatch, collect, collect, delegate, findAny, findFirst, flatMap, flatMapToDouble, flatMapToInt, flatMapToLong, forEach, forEachOrdered, iterator, mapToDouble, mapToInt, mapToLong, max, min, noneMatch, onClose, parallel, peek, reduce, reduce, reduce, sequential, source, spliterator, toArray, toArray

Methods inherited from class org.apache.sis.internal.stream.BaseStreamWrapper

close, isParallel

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.stream.BaseStream

close, isParallel

Field Details

table

private final Table table

The table which is the source of features.

filterToSQL

private SelectionClauseWriter filterToSQL

The visitor to use for converting filters/expressions to SQL statements. This is used for writing the content of the SelectionClause. It is usually a singleton instance shared by all databases. It is fetched when first needed.

selection

private SelectionClause selection

The SQL fragment on the right side of the WHERE keyword. This buffer does not including the WHERE keyword. It is created when first needed and discarded after the iterator is created.

hasPredicates

private boolean hasPredicates

true if at least one predicate given to filter(Predicate) is implemented using Java code instead of using SQL statements.

hasComparator

private boolean hasComparator

true if at least one comparator given to sorted(Comparator) is implemented using Java code instead of using SQL statements.

distinct

private boolean distinct

Whether all returned feature instances should be unique.

sort

private SortBy<? super AbstractFeature> sort

The ORDER BY clauses, or null if none.

offset

private long offset

Number of rows to skip in underlying SQL query, or 0 for none.

See Also:

• skip(long)

count

private long count

Maximum number of rows to return, or 0 for no limit. Note that 0 is a valid value for the limit, but when this value is reached the empty() stream should be immediately returned.

See Also:

• limit(long)

Constructor Details

FeatureStream

FeatureStream(Table table,
 boolean parallel)

Creates a new stream of features.

Parameters:

table - the source table.

parallel - whether the stream should be initially parallel.

Method Details

empty

private Stream<AbstractFeature> empty()

Marks this stream as inactive and returns an empty stream. This method is invoked when an operation resulted in an empty stream.

isPagined

private boolean isPagined()

Returns true if either count or offset is set. In such case, we cannot continue to build the SQL statement because the OFFSET ... FETCH NEXT clauses in SQL are executed last. Consequently, in order to have consistent results, the #offset(long) and limit(long) methods need to be the last methods invoked on this stream.

filter

public Stream<AbstractFeature> filter(Predicate<? super AbstractFeature> predicate)

Returns a stream with features of this stream that match the given predicate. If the given predicate is an instance of Filter, then this method tries to express the filter using SQL statements.

Specified by:

filter in interface Stream<AbstractFeature>

Overrides:

filter in class StreamWrapper<AbstractFeature>

distinct

public Stream<AbstractFeature> distinct()

Requests this stream to return distinct feature instances. This operation will be done with a SQL DISTINCT clause if possible.

Specified by:

distinct in interface Stream<AbstractFeature>

Overrides:

distinct in class StreamWrapper<AbstractFeature>

unordered

public Stream<AbstractFeature> unordered()

Returns an equivalent stream that is unordered.

Specified by:

unordered in interface BaseStream<AbstractFeature,Stream<AbstractFeature>>

Overrides:

unordered in class StreamWrapper<AbstractFeature>

sorted

public Stream<AbstractFeature> sorted()

Returns an equivalent stream that is sorted by feature natural order. This is defined as a matter of principle, but will cause a ClassCastException to be thrown when a terminal operation will be executed because Feature instances are not comparable.

Specified by:

sorted in interface Stream<AbstractFeature>

Overrides:

sorted in class StreamWrapper<AbstractFeature>

sorted

public Stream<AbstractFeature> sorted(Comparator<? super AbstractFeature> comparator)

Returns a stream with features of this stream sorted using the given comparator.

Specified by:

sorted in interface Stream<AbstractFeature>

Overrides:

sorted in class StreamWrapper<AbstractFeature>

skip

public Stream<AbstractFeature> skip(long n)

Discards the specified number of elements. This operation will be done with a SQL OFFSET clause.

Specified by:

skip in interface Stream<AbstractFeature>

Overrides:

skip in class StreamWrapper<AbstractFeature>

limit

public Stream<AbstractFeature> limit(long maxSize)

Truncates this stream to the given number of elements. This operation will be done with a SQL FETCH NEXT clause.

Specified by:

limit in interface Stream<AbstractFeature>

Overrides:

limit in class StreamWrapper<AbstractFeature>

map

public <R> Stream<R> map(Function<? super AbstractFeature,? extends R> mapper)

Returns a stream with results of applying the given function to the elements of this stream. The skip and limit operations applied on the returned stream may continue to be optimized.

Specified by:

map in interface Stream<AbstractFeature>

Overrides:

map in class StreamWrapper<AbstractFeature>

count

public long count()

Counts the number of elements in the table. This method uses a simpler SQL statement than the one associated to the table. For example if a property is an association to another feature, the SQL statement will contain only the foreigner key values, not an inner join to the other feature table.

Specified by:

count in interface Stream<AbstractFeature>

Overrides:

count in class StreamWrapper<AbstractFeature>

getConnection

private Connection getConnection()
                          throws SQLException

Acquires a connection to the database. The makeReadOnly(Connection) method should be invoked after this method. Those two methods are separated for allowing the immediate use of the connection in a try ... finally block.

Returns:

a new connection to the database.

Throws:

SQLException - if we cannot create a new connection. See DataSource.getConnection() for details.

makeReadOnly

private void makeReadOnly(Connection connection)
                   throws SQLException

Makes the given connection read-only and apply some configuration for better performances. Current configurations are:

• querying read-only.

Parameters:

connection - the connection to configure.

Throws:

SQLException

createSourceIterator

protected Spliterator<AbstractFeature> createSourceIterator()
                                                     throws Exception

Creates the iterator which will provide the actual feature instances. The characteristics of the returned iterator must be the characteristics declared in the FeatureStream constructor.

This method is invoked at most once, generally when a stream terminal operation is invoked. After this method is invoked, this stream will not be active anymore.

Specified by:

createSourceIterator in class DeferredStream<AbstractFeature>

Returns:

an iterator over the feature elements.

Throws:

DataStoreException - if a data model dependent error occurs.

SQLException - if an error occurs while executing the SQL statement.

Exception - if the iterator cannot be created.

toString

public String toString()

Returns a string representation of this stream for debugging purposes. The returned string tells whether filtering and sorting are done using SQL statement, Java code, or a mix of both.

Overrides:

toString in class Object