Module org.jooq

Package org.jooq

Interface Cursor<R extends Record>

Type Parameters:

R - The cursor's record type

All Superinterfaces:

AutoCloseable, Fields, Formattable, Iterable<R>

public interface Cursor<R extends Record>
extends Fields, Iterable<R>, Formattable, AutoCloseable

Cursors allow for lazy, sequential access to an underlying JDBC 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 Type	Method	Description
void	close()	Explicitly close the underlying PreparedStatement and ResultSet.
<X, A> X	collect(Collector<? super R,A,X> collector)	Reduce the execution results of this query using a Collector.
@NotNull Result<R>	fetch()	Fetch all remaining records as a result.
@NotNull Result<R>	fetch(int number)	Deprecated, for removal: This API element is subject to removal in a future version. - 3.10 - [#6363] - Use fetchNext(int) instead.
<E> @NotNull List<E>	fetch(RecordMapper<? super R,E> mapper)	Fetch results into a custom mapper callback.
<H extends RecordHandler<? super R>> H	fetchInto(H handler)	Deprecated, for removal: This API element is subject to removal in a future version. - 3.15.0 - [#11902] - Use Iterable.forEach(Consumer) based methods, instead.
<E> @NotNull List<E>	fetchInto(Class<? extends E> type)	Map resulting records onto a custom type.
<Z extends Record> @NotNull Result<Z>	fetchInto(Table<Z> table)	Map resulting records onto a custom record.
R	fetchNext()	Fetch the next record from the cursor.
@NotNull Result<R>	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>> H	fetchNextInto(H handler)	Deprecated, for removal: This API element is subject to removal in a future version. - 3.15.0 - [#11902] - Use Iterable.forEach(Consumer) based methods, instead.
<E> E	fetchNextInto(Class<? extends E> type)	Map the next resulting record onto a custom type.
<Z extends Record> Z	fetchNextInto(Table<Z> table)	Map the next resulting record onto a custom record.
@NotNull Optional<R>	fetchNextOptional()	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.
<Z extends Record> @NotNull Optional<Z>	fetchNextOptionalInto(Table<Z> table)	Map the next resulting record onto a custom record.
R	fetchOne()	Deprecated, for removal: This API element is subject to removal in a future version. - 3.10 - [#6363] - Use fetchNext() 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] - Use fetchNext(RecordMapper) instead.
<H extends RecordHandler<? super R>> H	fetchOneInto(H handler)	Deprecated, for removal: This API element is subject to removal in a future version. - 3.10 - [#6363] - Use fetchNextInto(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] - Use fetchNextInto(Class) instead.
<Z extends Record> Z	fetchOneInto(Table<Z> table)	Deprecated, for removal: This API element is subject to removal in a future version. - 3.10 - [#6363] - Use fetchNextInto(Table) instead.
@NotNull Optional<R>	fetchOptional()	Deprecated, for removal: This API element is subject to removal in a future version. - 3.10 - [#6363] - Use fetchNextOptional() 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] - Use fetchNextOptional(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] - Use fetchNextOptionalInto(Class) instead.
<Z extends Record> @NotNull Optional<Z>	fetchOptionalInto(Table<Z> table)	Deprecated, for removal: This API element is subject to removal in a future version. - 3.10 - [#6363] - Use fetchNextOptionalInto(Table) instead.
boolean	hasNext()	Check whether this cursor has a next record.
boolean	isClosed()	Check whether this Cursor has been explicitly or "conveniently" closed.
@NotNull RecordType<R>	recordType()	Get this cursor's row type.
@Nullable ResultSet	resultSet()	Get the Cursor's underlying ResultSet.
@NotNull Stream<R>	stream()	Turn this Cursor into a Stream.

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

@NotNull
@NotNull RecordType<R> recordType()

Get this cursor's row type.

hasNext

boolean hasNext()
         throws DataAccessException

Check whether this cursor has a next record.

This will conveniently close the Cursor, after the last Record was fetched.

Throws:

DataAccessException - if something went wrong executing the query

fetch

@NotNull
@NotNull Result<R> fetch()
                  throws DataAccessException

Fetch all remaining records as a result.

This will conveniently close the Cursor, after the last Record was fetched.

The result and its contained records are attached to the original Configuration by default. Use Settings.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] - Use fetchNext(int) instead.

Throws:

DataAccessException

fetchNext

@NotNull
@NotNull Result<R> fetchNext(int number)
                      throws DataAccessException

Fetch the next couple of records from the cursor.

This will conveniently close the Cursor, after the last Record was fetched.

The result and its contained records are attached to the original Configuration by default. Use Settings.isAttachRecords() to override this behaviour.

Parameters:

number - The number of records to fetch. If this is 0 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] - Use Iterable.forEach(Consumer) based methods, instead.

Fetch results into a custom handler callback.

The resulting records are attached to the original Configuration by default. Use Settings.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

@NotNull
<E> @NotNull List<E> fetch(RecordMapper<? super R,E> mapper)
                    throws DataAccessException

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). See Record.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 query

MappingException - wrapping any reflection or data type conversion exception that might have occurred while mapping records

See Also:

Record.into(Class), Result.into(Class), DefaultRecordMapper

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). See Record.into(Class) for more details

The result and its contained records are attached to the original Configuration by default. Use Settings.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 query

MappingException - wrapping any reflection or data type conversion exception that might have occurred while mapping records

See Also:

Record.into(Class), Result.into(Class)

fetchOne

@Nullable
@Deprecated(forRemoval=true,
            since="3.10")
R fetchOne()
    throws DataAccessException

Deprecated, for removal: This API element is subject to removal in a future version.

- 3.10 - [#6363] - Use fetchNext() 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] - Use fetchNextInto(RecordHandler) instead.

Throws:

DataAccessException

fetchOne

@Nullable
@Deprecated(forRemoval=true,
            since="3.10")
<E> E fetchOne(RecordMapper<? super R,E> mapper)
        throws DataAccessException

Deprecated, for removal: This API element is subject to removal in a future version.

- 3.10 - [#6363] - Use fetchNext(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] - Use fetchNextInto(Table) instead.

Throws:

DataAccessException

MappingException

fetchNext

@Nullable
R fetchNext()
     throws DataAccessException

Fetch the next record from the cursor.

This will conveniently close the Cursor, after the last Record was fetched.

The resulting record is attached to the original Configuration by default. Use Settings.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] - Use Iterable.forEach(Consumer) based methods, instead.

Fetch the next record into a custom handler callback.

This will conveniently close the Cursor, after the last Record was fetched.

The resulting record is attached to the original Configuration by default. Use Settings.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] - Use fetchNextInto(Class) instead.

Throws:

DataAccessException

MappingException

fetchNextInto

@Nullable
<E> E fetchNextInto(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). See Record.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 query

MappingException - wrapping any reflection or data type conversion exception that might have occurred while mapping records

See Also:

Record.into(Class), Result.into(Class), DefaultRecordMapper

fetchNext

@Nullable
<E> E fetchNext(RecordMapper<? super R,E> mapper)
         throws DataAccessException

Fetch the next record into a custom mapper callback.

This will conveniently close the Cursor, after the last Record 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). See Record.into(Class) for more details

The resulting record is attached to the original Configuration by default. Use Settings.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 query

MappingException - wrapping any reflection or data type conversion exception that might have occurred while mapping records

See Also:

Record.into(Class), Result.into(Class)

fetchOptional

@NotNull
@Deprecated(forRemoval=true,
            since="3.10")
@NotNull Optional<R> fetchOptional()
                            throws DataAccessException

Deprecated, for removal: This API element is subject to removal in a future version.

- 3.10 - [#6363] - Use fetchNextOptional() 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] - Use fetchNextOptionalInto(Class) instead.

Throws:

DataAccessException

MappingException

fetchOptional

@NotNull
@Deprecated(forRemoval=true,
            since="3.10")
<E> @NotNull Optional<E> fetchOptional(RecordMapper<? super R,E> mapper)
                                throws DataAccessException

Deprecated, for removal: This API element is subject to removal in a future version.

- 3.10 - [#6363] - Use fetchNextOptional(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] - Use fetchNextOptionalInto(Table) instead.

Throws:

DataAccessException

MappingException

fetchNextOptional

@NotNull
@NotNull Optional<R> fetchNextOptional()
                                throws DataAccessException

Fetch the next record from the cursor.

This will conveniently close the Cursor, after the last Record was fetched.

The resulting record is attached to the original Configuration by default. Use Settings.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). See Record.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 query

MappingException - wrapping any reflection or data type conversion exception that might have occurred while mapping records

See Also:

Record.into(Class), Result.into(Class), DefaultRecordMapper

fetchNextOptional

@NotNull
<E> @NotNull Optional<E> fetchNextOptional(RecordMapper<? super R,E> mapper)
                                    throws DataAccessException

Fetch the next record into a custom mapper callback.

This will conveniently close the Cursor, after the last Record 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). See Record.into(Class) for more details

The resulting record is attached to the original Configuration by default. Use Settings.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 query

MappingException - wrapping any reflection or data type conversion exception that might have occurred while mapping records

See Also:

Record.into(Class), Result.into(Class)

stream

@NotNull
@NotNull Stream<R> stream()
                   throws DataAccessException

Turn this Cursor into a Stream.

Throws:

DataAccessException - if something went wrong executing the query

collect

<X,
A> X collect(Collector<? super R,A,X> collector)
         throws DataAccessException

Reduce the execution results of this query using a Collector.

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

void close()
    throws DataAccessException

Explicitly close the underlying PreparedStatement and ResultSet.

If you fetch all records from the underlying ResultSet, jOOQ Cursor implementations will close themselves for you. Calling close() again will have no effect.

Specified by:

close in interface AutoCloseable

Throws:

DataAccessException - if something went wrong executing the query

isClosed

boolean isClosed()

Check whether this Cursor 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

@Nullable
@Nullable ResultSet resultSet()

Get the Cursor's underlying ResultSet.

This will return a ResultSet wrapping the JDBC driver's ResultSet. Closing this ResultSet may close the producing Statement or PreparedStatement, depending on your setting for ResultQuery.keepStatement(boolean).

Modifying this ResultSet will affect this Cursor.

Returns:

The underlying ResultSet. May be null, for instance when the Cursor is closed.