- Type Parameters:
R
- The cursor's record type
- All Superinterfaces:
AutoCloseable
,Fields
,Formattable
,Iterable<R>
ResultSet
. Unlike Result
, data can only be accessed
sequentially, using an Iterator
, or the cursor's hasNext()
and fetch()
methods.
Client code must close this Cursor
in order to close the underlying
PreparedStatement
and ResultSet
The cursor can be consumed in two ways:
- Record by record: Such methods can be recognised by the term "Next" in
the method name, e.g.
fetchNext(int)
. - Completely in one go: Such methods do not have the term "Next" in their
method names, e.g.
fetch()
.
Note: Unlike usual implementations of Iterable
, a Cursor
can only provide one Iterator
!
- Author:
- Lukas Eder
-
Method Summary
Modifier and TypeMethodDescriptionvoid
close()
Explicitly close the underlyingPreparedStatement
andResultSet
.<X,
A> X Reduce the execution results of this query using aCollector
.fetch()
Fetch all remaining records as a result.fetch
(int number) Deprecated, for removal: This API element is subject to removal in a future version.<E> @NotNull List<E>
fetch
(RecordMapper<? super R, E> mapper) Fetch results into a custom mapper callback.<H extends RecordHandler<? super R>>
HfetchInto
(H handler) Deprecated, for removal: This API element is subject to removal in a future version.- 3.15.0 - [#11902] - UseIterable.forEach(Consumer)
based methods, instead.<E> @NotNull List<E>
Map resulting records onto a custom type.Map resulting records onto a custom record.Fetch the next record from the cursor.fetchNext
(int number) Fetch the next couple of records from the cursor.<E> E
fetchNext
(RecordMapper<? super R, E> mapper) Fetch the next record into a custom mapper callback.<H extends RecordHandler<? super R>>
HfetchNextInto
(H handler) Deprecated, for removal: This API element is subject to removal in a future version.- 3.15.0 - [#11902] - UseIterable.forEach(Consumer)
based methods, instead.<E> E
fetchNextInto
(Class<? extends E> type) Map the next resulting record onto a custom type.<Z extends Record>
ZfetchNextInto
(Table<Z> table) Map the next resulting record onto a custom record.Fetch the next record from the cursor.<E> @NotNull Optional<E>
fetchNextOptional
(RecordMapper<? super R, E> mapper) Fetch the next record into a custom mapper callback.<E> @NotNull Optional<E>
fetchNextOptionalInto
(Class<? extends E> type) Map the next resulting record onto a custom type.fetchNextOptionalInto
(Table<Z> table) Map the next resulting record onto a custom record.fetchOne()
Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNext()
instead.<E> E
fetchOne
(RecordMapper<? super R, E> mapper) Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNext(RecordMapper)
instead.<H extends RecordHandler<? super R>>
HfetchOneInto
(H handler) Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNextInto(RecordHandler)
instead.<E> E
fetchOneInto
(Class<? extends E> type) Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNextInto(Class)
instead.<Z extends Record>
ZfetchOneInto
(Table<Z> table) Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNextInto(Table)
instead.Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNextOptional()
instead.<E> @NotNull Optional<E>
fetchOptional
(RecordMapper<? super R, E> mapper) Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNextOptional(RecordMapper)
instead.<E> @NotNull Optional<E>
fetchOptionalInto
(Class<? extends E> type) Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNextOptionalInto(Class)
instead.fetchOptionalInto
(Table<Z> table) Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNextOptionalInto(Table)
instead.boolean
hasNext()
Check whether this cursor has a next record.boolean
isClosed()
Check whether thisCursor
has been explicitly or "conveniently" closed.@NotNull RecordType<R>
Get this cursor's row type.@Nullable ResultSet
Get theCursor
's underlyingResultSet
.stream()
Turn thisCursor
into aStream
.Methods inherited from interface org.jooq.Fields
dataType, dataType, dataType, dataTypes, field, field, field, field, field, field, field, field, field, field, fields, fields, fields, fields, fields, fieldsRow, fieldStream, indexOf, indexOf, indexOf, type, type, type, types
Methods inherited from interface org.jooq.Formattable
format, format, format, format, format, format, format, format, format, formatChart, formatChart, formatChart, formatChart, formatChart, formatChart, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatCSV, formatHTML, formatHTML, formatHTML, formatInsert, formatInsert, formatInsert, formatInsert, formatInsert, formatInsert, formatJSON, formatJSON, formatJSON, formatJSON, formatJSON, formatJSON, formatXML, formatXML, formatXML, formatXML, formatXML, formatXML, intoXML, intoXML, intoXML, intoXML
Methods inherited from interface java.lang.Iterable
forEach, iterator, spliterator
-
Method Details
-
recordType
Get this cursor's row type. -
hasNext
Check whether this cursor has a next record.This will conveniently close the
Cursor
, after the lastRecord
was fetched.- Throws:
DataAccessException
- if something went wrong executing the query
-
fetch
Fetch all remaining records as a result.This will conveniently close the
Cursor
, after the lastRecord
was fetched.The result and its contained records are attached to the original
Configuration
by default. UseSettings.isAttachRecords()
to override this behaviour.- Throws:
DataAccessException
- if something went wrong executing the query
-
fetch
@NotNull @Deprecated(forRemoval=true, since="3.10") @NotNull Result<R> fetch(int number) throws DataAccessException Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNext(int)
instead.- Throws:
DataAccessException
-
fetchNext
Fetch the next couple of records from the cursor.This will conveniently close the
Cursor
, after the lastRecord
was fetched.The result and its contained records are attached to the original
Configuration
by default. UseSettings.isAttachRecords()
to override this behaviour.- Parameters:
number
- The number of records to fetch. If this is0
or negative an empty list is returned, the cursor is untouched. If this is greater than the number of remaining records, then all remaining records are returned.- Throws:
DataAccessException
- if something went wrong executing the query
-
fetchInto
@Deprecated(forRemoval=true, since="3.15") @NotNull <H extends RecordHandler<? super R>> H fetchInto(H handler) throws DataAccessException Deprecated, for removal: This API element is subject to removal in a future version.- 3.15.0 - [#11902] - UseIterable.forEach(Consumer)
based methods, instead.Fetch results into a custom handler callback.The resulting records are attached to the original
Configuration
by default. UseSettings.isAttachRecords()
to override this behaviour.- Parameters:
handler
- The handler callback- Returns:
- Convenience result, returning the parameter handler itself
- Throws:
DataAccessException
- if something went wrong executing the query
-
fetch
Fetch results into a custom mapper callback.- Parameters:
mapper
- The mapper callback- Returns:
- The custom mapped records
- Throws:
DataAccessException
- if something went wrong executing the query
-
fetchInto
@NotNull <E> @NotNull List<E> fetchInto(Class<? extends E> type) throws DataAccessException, MappingException Map resulting records onto a custom type.This is the same as calling
fetch().into(type)
. SeeRecord.into(Class)
for more details- Type Parameters:
E
- The generic entity type.- Parameters:
type
- The entity type.- Throws:
DataAccessException
- if something went wrong executing the queryMappingException
- wrapping any reflection or data type conversion exception that might have occurred while mapping records- See Also:
-
fetchInto
@NotNull <Z extends Record> @NotNull Result<Z> fetchInto(Table<Z> table) throws DataAccessException, MappingException Map resulting records onto a custom record.This is the same as calling
fetch().into(table)
. SeeRecord.into(Class)
for more detailsThe result and its contained records are attached to the original
Configuration
by default. UseSettings.isAttachRecords()
to override this behaviour.- Type Parameters:
Z
- The generic table record type.- Parameters:
table
- The table type.- Throws:
DataAccessException
- if something went wrong executing the queryMappingException
- wrapping any reflection or data type conversion exception that might have occurred while mapping records- See Also:
-
fetchOne
Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNext()
instead.- Throws:
DataAccessException
-
fetchOneInto
@NotNull @Deprecated(forRemoval=true, since="3.10") <H extends RecordHandler<? super R>> H fetchOneInto(H handler) throws DataAccessException Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNextInto(RecordHandler)
instead.- Throws:
DataAccessException
-
fetchOne
@Nullable @Deprecated(forRemoval=true, since="3.10") <E> E fetchOne(RecordMapper<? super R, E> mapper) throws DataAccessExceptionDeprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNext(RecordMapper)
instead.- Throws:
DataAccessException
-
fetchOneInto
@Nullable @Deprecated(forRemoval=true, since="3.10") <Z extends Record> Z fetchOneInto(Table<Z> table) throws DataAccessException, MappingException Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNextInto(Table)
instead.- Throws:
DataAccessException
MappingException
-
fetchNext
Fetch the next record from the cursor.This will conveniently close the
Cursor
, after the lastRecord
was fetched.The resulting record is attached to the original
Configuration
by default. UseSettings.isAttachRecords()
to override this behaviour.- Returns:
- The next record from the cursor, or
null
if there is no next record. - Throws:
DataAccessException
- if something went wrong executing the query
-
fetchNextInto
@Deprecated(forRemoval=true, since="3.15") @NotNull <H extends RecordHandler<? super R>> H fetchNextInto(H handler) throws DataAccessException Deprecated, for removal: This API element is subject to removal in a future version.- 3.15.0 - [#11902] - UseIterable.forEach(Consumer)
based methods, instead.Fetch the next record into a custom handler callback.This will conveniently close the
Cursor
, after the lastRecord
was fetched.The resulting record is attached to the original
Configuration
by default. UseSettings.isAttachRecords()
to override this behaviour.- Parameters:
handler
- The handler callback- Returns:
- Convenience result, returning the parameter handler itself
- Throws:
DataAccessException
- if something went wrong executing the query
-
fetchOneInto
@Nullable @Deprecated(forRemoval=true, since="3.10") <E> E fetchOneInto(Class<? extends E> type) throws DataAccessException, MappingException Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNextInto(Class)
instead.- Throws:
DataAccessException
MappingException
-
fetchNextInto
Map the next resulting record onto a custom type.This is the same as calling
fetchOne().into(type)
. SeeRecord.into(Class)
for more details- Type Parameters:
E
- The generic entity type.- Parameters:
type
- The entity type.- Throws:
DataAccessException
- if something went wrong executing the queryMappingException
- wrapping any reflection or data type conversion exception that might have occurred while mapping records- See Also:
-
fetchNext
Fetch the next record into a custom mapper callback.This will conveniently close the
Cursor
, after the lastRecord
was fetched.- Parameters:
mapper
- The mapper callback- Returns:
- The custom mapped record
- Throws:
DataAccessException
- if something went wrong executing the query
-
fetchNextInto
@Nullable <Z extends Record> Z fetchNextInto(Table<Z> table) throws DataAccessException, MappingException Map the next resulting record onto a custom record.This is the same as calling
fetchOne().into(table)
. SeeRecord.into(Class)
for more detailsThe resulting record is attached to the original
Configuration
by default. UseSettings.isAttachRecords()
to override this behaviour.- Type Parameters:
Z
- The generic table record type.- Parameters:
table
- The table type.- Throws:
DataAccessException
- if something went wrong executing the queryMappingException
- wrapping any reflection or data type conversion exception that might have occurred while mapping records- See Also:
-
fetchOptional
@NotNull @Deprecated(forRemoval=true, since="3.10") @NotNull Optional<R> fetchOptional() throws DataAccessExceptionDeprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNextOptional()
instead.- Throws:
DataAccessException
-
fetchOptionalInto
@NotNull @Deprecated(forRemoval=true, since="3.10") <E> @NotNull Optional<E> fetchOptionalInto(Class<? extends E> type) throws DataAccessException, MappingException Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNextOptionalInto(Class)
instead.- Throws:
DataAccessException
MappingException
-
fetchOptional
@NotNull @Deprecated(forRemoval=true, since="3.10") <E> @NotNull Optional<E> fetchOptional(RecordMapper<? super R, E> mapper) throws DataAccessExceptionDeprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNextOptional(RecordMapper)
instead.- Throws:
DataAccessException
-
fetchOptionalInto
@NotNull @Deprecated(forRemoval=true, since="3.10") <Z extends Record> @NotNull Optional<Z> fetchOptionalInto(Table<Z> table) throws DataAccessException, MappingException Deprecated, for removal: This API element is subject to removal in a future version.- 3.10 - [#6363] - UsefetchNextOptionalInto(Table)
instead.- Throws:
DataAccessException
MappingException
-
fetchNextOptional
Fetch the next record from the cursor.This will conveniently close the
Cursor
, after the lastRecord
was fetched.The resulting record is attached to the original
Configuration
by default. UseSettings.isAttachRecords()
to override this behaviour.- Returns:
- The next record from the cursor
- Throws:
DataAccessException
- if something went wrong executing the query
-
fetchNextOptionalInto
@NotNull <E> @NotNull Optional<E> fetchNextOptionalInto(Class<? extends E> type) throws DataAccessException, MappingException Map the next resulting record onto a custom type.This is the same as calling
fetchOne().into(type)
. SeeRecord.into(Class)
for more details- Type Parameters:
E
- The generic entity type.- Parameters:
type
- The entity type.- Throws:
DataAccessException
- if something went wrong executing the queryMappingException
- wrapping any reflection or data type conversion exception that might have occurred while mapping records- See Also:
-
fetchNextOptional
@NotNull <E> @NotNull Optional<E> fetchNextOptional(RecordMapper<? super R, E> mapper) throws DataAccessExceptionFetch the next record into a custom mapper callback.This will conveniently close the
Cursor
, after the lastRecord
was fetched.- Parameters:
mapper
- The mapper callback- Returns:
- The custom mapped record
- Throws:
DataAccessException
- if something went wrong executing the query
-
fetchNextOptionalInto
@NotNull <Z extends Record> @NotNull Optional<Z> fetchNextOptionalInto(Table<Z> table) throws DataAccessException, MappingException Map the next resulting record onto a custom record.This is the same as calling
fetchOne().into(table)
. SeeRecord.into(Class)
for more detailsThe resulting record is attached to the original
Configuration
by default. UseSettings.isAttachRecords()
to override this behaviour.- Type Parameters:
Z
- The generic table record type.- Parameters:
table
- The table type.- Throws:
DataAccessException
- if something went wrong executing the queryMappingException
- wrapping any reflection or data type conversion exception that might have occurred while mapping records- See Also:
-
stream
Turn thisCursor
into aStream
.- Throws:
DataAccessException
- if something went wrong executing the query
-
collect
Reduce the execution results of this query using aCollector
.This works in the same way as calling the following code:
cursor.stream().collect(collector);
- Parameters:
collector
- The collector that collects all records and accumulates them into a result type.- Returns:
- The result of the collection.
- Throws:
DataAccessException
- if something went wrong executing the query
-
close
Explicitly close the underlyingPreparedStatement
andResultSet
.If you fetch all records from the underlying
ResultSet
, jOOQCursor
implementations will close themselves for you. Callingclose()
again will have no effect.- Specified by:
close
in interfaceAutoCloseable
- Throws:
DataAccessException
- if something went wrong executing the query
-
isClosed
boolean isClosed()Check whether thisCursor
has been explicitly or "conveniently" closed.Explicit closing can be achieved by calling
close()
from client code. "Convenient" closing is done by any of the other methods, when the last record was fetched. -
resultSet
Get theCursor
's underlyingResultSet
.This will return a
ResultSet
wrapping the JDBC driver'sResultSet
. Closing thisResultSet
may close the producingStatement
orPreparedStatement
, depending on your setting forResultQuery.keepStatement(boolean)
.Modifying this
ResultSet
will affect thisCursor
.- Returns:
- The underlying
ResultSet
. May benull
, for instance when theCursor
is closed.
-
fetchNext(int)
instead.