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.
Result<R>	fetch()	Fetch all remaining records as a result.
Result<R>	fetch(int number)	Deprecated. - 3.10 - [#6363] - Use fetchNext(int) instead.
<E> 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> List<E>	fetchInto(Class<? extends E> type)	Map resulting records onto a custom type.
<Z extends Record> Result<Z>	fetchInto(Table<Z> table)	Map resulting records onto a custom record.
R	fetchNext()	Fetch the next record from the cursor.
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.
Optional<R>	fetchNextOptional()	Fetch the next record from the cursor.
<E> Optional<E>	fetchNextOptional(RecordMapper<? super R,E> mapper)	Fetch the next record into a custom mapper callback.
<E> Optional<E>	fetchNextOptionalInto(Class<? extends E> type)	Map the next resulting record onto a custom type.
<Z extends Record> 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.
Optional<R>	fetchOptional()	Deprecated. - 3.10 - [#6363] - Use fetchNextOptional() instead.
<E> Optional<E>	fetchOptional(RecordMapper<? super R,E> mapper)	Deprecated. - 3.10 - [#6363] - Use fetchNextOptional(RecordMapper) instead.
<E> Optional<E>	fetchOptionalInto(Class<? extends E> type)	Deprecated. - 3.10 - [#6363] - Use fetchNextOptionalInto(Class) instead.
<Z extends Record> Optional<Z>	fetchOptionalInto(Table<Z> table)	Deprecated. - 3.10 - [#6363] - Use fetchNextOptionalInto(Table) instead.
Field<?>	field(int index)	Get a specific field from this Cursor.
Field<?>	field(String name)	Get a specific field from this Cursor.
<T> Field<T>	field(Field<T> field)	Get a specific field from this Cursor.
Field<?>	field(Name name)	Get a specific qualified field from this Cursor.
Field<?>[]	fields()	Get all fields from this Cursor.
Field<?>[]	fields(int... fieldIndexes)	Get all fields from this Cursor, providing some field indexes.
Field<?>[]	fields(String... fieldNames)	Get all fields from this Cursor, providing some field names.
Field<?>[]	fields(Field<?>... fields)	Get all fields from this Cursor, providing some fields.
Field<?>[]	fields(Name... fieldNames)	Get all fields from this Cursor, providing some field names.
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.
RecordType<R>	recordType()	Get this cursor's row type.
ResultSet	resultSet()	Get the Cursor's underlying ResultSet.
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

RecordType<R> recordType()

Get this cursor's row type.

fieldsRow

Row fieldsRow()

Get this cursor's fields as a Row.

field

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

Field<?> field(String name)

Get a specific field from this Cursor.

See Also:

Row.field(String)

field

Field<?> field(Name name)

Get a specific qualified field from this Cursor.

See Also:

Row.field(Name)

field

Field<?> field(int index)

Get a specific field from this Cursor.

See Also:

Row.field(int)

fields

Field<?>[] fields()

Get all fields from this Cursor.

See Also:

Row.fields()

fields

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

Get all fields from this Cursor, providing some fields.

Returns:

All available fields

See Also:

Row.fields(Field...)

fields

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

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

Returns:

All available fields

See Also:

Row.fields(String...)

fields

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

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

Returns:

All available fields

See Also:

Row.fields(Name...)

fields

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

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

@Deprecated
Result<R> fetch(int number)
         throws DataAccessException

Deprecated.

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

Throws:

DataAccessException

fetchNext

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

<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

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

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

<Z extends Record> 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

@Deprecated
R fetchOne()
    throws DataAccessException

Deprecated.

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

Throws:

DataAccessException

fetchOneInto

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

Deprecated.

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

Throws:

DataAccessException

fetchOne

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

Deprecated.

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

Throws:

DataAccessException

fetchOneInto

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

Deprecated.

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

Throws:

DataAccessException

MappingException

fetchNext

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

<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

@Deprecated
<E> E fetchOneInto(Class<? extends E> type)
            throws DataAccessException,
                   MappingException

Deprecated.

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

Throws:

DataAccessException

MappingException

fetchNextInto

<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

<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

<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

@Deprecated
Optional<R> fetchOptional()
                   throws DataAccessException

Deprecated.

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

Throws:

DataAccessException

fetchOptionalInto

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

Deprecated.

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

Throws:

DataAccessException

MappingException

fetchOptional

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

Deprecated.

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

Throws:

DataAccessException

fetchOptionalInto

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

Deprecated.

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

Throws:

DataAccessException

MappingException

fetchNextOptional

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

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

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

<Z extends Record> 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

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

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.