Module org.jooq

Package org.jooq

Interface Cursor<R extends Record>

Type Parameters:

R - The cursor's record type

All Superinterfaces:

AutoCloseable, Formattable, Iterable<R>

public interface Cursor<R extends Record>
extends 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. - 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)	Fetch results into a custom handler callback.
<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)	Fetch the next record into a custom handler callback.
<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. - 3.10 - [#6363] - Use fetchNext() instead.
<E> E	fetchOne(RecordMapper<? super R,E> mapper)	Deprecated. - 3.10 - [#6363] - Use fetchNext(RecordMapper) instead.
<H extends RecordHandler<? super R>> H	fetchOneInto(H handler)	Deprecated. - 3.10 - [#6363] - Use fetchNextInto(RecordHandler) instead.
<E> E	fetchOneInto(Class<? extends E> type)	Deprecated. - 3.10 - [#6363] - Use fetchNextInto(Class) instead.
<Z extends Record> Z	fetchOneInto(Table<Z> table)	Deprecated. - 3.10 - [#6363] - Use fetchNextInto(Table) instead.
@NotNull Optional<R>	fetchOptional()	Deprecated. - 3.10 - [#6363] - Use fetchNextOptional() instead.
<E> @NotNull Optional<E>	fetchOptional(RecordMapper<? super R,E> mapper)	Deprecated. - 3.10 - [#6363] - Use fetchNextOptional(RecordMapper) instead.
<E> @NotNull Optional<E>	fetchOptionalInto(Class<? extends E> type)	Deprecated. - 3.10 - [#6363] - Use fetchNextOptionalInto(Class) instead.
<Z extends Record> @NotNull Optional<Z>	fetchOptionalInto(Table<Z> table)	Deprecated. - 3.10 - [#6363] - Use fetchNextOptionalInto(Table) instead.
@Nullable Field<?>	field(int index)	Get a specific field from this Cursor.
@Nullable Field<?>	field(String name)	Get a specific field from this Cursor.
<T> @Nullable Field<T>	field(Field<T> field)	Get a specific field from this Cursor.
@Nullable Field<?>	field(Name name)	Get a specific qualified field from this Cursor.
@NotNull Field<?>[]	fields()	Get all fields from this Cursor.
@NotNull Field<?>[]	fields(int... fieldIndexes)	Get all fields from this Cursor, providing some field indexes.
@NotNull Field<?>[]	fields(String... fieldNames)	Get all fields from this Cursor, providing some field names.
@NotNull Field<?>[]	fields(Field<?>... fields)	Get all fields from this Cursor, providing some fields.
@NotNull Field<?>[]	fields(Name... fieldNames)	Get all fields from this Cursor, providing some field names.
@NotNull Row	fieldsRow()	Get this cursor's fields as a Row.
boolean	hasNext()	Check whether this cursor has a next record.
int	indexOf(String fieldName)	Get a field's index from this cursor.
int	indexOf(Field<?> field)	Get a field's index from this cursor.
int	indexOf(Name fieldName)	Get a field's index from this cursor.
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.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 Detail

recordType

@NotNull
@NotNull RecordType<R> recordType()

Get this cursor's row type.

fieldsRow

@NotNull
@NotNull Row fieldsRow()

Get this cursor's fields as a Row.

field

@Nullable
<T> @Nullable Field<T> field(Field<T> field)

Get a specific field from this Cursor.

This will return:

• A field that is the same as the argument field (by identity comparison).
• A field that is equal to the argument field (exact matching fully qualified name).
• A field that is equal to the argument field (partially matching qualified name).
• A field whose name is equal to the name of the argument field.
• null otherwise.

If several fields have the same name, the first one is returned and a warning is logged.

See Also:

Row.field(Field)

field

@Nullable
@Nullable Field<?> field(String name)

Get a specific field from this Cursor.

See Also:

Row.field(String)

field

@Nullable
@Nullable Field<?> field(Name name)

Get a specific qualified field from this Cursor.

See Also:

Row.field(Name)

field

@Nullable
@Nullable Field<?> field(int index)

Get a specific field from this Cursor.

See Also:

Row.field(int)

fields

@NotNull
@NotNull Field<?>[] fields()

Get all fields from this Cursor.

See Also:

Row.fields()

fields

@NotNull
@NotNull Field<?>[] fields(Field<?>... fields)

Get all fields from this Cursor, providing some fields.

Returns:

All available fields

See Also:

Row.fields(Field...)

fields

@NotNull
@NotNull Field<?>[] fields(String... fieldNames)

Get all fields from this Cursor, providing some field names.

Returns:

All available fields

See Also:

Row.fields(String...)

fields

@NotNull
@NotNull Field<?>[] fields(Name... fieldNames)

Get all fields from this Cursor, providing some field names.

Returns:

All available fields

See Also:

Row.fields(Name...)

fields

@NotNull
@NotNull Field<?>[] fields(int... fieldIndexes)

Get all fields from this Cursor, providing some field indexes.

Returns:

All available fields

See Also:

Row.fields(int...)

indexOf

int indexOf(Field<?> field)

Get a field's index from this cursor.

Parameters:

field - The field to look for

Returns:

The field's index or -1 if the field is not contained in this cursor.

indexOf

int indexOf(String fieldName)

Get a field's index from this cursor.

Parameters:

fieldName - The field name to look for

Returns:

The field's index or -1 if the field is not contained in this cursor.

indexOf

int indexOf(Name fieldName)

Get a field's index from this cursor.

Parameters:

fieldName - The field name to look for

Returns:

The field's index or -1 if the field is not contained in this cursor

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
@NotNull Result<R> fetch(int number)
                  throws DataAccessException

Deprecated.

- 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

@NotNull
<H extends RecordHandler<? super R>> H fetchInto(H handler)
                                          throws DataAccessException

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
R fetchOne()
    throws DataAccessException

Deprecated.

- 3.10 - [#6363] - Use fetchNext() instead.

Throws:

DataAccessException

fetchOneInto

@NotNull
@Deprecated
<H extends RecordHandler<? super R>> H fetchOneInto(H handler)
                                             throws DataAccessException

Deprecated.

- 3.10 - [#6363] - Use fetchNextInto(RecordHandler) instead.

Throws:

DataAccessException

fetchOne

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

Deprecated.

- 3.10 - [#6363] - Use fetchNext(RecordMapper) instead.

Throws:

DataAccessException

fetchOneInto

@Nullable
@Deprecated
<Z extends Record> Z fetchOneInto(Table<Z> table)
                           throws DataAccessException,
                                  MappingException

Deprecated.

- 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

@NotNull
<H extends RecordHandler<? super R>> H fetchNextInto(H handler)
                                              throws DataAccessException

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
<E> E fetchOneInto(Class<? extends E> type)
            throws DataAccessException,
                   MappingException

Deprecated.

- 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
@NotNull Optional<R> fetchOptional()
                            throws DataAccessException

Deprecated.

- 3.10 - [#6363] - Use fetchNextOptional() instead.

Throws:

DataAccessException

fetchOptionalInto

@NotNull
@Deprecated
<E> @NotNull Optional<E> fetchOptionalInto(Class<? extends E> type)
                                    throws DataAccessException,
                                           MappingException

Deprecated.

- 3.10 - [#6363] - Use fetchNextOptionalInto(Class) instead.

Throws:

DataAccessException

MappingException

fetchOptional

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

Deprecated.

- 3.10 - [#6363] - Use fetchNextOptional(RecordMapper) instead.

Throws:

DataAccessException

fetchOptionalInto

@NotNull
@Deprecated
<Z extends Record> @NotNull Optional<Z> fetchOptionalInto(Table<Z> table)
                                                   throws DataAccessException,
                                                          MappingException

Deprecated.

- 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.