Package com.storedobject.core

Class Query

java.lang.Object

com.storedobject.core.Query

All Implemented Interfaces:

Closeable, AutoCloseable, Iterable<ResultSet>, Iterator<ResultSet>

public class Query
extends Object
implements Iterator<ResultSet>, Iterable<ResultSet>, Closeable

The Query class provides a mechanism to iterate over rows in a SQL result set. It implements Iterator<ResultSet>, Iterable<ResultSet>, and Closeable interfaces to facilitate traversing and managing the lifecycle of database query results using for/for each/while loops.

Query objects allow navigation through the result set, provide means to map results into other data types, and support optional transformation functions to manipulate individual rows.

Author:

Syam

Method Summary

Modifier and Type	Method	Description
void	close()	Closes the resources associated with this query.
boolean	eoq()	Determines if the end of the query has been reached.
ResultSet	getResultSet()	Retrieves the current result set of the query.
boolean	hasNext()	Checks if there are additional results available in the query.
Iterable<Id>	idIterator()	Provides an iterable over the query results, using the default column index.
Iterable<Id>	idIterator(int column)	Provides an iterable of Id objects by mapping the result set from a specific column index of a database query to instances of Id.
Iterable<Integer>	integerIterator()	Creates an iterable that iterates over the first column of the result set, mapping each row to an integer value.
Iterable<Integer>	integerIterator(int column)	Creates an iterable over integers retrieved from a specified column of a database result set.
Iterator<ResultSet>	iterator()	Returns an iterator for traversing the results of the query.
Query	limit(long limit)	Limits the number of results returned by the query.
ResultSet	next()	Retrieves the next result set from the query.
<T> Iterable<T>	objectIterator(Function<ResultSet,T> objectMapper)	Creates an Iterable that maps each ResultSet entry from the query into an object of type T using the provided objectMapper function.
void	remove()	Removes the current element from the underlying data structure.
Query	skip(long skip)	Skips a specified number of rows in the result set.
Iterable<String>	stringIterator()	Provides an iterable sequence of string values retrieved from the query's result set, defaulting to the first column (column index 1).
Iterable<String>	stringIterator(int column)	Provides an iterable over a specific column in the result set, extracting its values as strings.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface java.util.Iterator

forEachRemaining

Method Details

close

public void close()

Closes the resources associated with this query. This method ensures that any open database resources, represented by the sql object, are properly cleaned up. After the cleanup, the sql field is set to null to indicate that the associated resources have been released. Repeated calls to this method are safe and effectively have no additional effect once the resources have already been closed and sql is null.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

iterator

@Nonnull
public Iterator<ResultSet> iterator()

Returns an iterator for traversing the results of the query.

Specified by:

iterator in interface Iterable<ResultSet>

Returns:

an iterator over the ResultSet objects produced by the query

getResultSet

public ResultSet getResultSet()

Retrieves the current result set of the query.

Returns:

the ResultSet object obtained from the underlying SQL query execution.

next

public ResultSet next()

Retrieves the next result set from the query. If no result set is available or the query is invalid, this method will throw a NoSuchElementException. It skips over the current result set if it has already been read before retrieving the next result.

Specified by:

next in interface Iterator<ResultSet>

Returns:

the next ResultSet retrieved from the query

Throws:

NoSuchElementException - if there are no more results available or the query is invalid

hasNext

public boolean hasNext()

Checks if there are additional results available in the query. This method determines whether there are more elements to process in the query. It manages conditions such as end-of-query state, ensures the query is properly closed when no further results are available, and skips the current result if necessary.

Specified by:

hasNext in interface Iterator<ResultSet>

Returns:

true if additional results are available; false otherwise.

remove

public void remove()

Removes the current element from the underlying data structure. This method is unsupported for the current implementation and will always throw an UnsupportedOperationException. It is included to fulfill the Iterator interface contract.

Specified by:

remove in interface Iterator<ResultSet>

Throws:

UnsupportedOperationException - always, as this operation is not supported.

stringIterator

public Iterable<String> stringIterator()

Provides an iterable sequence of string values retrieved from the query's result set, defaulting to the first column (column index 1).

Returns:

an Iterable<String> representing the sequence of string values from the result set in the specified column.

stringIterator

public Iterable<String> stringIterator(int column)

Provides an iterable over a specific column in the result set, extracting its values as strings.

Parameters:

column - the column index (1-based) to retrieve string values from

Returns:

an iterable of strings corresponding to the specified column in the result set

integerIterator

public Iterable<Integer> integerIterator()

Creates an iterable that iterates over the first column of the result set, mapping each row to an integer value.

Returns:

an Iterable that provides integer values from the first column of the result set

integerIterator

public Iterable<Integer> integerIterator(int column)

Creates an iterable over integers retrieved from a specified column of a database result set. The method maps the values obtained from the given column index of the result set into Integer objects. If an SQL exception occurs during the retrieval of a value, it will return null for that entry.

Parameters:

column - the column index of the result set from which integers are to be retrieved

Returns:

an Iterable of integers corresponding to the specified column's values in the result set

idIterator

public Iterable<Id> idIterator()

Provides an iterable over the query results, using the default column index.

Returns:

an Iterable of Id objects from the query results.

idIterator

public Iterable<Id> idIterator(int column)

Provides an iterable of Id objects by mapping the result set from a specific column index of a database query to instances of Id.

Parameters:

column - the column index to extract Id values from the result set

Returns:

an Iterable<Id> that iterates over the Id objects from the specified column

objectIterator

public <T> Iterable<T> objectIterator(Function<ResultSet,T> objectMapper)

Creates an Iterable that maps each ResultSet entry from the query into an object of type T using the provided objectMapper function.

Type Parameters:

T - the type of the object to be created from each row of the ResultSet

Parameters:

objectMapper - a Function that maps a ResultSet to an object of type T

Returns:

an Iterable over objects of type T, representing the mapped entries from the query

eoq

public boolean eoq()

Determines if the end of the query has been reached. This method is a utility to check if there are no more results available in the query being processed. It internally calls the hasNext() method to verify if additional elements exist and negates its result.

Returns:

true if the end of the query has been reached (no more results); false otherwise.

skip

public Query skip(long skip)

Skips a specified number of rows in the result set.

Parameters:

skip - the number of rows to skip

Returns:

the current Query instance, for method chaining

limit

public Query limit(long limit)

Limits the number of results returned by the query.

Parameters:

limit - the maximum number of results to be returned

Returns:

a new Query instance with the specified limit applied