org.jooq.ResultQuery Maven / Gradle / Ivy
/*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* Other licenses:
* -----------------------------------------------------------------------------
* Commercial licenses for this work are available. These replace the above
* Apache-2.0 license and offer limited warranties, support, maintenance, and
* commercial database integrations.
*
* For more information, please visit: https://www.jooq.org/legal/licensing
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*/
package org.jooq;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.Statement;
import java.util.Collection;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.Set;
import java.util.Spliterator;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.Executor;
import java.util.function.Consumer;
import java.util.stream.Collector;
import java.util.stream.Stream;
import javax.sql.DataSource;
import org.jooq.conf.Settings;
import org.jooq.exception.DataAccessException;
import org.jooq.exception.DataTypeException;
import org.jooq.exception.InvalidResultException;
import org.jooq.exception.MappingException;
import org.jooq.exception.NoDataFoundException;
import org.jooq.exception.TooManyRowsException;
import org.jooq.impl.DefaultRecordMapper;
import org.jetbrains.annotations.Blocking;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* A query that can return results.
*
* jOOQ distinguishes between ordinary {@link Query} types, such as
* {@link Insert}, {@link Update}, {@link Delete}, and any {@link DDLQuery},
* which are meant to produce side effects in a database, and the
* {@link ResultQuery}, which is meant to produce a {@link Result} through
* various means.
*
* The most common way to create a result is by calling {@link #fetch()}, or by
* using the query's {@link #iterator()} method in a foreach loop:
*
*
*
*
* Result<TRecord> result = ctx.select(T.A, T.B).from(T).fetch();
*
* for (TRecord record : ctx.select(T.A, T.B).from(T)) {
* // ...
* }
*
*
*
* Most approaches to fetching results in {@link ResultQuery} (including the
* above), fetch the entire JDBC {@link ResultSet} eagerly into memory, which
* allows for closing the underlying JDBC resources as quickly as possible. Such
* operations are not resourceful, i.e. users do not need to worry about closing
* any resources. None of the many ways of fetching data will affect the SQL
* query projection (SELECT clause). Hence, users must make sure
* not to fetch any unnecessary columns, themselves.
*
* There are, however, some ways of fetching results lazily, and thus in a
* resourceful way. These include:
*
* - {@link ResultQuery#fetchLazy()} and related methods, which produce a
* {@link Cursor} for imperative style consumption of resulting records.
* - {@link ResultQuery#fetchStream()} and related methods, which produce a
* Java {@link Stream} for functional style consumption of resulting
* records.
*
*
* In both cases, it is recommended to explicitly close the underlying resources
* (i.e. JDBC {@link ResultSet}) using try-with-resources:
*
*
*
*
* try (Cursor<TRecord> cursor = ctx.select(T.A, T.B).from(T).fetchLazy()) {
* for (;;) {
* TRecord record = cursor.fetchNext();
* if (record == null)
* break;
*
* // ...
* }
* }
*
* try (Stream<TRecord> stream = ctx.select(T.A, T.B).from(T).fetchStream()) {
* stream.forEach(record -> {
* // ...
* });
* }
*
*
*
* While most instances of {@link ResultQuery} implement {@link Select}, there
* also exist other types of {@link ResultQuery} constructed e.g. from plain SQL
* APIs, such as {@link DSLContext#resultQuery(String)}.
*
*
* @author Lukas Eder
*/
public interface ResultQuery extends Fields, Query, Iterable, Publisher {
/**
* Execute the query and return the generated result.
*
* The result and its contained records are attached to the original
* {@link Configuration} by default. Use {@link Settings#isAttachRecords()}
* to override this behaviour.
*
Lifecycle guarantees
This method completes the whole
* {@link ConnectionProvider} and {@link ExecuteListener} lifecycles,
* eagerly fetching all results into memory. Underlying JDBC
* {@link ResultSet}s are always closed. Underlying JDBC
* {@link PreparedStatement}s are closed, unless
* {@link ResultQuery#keepStatement(boolean)} is set.
*
* In order to keep open {@link ResultSet}s and fetch records lazily, use
* {@link #fetchLazy()} instead and then operate on {@link Cursor}.
*
* This method is not affected by
* {@link Settings#getFetchIntermediateResult()}.
*
* @return The result. This will never be null.
* @throws DataAccessException if something went wrong executing the query
*/
@NotNull
@Blocking
Result fetch() throws DataAccessException;
/**
* Execute the query and return the generated result as a JDBC
* {@link ResultSet}.
*
* This is the same as calling {@link #fetchLazy()}.
* {@link Cursor#resultSet() resultSet()} and will return a
* {@link ResultSet} wrapping the JDBC driver's ResultSet.
* Closing this ResultSet may close the producing
* {@link Statement} or {@link PreparedStatement}, depending on your setting
* for {@link ResultQuery#keepStatement(boolean)}.
*
* You can use this method when you want to use jOOQ for query execution,
* but not for result fetching. The returned ResultSet can also
* be used with {@link DSLContext#fetch(ResultSet)}.
*
* @return The result. This will never be null.
* @throws DataAccessException if something went wrong executing the query
*/
@NotNull
@Blocking
ResultSet fetchResultSet() throws DataAccessException;
/**
* Execute the query using {@link #fetch()} and return the generated result
* as an {@link Iterator}.
*
* {@inheritDoc}
*/
@NotNull
@Override
@Blocking
Iterator iterator() throws DataAccessException;
/**
* Execute the query using {@link #fetch()} and return the generated result
* as an {@link Spliterator}.
*
* {@inheritDoc}
*/
@NotNull
@Override
@Blocking
default Spliterator spliterator() {
return Iterable.super.spliterator();
}
/**
* Execute the query and consume its results.
*
* {@inheritDoc}
*/
@Override
@Blocking
default void forEach(Consumer action) {
Iterable.super.forEach(action);
}
/**
* Stream this query.
*
* This is just a synonym for {@link #stream()}.
*
* Clients should ensure the {@link Stream} is properly closed, e.g. in a
* try-with-resources statement:
*
*
*
*
* try (Stream<R> stream = query.stream()) {
* // Do things with stream
* }
*
*
*
* If users prefer more fluent style streaming of queries, {@link ResultSet}
* can be registered and closed via {@link ExecuteListener}, or via "smart"
* third-party {@link DataSource}s.
*
* Depending on your JDBC driver's default behaviour, this may load the
* whole database result into the driver's memory. In order to indicate to
* the driver that you may not want to fetch all records at once, use
* {@link ResultQuery#fetchSize(int)} or
* {@link Settings#setFetchSize(Integer)} prior to calling this method.
*
* @return The result.
* @throws DataAccessException if something went wrong executing the query
* @see #stream()
*/
@NotNull
@Blocking
Stream fetchStream() throws DataAccessException;
/**
* Stream this query, mapping records into a custom type.
*
* This is the same as calling
* fetchStream().map(r -> r.into(type)). See
* {@link Record#into(Class)} for more details.
*
* Clients should ensure the {@link Stream} is properly closed, e.g. in a
* try-with-resources statement:
*
*
*
*
* try (Stream<R> stream = query.stream()) {
* // Do things with stream
* }
*
*
*
* If users prefer more fluent style streaming of queries, {@link ResultSet}
* can be registered and closed via {@link ExecuteListener}, or via "smart"
* third-party {@link DataSource}s.
*
* Depending on your JDBC driver's default behaviour, this may load the
* whole database result into the driver's memory. In order to indicate to
* the driver that you may not want to fetch all records at once, use
* {@link ResultQuery#fetchSize(int)} or
* {@link Settings#setFetchSize(Integer)} prior to calling this method.
*
* @param The generic entity type.
* @param type The entity type.
* @see Record#into(Class)
* @see Result#into(Class)
* @see DefaultRecordMapper
* @return The results.
* @throws DataAccessException if something went wrong executing the query
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
*/
@NotNull
@Blocking
Stream fetchStreamInto(Class type) throws DataAccessException, MappingException;
/**
* Stream this query, mapping records into a custom record.
*
* This is the same as calling
* fetchStream().map(r -> r.into(table)). See
* {@link Record#into(Table)} for more details.
*
* The result and its contained records are attached to the original
* {@link Configuration} by default. Use {@link Settings#isAttachRecords()}
* to override this behaviour.
*
* Clients should ensure the {@link Stream} is properly closed, e.g. in a
* try-with-resources statement:
*
*
*
*
* try (Stream<R> stream = query.stream()) {
* // Do things with stream
* }
*
*
*
* If users prefer more fluent style streaming of queries, {@link ResultSet}
* can be registered and closed via {@link ExecuteListener}, or via "smart"
* third-party {@link DataSource}s.
*
* Depending on your JDBC driver's default behaviour, this may load the
* whole database result into the driver's memory. In order to indicate to
* the driver that you may not want to fetch all records at once, use
* {@link ResultQuery#fetchSize(int)} or
* {@link Settings#setFetchSize(Integer)} prior to calling this method.
*
* @param The generic table record type.
* @param table The table type.
* @return The results. This will never be null.
* @see Record#into(Table)
* @see Result#into(Table)
* @throws DataAccessException if something went wrong executing the query
*/
@NotNull
@Blocking
Stream fetchStreamInto(Table table) throws DataAccessException;
/**
* Stream this query.
*
* This is essentially the same as {@link #fetchLazy()} but instead of
* returning a {@link Cursor}, a Java 8 {@link Stream} is returned. Clients
* should ensure the {@link Stream} is properly closed, e.g. in a
* try-with-resources statement:
*
*
*
*
* try (Stream<R> stream = query.stream()) {
* // Do things with stream
* }
*
*
*
* If users prefer more fluent style streaming of queries, {@link ResultSet}
* can be registered and closed via {@link ExecuteListener}, or via "smart"
* third-party {@link DataSource}s.
*
* Depending on your JDBC driver's default behaviour, this may load the
* whole database result into the driver's memory. In order to indicate to
* the driver that you may not want to fetch all records at once, use
* {@link ResultQuery#fetchSize(int)} or
* {@link Settings#setFetchSize(Integer)} prior to calling this method.
*
* @return The result.
* @throws DataAccessException if something went wrong executing the query
*/
@NotNull
@Blocking
Stream stream() throws DataAccessException;
/**
* Reduce the execution results of this query using a {@link Collector}.
*
* This works in the same way as calling the following code:
*
*
*
* try (Stream<R> stream = resultQuery.stream()) {
* X result = stream.collect(collector);
* }
*
*
*
* ... with the exception of allowing client code to ignore the need for
* managing resources, which are handled inside of the
* collect() method.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* @param collector The collector that collects all records and accumulates
* them into a result type.
* @return The result of the collection.
* @throws DataAccessException if something went wrong executing the query
*/
@Blocking
X collect(Collector collector) throws DataAccessException;
/**
* Execute the query and "lazily" return the generated result.
*
* The returned {@link Cursor} holds a reference to the executed
* {@link PreparedStatement} and the associated {@link ResultSet}. Data can
* be fetched (or iterated over) lazily, fetching records from the
* {@link ResultSet} one by one.
*
* Depending on your JDBC driver's default behaviour, this may load the
* whole database result into the driver's memory. In order to indicate to
* the driver that you may not want to fetch all records at once, use
* {@link ResultQuery#fetchSize(int)} or
* {@link Settings#setFetchSize(Integer)} prior to calling this method.
*
* Client code is responsible for closing the cursor after use.
*
* @return The resulting cursor. This will never be null.
* @throws DataAccessException if something went wrong executing the query
* @see ResultQuery#fetchSize(int)
*/
@NotNull
@Blocking
Cursor fetchLazy() throws DataAccessException;
/**
* Execute a query, possibly returning several result sets.
*
* Example (Sybase ASE):
*
*
*
*
* String sql = "sp_help 'my_table'";
*
*
* The result and its contained records are attached to the original
* {@link Configuration} by default. Use {@link Settings#isAttachRecords()}
* to override this behaviour.
*
* @return The resulting records. This will never be null.
* @throws DataAccessException if something went wrong executing the query
*/
@NotNull
@Blocking
Results fetchMany() throws DataAccessException;
/**
* Execute the query and return all values for a field from the generated
* result, using {@link #field(Field)} for lookup.
*
* This is the same as calling {@link #fetch()} and then
* {@link Result#getValues(Field)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* If the argument {@link Field} is the same as the one you've provided to
* {@link DSLContext#select(SelectField)}, then you could also just call
* {@link #collect(Collector)} with {@link Records#intoList()}.
*
* @return The result. This will never be null.
* @throws DataAccessException if something went wrong executing the query
*/
@NotNull
@Blocking
List fetch(Field field) throws DataAccessException;
/**
* Execute the query and return all values for a field from the generated
* result, using {@link #field(Field)} for lookup.
*
* This is the same as calling {@link #fetch()} and then
* {@link Result#getValues(Field, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* @return The result. This will never be null.
* @throws DataAccessException if something went wrong executing the query
* @see Record#get(Field, Class)
*/
@NotNull
@Blocking
List fetch(Field field, Class type) throws DataAccessException;
/**
* Execute the query and return all values for a field from the generated
* result, using {@link #field(Field)} for lookup.
*
* This is the same as calling {@link #fetch()} and then
* {@link Result#getValues(Field, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* @return The result. This will never be null.
* @throws DataAccessException if something went wrong executing the query
* @see Record#get(Field, Converter)
*/
@NotNull
@Blocking
List fetch(Field field, Converter converter) throws DataAccessException;
/**
* Execute the query and return all values for a field index from the
* generated result.
*
* This is the same as calling {@link #fetch()} and then
* {@link Result#getValues(int)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* @return The result. This will never be null.
* @throws DataAccessException if something went wrong executing the query
*/
@NotNull
@Blocking
List fetch(int fieldIndex) throws DataAccessException;
/**
* Execute the query and return all values for a field index from the
* generated result.
*
* This is the same as calling {@link #fetch()} and then
* {@link Result#getValues(int, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* @return The result. This will never be null.
* @throws DataAccessException if something went wrong executing the query
* @see Record#get(int, Class)
*/
@NotNull
@Blocking
List fetch(int fieldIndex, Class type) throws DataAccessException;
/**
* Execute the query and return all values for a field index from the
* generated result.
*
* This is the same as calling {@link #fetch()} and then
* {@link Result#getValues(int, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* @return The result. This will never be null.
* @throws DataAccessException if something went wrong executing the query
* @see Record#get(int, Converter)
*/
@NotNull
@Blocking
List fetch(int fieldIndex, Converter converter) throws DataAccessException;
/**
* Execute the query and return all values for a field name from the
* generated result, using {@link #field(String)} for lookup.
*
* This is the same as calling {@link #fetch()} and then
* {@link Result#getValues(String)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* @return The result. This will never be null.
* @throws DataAccessException if something went wrong executing the query
*/
@NotNull
@Blocking
List fetch(String fieldName) throws DataAccessException;
/**
* Execute the query and return all values for a field name from the
* generated result, using {@link #field(String)} for lookup.
*
* This is the same as calling {@link #fetch()} and then
* {@link Result#getValues(String, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* @return The result. This will never be null.
* @throws DataAccessException if something went wrong executing the query
* @see Record#get(String, Class)
*/
@NotNull
@Blocking
List fetch(String fieldName, Class type) throws DataAccessException;
/**
* Execute the query and return all values for a field name from the
* generated result, using {@link #field(String)} for lookup.
*
* This is the same as calling {@link #fetch()} and then
* {@link Result#getValues(String, Converter)}. As such, the query
* projection (SELECT clause) is not affected. Make sure not to
* fetch any unnecessary data.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* @return The result. This will never be null.
* @throws DataAccessException if something went wrong executing the query
* @see Record#get(String, Converter)
*/
@NotNull
@Blocking
List fetch(String fieldName, Converter converter) throws DataAccessException;
/**
* Execute the query and return all values for a field name from the
* generated result, using {@link #field(Name)} for lookup.
*
* This is the same as calling {@link #fetch()} and then
* {@link Result#getValues(Name)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* @return The result. This will never be null.
* @throws DataAccessException if something went wrong executing the query
*/
@NotNull
@Blocking
List fetch(Name fieldName) throws DataAccessException;
/**
* Execute the query and return all values for a field name from the
* generated result, using {@link #field(Name)} for lookup.
*
* This is the same as calling {@link #fetch()} and then
* {@link Result#getValues(Name, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* @return The result. This will never be null.
* @throws DataAccessException if something went wrong executing the query
* @see Record#get(Name, Class)
*/
@NotNull
@Blocking
List fetch(Name fieldName, Class type) throws DataAccessException;
/**
* Execute the query and return all values for a field name from the
* generated result, using {@link #field(Name)} for lookup.
*
* This is the same as calling {@link #fetch()} and then
* {@link Result#getValues(Name, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* @return The result. This will never be null.
* @throws DataAccessException if something went wrong executing the query
* @see Record#get(Name, Converter)
*/
@NotNull
@Blocking
List fetch(Name fieldName, Converter converter) throws DataAccessException;
/**
* Execute the query and return at most one resulting value for a field from
* the generated result, using {@link #field(Field)} for lookup.
*
* This is the same as calling {@link #fetchOne()} and then
* {@link Record#get(Field)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
T fetchOne(Field field) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field from
* the generated result, using {@link #field(Field)} for lookup.
*
* This is the same as calling {@link #fetchOne()} and then
* {@link Record#get(Field, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchOne(Field field, Class type) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field from
* the generated result, using {@link #field(Field)} for lookup.
*
* This is the same as calling {@link #fetchOne()} and then
* {@link Record#get(Field, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchOne(Field field, Converter converter)
throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field
* index from the generated result.
*
* This is the same as calling {@link #fetchOne()} and then
* {@link Record#get(int)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
Object fetchOne(int fieldIndex) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field
* index from the generated result.
*
* This is the same as calling {@link #fetchOne()} and then
* {@link Record#get(int, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchOne(int fieldIndex, Class type) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field
* index from the generated result.
*
* This is the same as calling {@link #fetchOne()} and then
* {@link Record#get(int, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchOne(int fieldIndex, Converter converter)
throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(String)} for lookup.
*
* This is the same as calling {@link #fetchOne()} and then
* {@link Record#get(String)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
Object fetchOne(String fieldName) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(String)} for lookup.
*
* This is the same as calling {@link #fetchOne()} and then
* {@link Record#get(String, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchOne(String fieldName, Class type) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(String)} for lookup.
*
* This is the same as calling {@link #fetchOne()} and then
* {@link Record#get(String, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchOne(String fieldName, Converter converter)
throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(Name)} for lookup.
*
* This is the same as calling {@link #fetchOne()} and then
* {@link Record#get(Name)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
Object fetchOne(Name fieldName) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(Name)} for lookup.
*
* This is the same as calling {@link #fetchOne()} and then
* {@link Record#get(Name, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchOne(Name fieldName, Class type) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(Name)} for lookup.
*
* This is the same as calling {@link #fetchOne()} and then
* {@link Record#get(Name, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchOne(Name fieldName, Converter converter)
throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting record.
*
* The resulting record is attached to the original {@link Configuration} by
* default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* @return The resulting record or null if the query returns no
* records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
R fetchOne() throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value into a custom
* mapper callback.
*
* @return The custom mapped record or null if the query
* returned no records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
E fetchOne(RecordMapper mapper) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting record as a name/value
* map.
*
* @return The resulting record or null if the query returns no
* records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
* @see Result#intoMaps()
* @see Record#intoMap()
*/
@Nullable
@Blocking
Map fetchOneMap() throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting record as an array
*
* You can access data like this
*
*
* query.fetchOneArray()[fieldIndex]
*
*
* @return The resulting record or null if the query returns no
* records.
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
Object @Nullable [] fetchOneArray() throws DataAccessException, TooManyRowsException;
/**
* Map resulting records onto a custom type.
*
* This is the same as calling
*
*
*
* E result = null;
* Record r = q.fetchOne();
*
* if (r != null)
* result = r.into(type);
*
*
*
* . See {@link Record#into(Class)} for more details
*
* @param The generic entity type.
* @param type The entity type.
* @return The resulting record or null if the query returns no
* records.
* @see Record#into(Class)
* @see Result#into(Class)
* @throws DataAccessException if something went wrong executing the query
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @throws TooManyRowsException if the query returned more than one record
* @see DefaultRecordMapper
*/
@Nullable
@Blocking
E fetchOneInto(Class type) throws DataAccessException, MappingException, TooManyRowsException;
/**
* Map resulting records onto a custom record.
*
* This is the same as calling
*
*
*
* Z result = null;
* Record r = q.fetchOne();
*
* if (r != null)
* result = r.into(table);
*
*
*
* . See {@link Record#into(Table)} for more details
*
* The resulting record is attached to the original {@link Configuration} by
* default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* @param The generic table record type.
* @param table The table type.
* @return The resulting record or null if the query returns no
* records.
* @see Record#into(Table)
* @see Result#into(Table)
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
Z fetchOneInto(Table table) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting value for a field from
* the generated result, using {@link #field(Field)} for lookup.
*
* This is the same as calling {@link #fetchSingle()} and then
* {@link Record#get(Field)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value. Unlike other {@link #fetchSingle()} methods,
* which never produce null records, this can be null
* if the resulting value in the record is null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
T fetchSingle(Field field) throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting value for a field from
* the generated result, using {@link #field(Field)} for lookup.
*
* This is the same as calling {@link #fetchSingle()} and then
* {@link Record#get(Field, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value. Unlike other {@link #fetchSingle()} methods,
* which never produce null records, this can be null
* if the resulting value in the record is null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchSingle(Field field, Class type)
throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting value for a field from
* the generated result, using {@link #field(Field)} for lookup.
*
* This is the same as calling {@link #fetchSingle()} and then
* {@link Record#get(Field, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value. Unlike other {@link #fetchSingle()} methods,
* which never produce null records, this can be null
* if the resulting value in the record is null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchSingle(Field field, Converter converter)
throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting value for a field
* index from the generated result.
*
* This is the same as calling {@link #fetchSingle()} and then
* {@link Record#get(int)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value. Unlike other {@link #fetchSingle()} methods,
* which never produce null records, this can be null
* if the resulting value in the record is null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
Object fetchSingle(int fieldIndex) throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting value for a field
* index from the generated result.
*
* This is the same as calling {@link #fetchSingle()} and then
* {@link Record#get(int, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value. Unlike other {@link #fetchSingle()} methods,
* which never produce null records, this can be null
* if the resulting value in the record is null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchSingle(int fieldIndex, Class type)
throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting value for a field
* index from the generated result.
*
* This is the same as calling {@link #fetchSingle()} and then
* {@link Record#get(int, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value. Unlike other {@link #fetchSingle()} methods,
* which never produce null records, this can be null
* if the resulting value in the record is null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchSingle(int fieldIndex, Converter converter)
throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting value for a field name
* from the generated result, using {@link #field(String)} for lookup.
*
* This is the same as calling {@link #fetchSingle()} and then
* {@link Record#get(String)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value. Unlike other {@link #fetchSingle()} methods,
* which never produce null records, this can be null
* if the resulting value in the record is null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
Object fetchSingle(String fieldName) throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting value for a field name
* from the generated result, using {@link #field(String)} for lookup.
*
* This is the same as calling {@link #fetchSingle()} and then
* {@link Record#get(String, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value. Unlike other {@link #fetchSingle()} methods,
* which never produce null records, this can be null
* if the resulting value in the record is null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchSingle(String fieldName, Class type)
throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting value for a field name
* from the generated result, using {@link #field(String)} for lookup.
*
* This is the same as calling {@link #fetchSingle()} and then
* {@link Record#get(String, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value. Unlike other {@link #fetchSingle()} methods,
* which never produce null records, this can be null
* if the resulting value in the record is null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchSingle(String fieldName, Converter converter)
throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting value for a field name
* from the generated result, using {@link #field(Name)} for lookup.
*
* This is the same as calling {@link #fetchSingle()} and then
* {@link Record#get(Name)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value. Unlike other {@link #fetchSingle()} methods,
* which never produce null records, this can be null
* if the resulting value in the record is null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
Object fetchSingle(Name fieldName) throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting value for a field name
* from the generated result, using {@link #field(Name)} for lookup.
*
* This is the same as calling {@link #fetchSingle()} and then
* {@link Record#get(Name, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value. Unlike other {@link #fetchSingle()} methods,
* which never produce null records, this can be null
* if the resulting value in the record is null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchSingle(Name fieldName, Class type)
throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting value for a field name
* from the generated result, using {@link #field(Name)} for lookup.
*
* This is the same as calling {@link #fetchSingle()} and then
* {@link Record#get(Name, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value. Unlike other {@link #fetchSingle()} methods,
* which never produce null records, this can be null
* if the resulting value in the record is null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
U fetchSingle(Name fieldName, Converter converter)
throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting record.
*
* The resulting record is attached to the original {@link Configuration} by
* default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* @return The resulting value. This is never null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
R fetchSingle() throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting value into a custom
* mapper callback.
*
* @return The resulting value. This is never null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
E fetchSingle(RecordMapper mapper)
throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting record as a name/value
* map.
*
* @return The resulting value. This is never null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
* @see Result#intoMaps()
* @see Record#intoMap()
*/
@NotNull
@Blocking
Map fetchSingleMap() throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return exactly one resulting record as an array
*
* You can access data like this
*
*
* query.fetchSingleArray()[fieldIndex]
*
*
* @return The resulting value. This is never null.
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@Nullable
@Blocking
Object @NotNull [] fetchSingleArray() throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Map resulting records onto a custom type.
*
* This is the same as calling
*
*
*
* E result = null;
* Record r = q.fetchSingle();
*
* if (r != null)
* result = r.into(type);
*
*
*
* . See {@link Record#into(Class)} for more details
*
* @param The generic entity type.
* @param type The entity type.
* @return The resulting value.
* @see Record#into(Class)
* @see Result#into(Class)
* @throws DataAccessException if something went wrong executing the query
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
* @see DefaultRecordMapper
*/
@Blocking
// [#10774] This is @Nullable in rare cases, which can be annoying for
// Kotlin users in most cases
E fetchSingleInto(Class type)
throws DataAccessException, MappingException, NoDataFoundException, TooManyRowsException;
/**
* Map resulting records onto a custom record.
*
* This is the same as calling
*
*
*
* Z result = null;
* Record r = q.fetchSingle();
*
* if (r != null)
* result = r.into(table);
*
*
*
* . See {@link Record#into(Table)} for more details
*
* The resulting record is attached to the original {@link Configuration} by
* default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* @param The generic table record type.
* @param table The table type.
* @return The resulting value. This is never null.
* @see Record#into(Table)
* @see Result#into(Table)
* @throws DataAccessException if something went wrong executing the query
* @throws NoDataFoundException if the query returned no records
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Z fetchSingleInto(Table table)
throws DataAccessException, NoDataFoundException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field from
* the generated result, using {@link #field(Field)} for lookup.
*
* This is the same as calling {@link #fetchOptional()} and then
* {@link Record#get(Field)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptional(Field field) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field from
* the generated result, using {@link #field(Field)} for lookup.
*
* This is the same as calling {@link #fetchOptional()} and then
* {@link Record#get(Field, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptional(Field field, Class type)
throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field from
* the generated result, using {@link #field(Field)} for lookup.
*
* This is the same as calling {@link #fetchOptional()} and then
* {@link Record#get(Field, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptional(Field field, Converter converter)
throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field
* index from the generated result.
*
* This is the same as calling {@link #fetchOptional()} and then
* {@link Record#get(int)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptional(int fieldIndex) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field
* index from the generated result.
*
* This is the same as calling {@link #fetchOptional()} and then
* {@link Record#get(int, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptional(int fieldIndex, Class type)
throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field
* index from the generated result.
*
* This is the same as calling {@link #fetchOptional()} and then
* {@link Record#get(int, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptional(int fieldIndex, Converter converter)
throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(String)} for lookup.
*
* This is the same as calling {@link #fetchOptional()} and then
* {@link Record#get(String)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptional(String fieldName) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(String)} for lookup.
*
* This is the same as calling {@link #fetchOptional()} and then
* {@link Record#get(String, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptional(String fieldName, Class type)
throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(String)} for lookup.
*
* This is the same as calling {@link #fetchOptional()} and then
* {@link Record#get(String, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptional(String fieldName, Converter converter)
throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(Name)} for lookup.
*
* This is the same as calling {@link #fetchOptional()} and then
* {@link Record#get(Name)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptional(Name fieldName) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(Name)} for lookup.
*
* This is the same as calling {@link #fetchOptional()} and then
* {@link Record#get(Name, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptional(Name fieldName, Class type)
throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(Name)} for lookup.
*
* This is the same as calling {@link #fetchOptional()} and then
* {@link Record#get(Name, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptional(Name fieldName, Converter converter)
throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting record.
*
* The resulting record is attached to the original {@link Configuration} by
* default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* @return The resulting record
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptional() throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value into a custom
* mapper callback.
*
* @return The custom mapped record
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptional(RecordMapper mapper) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting record as a name/value
* map.
*
* @return The resulting record
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
* @see Result#intoMaps()
* @see Record#intoMap()
*/
@NotNull
@Blocking
Optional> fetchOptionalMap() throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting record as an array.
*
* @return The resulting record
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptionalArray() throws DataAccessException, TooManyRowsException;
/**
* Map resulting records onto a custom type.
*
* This is the same as calling
*
*
*
* Optional<E> result = q.fetchOptional().map(r -> r.into(type));
*
*
*
* . See {@link Record#into(Class)} for more details
*
* @param The generic entity type.
* @param type The entity type.
* @return The resulting record
* @see Record#into(Class)
* @see Result#into(Class)
* @throws DataAccessException if something went wrong executing the query
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @throws TooManyRowsException if the query returned more than one record
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Optional fetchOptionalInto(Class type)
throws DataAccessException, MappingException, TooManyRowsException;
/**
* Map resulting records onto a custom record.
*
* This is the same as calling
*
*
*
* Optional<Z> result = q.fetchOptional().map(r -> r.into(table));
*
*
*
* . See {@link Record#into(Table)} for more details
*
* The resulting record is attached to the original {@link Configuration} by
* default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* @param The generic table record type.
* @param table The table type.
* @return The resulting record
* @see Record#into(Table)
* @see Result#into(Table)
* @throws DataAccessException if something went wrong executing the query
* @throws TooManyRowsException if the query returned more than one record
*/
@NotNull
@Blocking
Optional fetchOptionalInto(Table table) throws DataAccessException, TooManyRowsException;
/**
* Execute the query and return at most one resulting value for a field from
* the generated result, using {@link #field(Field)} for lookup.
*
* This is the same as calling {@link #fetchAny()} and then
* {@link Record#get(Field)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
T fetchAny(Field field) throws DataAccessException;
/**
* Execute the query and return at most one resulting value for a field from
* the generated result, using {@link #field(Field)} for lookup.
*
* This is the same as calling {@link #fetchAny()} and then
* {@link Record#get(Field, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
U fetchAny(Field field, Class type) throws DataAccessException;
/**
* Execute the query and return at most one resulting value for a field from
* the generated result, using {@link #field(Field)} for lookup.
*
* This is the same as calling {@link #fetchAny()} and then
* {@link Record#get(Field, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
U fetchAny(Field field, Converter converter) throws DataAccessException;
/**
* Execute the query and return at most one resulting value for a field
* index from the generated result.
*
* This is the same as calling {@link #fetchAny()} and then
* {@link Record#get(int)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
Object fetchAny(int fieldIndex) throws DataAccessException;
/**
* Execute the query and return at most one resulting value for a field
* index from the generated result.
*
* This is the same as calling {@link #fetchAny()} and then
* {@link Record#get(int, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
U fetchAny(int fieldIndex, Class type) throws DataAccessException;
/**
* Execute the query and return at most one resulting value for a field
* index from the generated result.
*
* This is the same as calling {@link #fetchAny()} and then
* {@link Record#get(int, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
U fetchAny(int fieldIndex, Converter converter) throws DataAccessException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(String)} for lookup.
*
* This is the same as calling {@link #fetchAny()} and then
* {@link Record#get(String)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
Object fetchAny(String fieldName) throws DataAccessException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(String)} for lookup.
*
* This is the same as calling {@link #fetchAny()} and then
* {@link Record#get(String, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
U fetchAny(String fieldName, Class type) throws DataAccessException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(String)} for lookup.
*
* This is the same as calling {@link #fetchAny()} and then
* {@link Record#get(String, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
U fetchAny(String fieldName, Converter converter) throws DataAccessException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(Name)} for lookup.
*
* This is the same as calling {@link #fetchAny()} and then
* {@link Record#get(Name)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
Object fetchAny(Name fieldName) throws DataAccessException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(Name)} for lookup.
*
* This is the same as calling {@link #fetchAny()} and then
* {@link Record#get(Name, Class)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* The {@link Converter} that is provided by
* {@link Configuration#converterProvider()} will be used to convert the
* value to U
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
U fetchAny(Name fieldName, Class type) throws DataAccessException;
/**
* Execute the query and return at most one resulting value for a field name
* from the generated result, using {@link #field(Name)} for lookup.
*
* This is the same as calling {@link #fetchAny()} and then
* {@link Record#get(Name, Converter)}. As such, the query projection
* (SELECT clause) is not affected. Make sure not to fetch any
* unnecessary data.
*
* @return The resulting value or null if the query returned no
* records.
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
U fetchAny(Name fieldName, Converter converter) throws DataAccessException;
/**
* Execute the query and return at most one resulting record.
*
* The resulting record is attached to the original {@link Configuration} by
* default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* @return The first resulting record or null if the query
* returns no records.
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
R fetchAny() throws DataAccessException;
/**
* Execute the query and return at most one resulting record.
*
* The resulting record is attached to the original {@link Configuration} by
* default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* @return The first resulting record or null if the query
* returns no records.
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
E fetchAny(RecordMapper mapper) throws DataAccessException;
/**
* Execute the query and return at most one resulting record as a name/value
* map.
*
* @return The resulting record or null if the query returns no
* records.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoMaps()
* @see Record#intoMap()
*/
@Nullable
@Blocking
Map fetchAnyMap() throws DataAccessException;
/**
* Execute the query and return at most one resulting record as an array
*
* You can access data like this
*
*
* query.fetchAnyArray()[fieldIndex]
*
*
* @return The resulting record or null if the query returns no
* records.
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
Object @Nullable [] fetchAnyArray() throws DataAccessException;
/**
* Map resulting records onto a custom type.
*
* This is the same as calling
*
*
*
* E result = null;
* Record r = q.fetchAny();
*
* if (r != null)
* result = r.into(type);
*
*
*
* . See {@link Record#into(Class)} for more details
*
* @param The generic entity type.
* @param type The entity type.
* @return The resulting record or null if the query returns no
* records.
* @see Record#into(Class)
* @see Result#into(Class)
* @throws DataAccessException if something went wrong executing the query
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @see DefaultRecordMapper
*/
@Nullable
@Blocking
E fetchAnyInto(Class type) throws DataAccessException, MappingException;
/**
* Map resulting records onto a custom record.
*
* This is the same as calling
*
*
*
* Z result = null;
* Record r = q.fetchOne();
*
* if (r != null)
* result = r.into(table);
*
*
*
* . See {@link Record#into(Table)} for more details
*
* The resulting record is attached to the original {@link Configuration} by
* default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* @param The generic table record type.
* @param table The table type.
* @return The resulting record or null if the query returns no
* records.
* @see Record#into(Table)
* @see Result#into(Table)
* @throws DataAccessException if something went wrong executing the query
*/
@Nullable
@Blocking
Z fetchAnyInto(Table table) throws DataAccessException;
/**
* Execute the query and return the generated result as a list of name/value
* maps.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* @return The result. This will never be null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key field returned two or more
* equal values from the result set.
* @see Result#intoMaps()
* @see Record#intoMap()
*/
@NotNull
@Blocking
List> fetchMaps() throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and the corresponding records as value, using
* {@link #field(Field)} for lookup.
*
* An exception is thrown, if the key turns out to be non-unique in the
* result set. Use {@link #fetchGroups(Field)} instead, if your keys are
* non-unique
*
* The resulting records are attached to the original {@link Configuration}
* by default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param The key's generic field type
* @param key The key field. Client code must assure that this field is
* unique in the result set.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key field returned two or more
* equal values from the result set.
* @see Result#intoMap(Field)
*/
@NotNull
@Blocking
Map fetchMap(Field key) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and the corresponding records as value.
*
* An exception is thrown, if the key turns out to be non-unique in the
* result set. Use {@link #fetchGroups(int)} instead, if your keys are
* non-unique
*
* The resulting records are attached to the original {@link Configuration}
* by default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldIndex The key field. Client code must assure that this
* field is unique in the result set.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key field returned two or more
* equal values from the result set.
* @see Result#intoMap(int)
*/
@NotNull
@Blocking
Map fetchMap(int keyFieldIndex) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and the corresponding records as value, using
* {@link #field(String)} for lookup.
*
* An exception is thrown, if the key turns out to be non-unique in the
* result set. Use {@link #fetchGroups(String)} instead, if your keys are
* non-unique
*
* The resulting records are attached to the original {@link Configuration}
* by default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldName The key field. Client code must assure that this
* field is unique in the result set.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key field returned two or more
* equal values from the result set.
* @see Result#intoMap(String)
*/
@NotNull
@Blocking
Map fetchMap(String keyFieldName) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and the corresponding records as value, using
* {@link #field(Name)} for lookup.
*
* An exception is thrown, if the key turns out to be non-unique in the
* result set. Use {@link #fetchGroups(Name)} instead, if your keys are
* non-unique
*
* The resulting records are attached to the original {@link Configuration}
* by default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldName The key field. Client code must assure that this
* field is unique in the result set.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key field returned two or more
* equal values from the result set.
* @see Result#intoMap(Name)
*/
@NotNull
@Blocking
Map fetchMap(Name keyFieldName) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and another one of the result's columns as value, using
* {@link #field(Field)} for lookup.
*
* An exception is thrown, if the key turns out to be non-unique in the
* result set. Use {@link #fetchGroups(Field, Field)} instead, if your keys
* are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* If the argument {@link Field}s are the same as the ones you've provided
* to {@link DSLContext#select(SelectField, SelectField)}, then you could
* also just call {@link #collect(Collector)} with
* {@link Records#intoMap()}.
*
* @param The key's generic field type
* @param The value's generic field type
* @param key The key field. Client code must assure that this field is
* unique in the result set.
* @param value The value field
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key field returned two or more
* equal values from the result set.
* @see Result#intoMap(Field, Field)
*/
@NotNull
@Blocking
Map fetchMap(Field key, Field value) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and another one of the result's columns as value.
*
* An exception is thrown, if the key turns out to be non-unique in the
* result set. Use {@link #fetchGroups(int, int)} instead, if your keys are
* non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldIndex The key field. Client code must assure that this
* field is unique in the result set.
* @param valueFieldIndex The value field
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key field returned two or more
* equal values from the result set.
* @see Result#intoMap(int, int)
*/
@NotNull
@Blocking
Map fetchMap(int keyFieldIndex, int valueFieldIndex) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and another one of the result's columns as value, using
* {@link #field(String)} for lookup.
*
* An exception is thrown, if the key turns out to be non-unique in the
* result set. Use {@link #fetchGroups(String, String)} instead, if your
* keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldName The key field. Client code must assure that this
* field is unique in the result set.
* @param valueFieldName The value field
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key field returned two or more
* equal values from the result set.
* @see Result#intoMap(String, String)
*/
@NotNull
@Blocking
Map fetchMap(String keyFieldName, String valueFieldName) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and another one of the result's columns as value, using
* {@link #field(Name)} for lookup.
*
* An exception is thrown, if the key turns out to be non-unique in the
* result set. Use {@link #fetchGroups(Name, Name)} instead, if your keys
* are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldName The key field. Client code must assure that this
* field is unique in the result set.
* @param valueFieldName The value field
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key field returned two or more
* equal values from the result set.
* @see Result#intoMap(Name, Name)
*/
@NotNull
@Blocking
Map fetchMap(Name keyFieldName, Name valueFieldName) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with keys as a map key and the
* corresponding record as value, using {@link #field(Field)} for lookup.
*
* An exception is thrown, if the keys turn out to be non-unique in the
* result set. Use {@link #fetchGroups(Field[])} instead, if your keys are
* non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keys The keys. Client code must assure that keys are unique in the
* result set.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(Field[])
*/
@NotNull
@Blocking
Map fetchMap(Field[] keys) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with keys as a map key and the
* corresponding record as value.
*
* An exception is thrown, if the keys turn out to be non-unique in the
* result set. Use {@link #fetchGroups(int[])} instead, if your keys are
* non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldIndexes The keys. Client code must assure that keys are
* unique in the result set.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(int[])
*/
@NotNull
@Blocking
Map fetchMap(int[] keyFieldIndexes) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with keys as a map key and the
* corresponding record as value, using {@link #field(String)} for lookup.
*
* An exception is thrown, if the keys turn out to be non-unique in the
* result set. Use {@link #fetchGroups(String[])} instead, if your keys are
* non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldNames The keys. Client code must assure that keys are
* unique in the result set.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(String[])
*/
@NotNull
@Blocking
Map fetchMap(String[] keyFieldNames) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with keys as a map key and the
* corresponding record as value, using {@link #field(Name)} for lookup.
*
* An exception is thrown, if the keys turn out to be non-unique in the
* result set. Use {@link #fetchGroups(Name[])} instead, if your keys are
* non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldNames The keys. Client code must assure that keys are
* unique in the result set.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(Name[])
*/
@NotNull
@Blocking
Map fetchMap(Name[] keyFieldNames) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with keys as a map key and the
* corresponding record as value, using {@link #field(Field)} for lookup.
*
* An exception is thrown, if the keys turn out to be non-unique in the
* result set. Use {@link #fetchGroups(Field[], Field[])} instead, if your
* keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keys The keys. Client code must assure that keys are unique in the
* result set.
* @param values The values.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(Field[], Field[])
*/
@NotNull
@Blocking
Map fetchMap(Field[] keys, Field[] values) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with keys as a map key and the
* corresponding record as value.
*
* An exception is thrown, if the keys turn out to be non-unique in the
* result set. Use {@link #fetchGroups(int[], int[])} instead, if your keys
* are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldIndexes The keys. Client code must assure that keys are
* unique in the result set.
* @param valueFieldIndexes The values.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(int[], int[])
*/
@NotNull
@Blocking
Map fetchMap(int[] keyFieldIndexes, int[] valueFieldIndexes) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with keys as a map key and the
* corresponding record as value, using {@link #field(String)} for lookup.
*
* An exception is thrown, if the keys turn out to be non-unique in the
* result set. Use {@link #fetchGroups(String[], String[])} instead, if your
* keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldNames The keys. Client code must assure that keys are
* unique in the result set.
* @param valueFieldNames The values.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(String[], String[])
*/
@NotNull
@Blocking
Map fetchMap(String[] keyFieldNames, String[] valueFieldNames) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with keys as a map key and the
* corresponding record as value, using {@link #field(Name)} for lookup.
*
* An exception is thrown, if the keys turn out to be non-unique in the
* result set. Use {@link #fetchGroups(Name[], Name[])} instead, if your
* keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldNames The keys. Client code must assure that keys are
* unique in the result set.
* @param valueFieldNames The values.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(Name[], Name[])
*/
@NotNull
@Blocking
Map fetchMap(Name[] keyFieldNames, Name[] valueFieldNames) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given keys and mapped into the given entity type, using
* {@link #field(Field)} for lookup.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(Field[], Class)} instead, if
* your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keys The keys. Client code must assure that keys are unique in the
* result set. If this is null or an empty array,
* the resulting map will contain at most one entry.
* @param type The entity type.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the keys are non-unique in the result
* set.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @see Result#intoMap(Field[], Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map, E> fetchMap(Field[] keys, Class type) throws DataAccessException, MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given keys and mapped into the given entity type.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(int[], Class)} instead, if
* your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldIndexes The keys. Client code must assure that keys are
* unique in the result set. If this is null or an
* empty array, the resulting map will contain at most one entry.
* @param type The entity type.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the keys are non-unique in the result
* set.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @see Result#intoMap(int[], Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map, E> fetchMap(int[] keyFieldIndexes, Class type)
throws DataAccessException, MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given keys and mapped into the given entity type, using
* {@link #field(String)} for lookup.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(String[], Class)} instead, if
* your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldNames The keys. Client code must assure that keys are
* unique in the result set. If this is null or an
* empty array, the resulting map will contain at most one entry.
* @param type The entity type.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the keys are non-unique in the result
* set.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @see Result#intoMap(String[], Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map, E> fetchMap(String[] keyFieldNames, Class type)
throws DataAccessException, MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given keys and mapped into the given entity type, using
* {@link #field(Name)} for lookup.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(Name[], Class)} instead, if
* your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldNames The keys. Client code must assure that keys are
* unique in the result set. If this is null or an
* empty array, the resulting map will contain at most one entry.
* @param type The entity type.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the keys are non-unique in the result
* set.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @see Result#intoMap(Name[], Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map, E> fetchMap(Name[] keyFieldNames, Class type)
throws DataAccessException, MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given keys and mapped by the given mapper, using {@link #field(Field)}
* for lookup.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(Field[], RecordMapper)}
* instead, if your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keys The keys. Client code must assure that keys are unique in the
* result set. If this is null or an empty array,
* the resulting map will contain at most one entry.
* @param mapper The mapper callback.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the keys are non-unique in the result
* set.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @see Result#intoMap(Field[], Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map, E> fetchMap(Field[] keys, RecordMapper mapper)
throws DataAccessException, MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given keys and mapped by the given mapper.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(int[], RecordMapper)} instead,
* if your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldIndexes The keys. Client code must assure that keys are
* unique in the result set. If this is null or an
* empty array, the resulting map will contain at most one entry.
* @param mapper The mapper callback.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the keys are non-unique in the result
* set.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @see Result#intoMap(int[], Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map, E> fetchMap(int[] keyFieldIndexes, RecordMapper mapper)
throws DataAccessException, MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given keys and mapped by the given mapper, using {@link #field(String)}
* for lookup.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(String[], RecordMapper)}
* instead, if your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldNames The keys. Client code must assure that keys are
* unique in the result set. If this is null or an
* empty array, the resulting map will contain at most one entry.
* @param mapper The mapper callback.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the keys are non-unique in the result
* set.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @see Result#intoMap(String[], Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map, E> fetchMap(String[] keyFieldNames, RecordMapper mapper)
throws DataAccessException, MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given keys and mapped by the given mapper, using {@link #field(Name)} for
* lookup.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(Name[], RecordMapper)}
* instead, if your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldNames The keys. Client code must assure that keys are
* unique in the result set. If this is null or an
* empty array, the resulting map will contain at most one entry.
* @param mapper The mapper callback.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the keys are non-unique in the result
* set.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @see Result#intoMap(Name[], Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map, E> fetchMap(Name[] keyFieldNames, RecordMapper mapper)
throws DataAccessException, MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given key entity.
*
* The grouping semantics is governed by the key type's
* {@link Object#equals(Object)} and {@link Object#hashCode()}
* implementation, not necessarily the values as fetched from the database.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(Class)} instead, if your keys
* are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyType The key type. If this is null, the resulting
* map will contain at most one entry.
* @return A Map containing grouped results. This will never be
* null.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map fetchMap(Class keyType)
throws DataAccessException, MappingException, InvalidResultException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given key entity and mapped into the given entity type.
*
* The grouping semantics is governed by the key type's
* {@link Object#equals(Object)} and {@link Object#hashCode()}
* implementation, not necessarily the values as fetched from the database.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(Class, Class)} instead, if
* your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyType The key type. If this is null, the resulting
* map will contain at most one entry.
* @param valueType The value type.
* @return A Map containing grouped results. This will never be
* null.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(Class, Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map fetchMap(Class keyType, Class valueType)
throws DataAccessException, MappingException, InvalidResultException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given key entity and mapped into the given entity type.
*
* The grouping semantics is governed by the key type's
* {@link Object#equals(Object)} and {@link Object#hashCode()}
* implementation, not necessarily the values as fetched from the database.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(Class, RecordMapper)} instead,
* if your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyType The key type. If this is null, the resulting
* map will contain at most one entry.
* @param valueMapper The value mapper.
* @return A Map containing grouped results. This will never be
* null.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(Class, RecordMapper)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map fetchMap(Class keyType, RecordMapper valueMapper)
throws DataAccessException, InvalidResultException, MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given key entity and mapped into the given entity type.
*
* The grouping semantics is governed by the key type's
* {@link Object#equals(Object)} and {@link Object#hashCode()}
* implementation, not necessarily the values as fetched from the database.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(RecordMapper)} instead, if
* your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyMapper The key mapper.
* @return A Map containing grouped results. This will never be
* null.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(RecordMapper)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map fetchMap(RecordMapper keyMapper)
throws DataAccessException, InvalidResultException, MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given key entity and mapped into the given entity type.
*
* The grouping semantics is governed by the key type's
* {@link Object#equals(Object)} and {@link Object#hashCode()}
* implementation, not necessarily the values as fetched from the database.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(RecordMapper, Class)} instead,
* if your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyMapper The key mapper.
* @param valueType The value type.
* @return A Map containing grouped results. This will never be
* null.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(RecordMapper, Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map fetchMap(RecordMapper keyMapper, Class valueType)
throws DataAccessException, InvalidResultException, MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given key entity and mapped into the given entity type.
*
* The grouping semantics is governed by the key type's
* {@link Object#equals(Object)} and {@link Object#hashCode()}
* implementation, not necessarily the values as fetched from the database.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(RecordMapper, RecordMapper)}
* instead, if your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyMapper The key mapper.
* @param valueMapper The value mapper.
* @return A Map containing grouped results. This will never be
* null.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(RecordMapper, RecordMapper)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map fetchMap(RecordMapper keyMapper, RecordMapper valueMapper)
throws DataAccessException, InvalidResultException, MappingException;
/**
* Execute the query and return a {@link Map} with table as a map key and
* the corresponding record as value.
*
* An {@link InvalidResultException} is thrown, if the keys turn out to be
* non-unique in the result set. Use {@link #fetchGroups(Table)} instead, if
* your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param table The key table. Client code must assure that keys are unique
* in the result set. May not be null.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(Table)
*/
@NotNull
@Blocking
Map fetchMap(Table table) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with table as a map key and
* the corresponding record as value.
*
* An {@link InvalidResultException} is thrown, if the keys turn out to be
* non-unique in the result set. Use {@link #fetchGroups(Table, Table)}
* instead, if your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyTable The key table. Client code must assure that keys are
* unique in the result set. May not be null.
* @param valueTable The value table. May not be null.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key list is non-unique in the
* result set.
* @see Result#intoMap(Table, Table)
*/
@NotNull
@Blocking
Map fetchMap(Table keyTable, Table valueTable)
throws DataAccessException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given table and mapped into the given entity type.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(Table, Class)} instead, if
* your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param table The key table. Client code must assure that keys are unique
* in the result set. May not be null.
* @param type The entity type.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the keys are non-unique in the result
* set.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @see Result#intoMap(Table, Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map fetchMap(Table table, Class type)
throws DataAccessException, MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given table and mapped by the given mapper.
*
* An {@link InvalidResultException} is thrown, if the keys are non-unique
* in the result set. Use {@link #fetchGroups(Table, RecordMapper)} instead,
* if your keys are non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param table The key table. Client code must assure that keys are unique
* in the result set. May not be null.
* @param mapper The mapper callback.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the keys are non-unique in the result
* set.
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @see Result#intoMap(Table, Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map fetchMap(Table table, RecordMapper mapper)
throws DataAccessException, MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given key and mapped into the given entity type, using
* {@link #field(Field)} for lookup.
*
* An exception is thrown, if the key turn out to be non-unique in the
* result set. Use {@link #fetchGroups(Field, Class)} instead, if your key
* is non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param key The key. Client code must assure that key is unique in the
* result set.
* @param type The entity type.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key is non-unique in the result
* set.
* @see Result#intoMap(Field, Class)
*/
@NotNull
@Blocking
Map fetchMap(Field key, Class type) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given key and mapped into the given entity type.
*
* An exception is thrown, if the key turn out to be non-unique in the
* result set. Use {@link #fetchGroups(int, Class)} instead, if your key is
* non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldIndex The key. Client code must assure that key is unique
* in the result set.
* @param type The entity type.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key is non-unique in the result
* set.
* @see Result#intoMap(int, Class)
*/
@NotNull
@Blocking
Map fetchMap(int keyFieldIndex, Class type) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given key and mapped into the given entity type, using
* {@link #field(String)} for lookup.
*
* An exception is thrown, if the key turn out to be non-unique in the
* result set. Use {@link #fetchGroups(String, Class)} instead, if your key
* is non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldName The key. Client code must assure that key is unique
* in the result set.
* @param type The entity type.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key is non-unique in the result
* set.
* @see Result#intoMap(String, Class)
*/
@NotNull
@Blocking
Map fetchMap(String keyFieldName, Class type) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given key and mapped into the given entity type, using
* {@link #field(Name)} for lookup.
*
* An exception is thrown, if the key turn out to be non-unique in the
* result set. Use {@link #fetchGroups(Name, Class)} instead, if your key is
* non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldName The key. Client code must assure that key is unique
* in the result set.
* @param type The entity type.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key is non-unique in the result
* set.
* @see Result#intoMap(Name, Class)
*/
@NotNull
@Blocking
Map fetchMap(Name keyFieldName, Class type) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given key and mapped by the given mapper, using {@link #field(Field)} for
* lookup.
*
* An exception is thrown, if the key turn out to be non-unique in the
* result set. Use {@link #fetchGroups(Field, Class)} instead, if your key
* is non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param key The key. Client code must assure that key is unique in the
* result set.
* @param mapper The mapper callback.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key is non-unique in the result
* set.
* @see Result#intoMap(Field, Class)
*/
@NotNull
@Blocking
Map fetchMap(Field key, RecordMapper mapper) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given key and mapped by the given mapper.
*
* An exception is thrown, if the key turn out to be non-unique in the
* result set. Use {@link #fetchGroups(int, Class)} instead, if your key is
* non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldIndex The key. Client code must assure that key is unique
* in the result set.
* @param mapper The mapper callback.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key is non-unique in the result
* set.
* @see Result#intoMap(int, Class)
*/
@NotNull
@Blocking
Map fetchMap(int keyFieldIndex, RecordMapper mapper) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given key and mapped by the given mapper, using {@link #field(String)}
* for lookup.
*
* An exception is thrown, if the key turn out to be non-unique in the
* result set. Use {@link #fetchGroups(String, Class)} instead, if your key
* is non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldName The key. Client code must assure that key is unique
* in the result set.
* @param mapper The mapper callback.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key is non-unique in the result
* set.
* @see Result#intoMap(String, Class)
*/
@NotNull
@Blocking
Map fetchMap(String keyFieldName, RecordMapper mapper) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given key and mapped by the given mapper, using {@link #field(Name)} for
* lookup.
*
* An exception is thrown, if the key turn out to be non-unique in the
* result set. Use {@link #fetchGroups(Name, Class)} instead, if your key is
* non-unique.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldName The key. Client code must assure that key is unique
* in the result set.
* @param mapper The mapper callback.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws InvalidResultException if the key is non-unique in the result
* set.
* @see Result#intoMap(Name, Class)
*/
@NotNull
@Blocking
Map fetchMap(Name keyFieldName, RecordMapper mapper) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and a list of corresponding records as value, using
* {@link #field(Field)} for lookup.
*
* Unlike {@link #fetchMap(Field)}, this method allows for non-unique keys
* in the result set.
*
* The resulting records are attached to the original {@link Configuration}
* by default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param The key's generic field type
* @param key The key field.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(Field)
*/
@NotNull
@Blocking
Map> fetchGroups(Field key) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and a list of corresponding records as value.
*
* Unlike {@link #fetchMap(int)}, this method allows for non-unique keys in
* the result set.
*
* The resulting records are attached to the original {@link Configuration}
* by default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldIndex The key field index.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(int)
*/
@NotNull
@Blocking
Map> fetchGroups(int keyFieldIndex) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and a list of corresponding records as value, using
* {@link #field(String)} for lookup.
*
* Unlike {@link #fetchMap(String)}, this method allows for non-unique keys
* in the result set.
*
* The resulting records are attached to the original {@link Configuration}
* by default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldName The key field name.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(String)
*/
@NotNull
@Blocking
Map> fetchGroups(String keyFieldName) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and a list of corresponding records as value, using
* {@link #field(Name)} for lookup.
*
* Unlike {@link #fetchMap(Name)}, this method allows for non-unique keys in
* the result set.
*
* The resulting records are attached to the original {@link Configuration}
* by default. Use {@link Settings#isAttachRecords()} to override this
* behaviour.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldName The key field name.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(Name)
*/
@NotNull
@Blocking
Map> fetchGroups(Name keyFieldName) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and another one of the result's columns as value, using
* {@link #field(Field)} for lookup.
*
* Unlike {@link #fetchMap(Field, Field)}, this method allows for non-unique
* keys in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* If the argument {@link Field}s are the same as the ones you've provided
* to {@link DSLContext#select(SelectField, SelectField)}, then you could
* also just call {@link #collect(Collector)} with
* {@link Records#intoGroups()}.
*
* @param The key's generic field type
* @param The value's generic field type
* @param key The key field.
* @param value The value field
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(Field, Field)
*/
@NotNull
@Blocking
Map> fetchGroups(Field key, Field value) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and another one of the result's columns as value.
*
* Unlike {@link #fetchMap(int, int)}, this method allows for non-unique
* keys in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldIndex The key field index.
* @param valueFieldIndex The value field index.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(int, int)
*/
@NotNull
@Blocking
Map> fetchGroups(int keyFieldIndex, int valueFieldIndex) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and another one of the result's columns as value, using
* {@link #field(String)} for lookup.
*
* Unlike {@link #fetchMap(String, String)}, this method allows for
* non-unique keys in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldName The key field name.
* @param valueFieldName The value field name.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(String, String)
*/
@NotNull
@Blocking
Map> fetchGroups(String keyFieldName, String valueFieldName) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with one of the result's
* columns as key and another one of the result's columns as value, using
* {@link #field(Name)} for lookup.
*
* Unlike {@link #fetchMap(Name, Name)}, this method allows for non-unique
* keys in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldName The key field name.
* @param valueFieldName The value field name.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(Name, Name)
*/
@NotNull
@Blocking
Map> fetchGroups(Name keyFieldName, Name valueFieldName) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with the result grouped by the
* given keys, using {@link #field(Field)} for lookup.
*
* Unlike {@link #fetchMap(Field[])}, this method allows for non-unique keys
* in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keys The keys used for result grouping. If this is
* null or an empty array, the resulting map will
* contain at most one entry.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(Field[])
*/
@NotNull
@Blocking
Map> fetchGroups(Field[] keys) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with the result grouped by the
* given keys.
*
* Unlike {@link #fetchMap(int[])}, this method allows for non-unique keys
* in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldIndexes The keys used for result grouping. If this is
* null or an empty array, the resulting map will
* contain at most one entry.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(int[])
*/
@NotNull
@Blocking
Map> fetchGroups(int[] keyFieldIndexes) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with the result grouped by the
* given keys, using {@link #field(String)} for lookup.
*
* Unlike {@link #fetchMap(String[])}, this method allows for non-unique
* keys in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldNames The keys used for result grouping. If this is
* null or an empty array, the resulting map will
* contain at most one entry.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(String[])
*/
@NotNull
@Blocking
Map> fetchGroups(String[] keyFieldNames) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with the result grouped by the
* given keys, using {@link #field(Name)} for lookup.
*
* Unlike {@link #fetchMap(Name[])}, this method allows for non-unique keys
* in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldNames The keys used for result grouping. If this is
* null or an empty array, the resulting map will
* contain at most one entry.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(Name[])
*/
@NotNull
@Blocking
Map> fetchGroups(Name[] keyFieldNames) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with the result grouped by the
* given keys, using {@link #field(Field)} for lookup.
*
* Unlike {@link #fetchMap(Field[], Field[])}, this method allows for
* non-unique keys in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keys The keys used for result grouping. If this is
* null or an empty array, the resulting map will
* contain at most one entry.
* @param values The values.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(Field[], Field[])
*/
@NotNull
@Blocking
Map> fetchGroups(Field[] keys, Field[] values) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with the result grouped by the
* given keys.
*
* Unlike {@link #fetchMap(int[], int[])}, this method allows for non-unique
* keys in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldIndexes The keys used for result grouping. If this is
* null or an empty array, the resulting map will
* contain at most one entry.
* @param valueFieldIndexes The values.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(int[], int[])
*/
@NotNull
@Blocking
Map> fetchGroups(int[] keyFieldIndexes, int[] valueFieldIndexes) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with the result grouped by the
* given keys, using {@link #field(String)} for lookup.
*
* Unlike {@link #fetchMap(String[], String[])}, this method allows for
* non-unique keys in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldNames The keys used for result grouping. If this is
* null or an empty array, the resulting map will
* contain at most one entry.
* @param valueFieldNames The values.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(String[], String[])
*/
@NotNull
@Blocking
Map> fetchGroups(String[] keyFieldNames, String[] valueFieldNames)
throws DataAccessException;
/**
* Execute the query and return a {@link Map} with the result grouped by the
* given keys, using {@link #field(Name)} for lookup.
*
* Unlike {@link #fetchMap(Name[], Name[])}, this method allows for
* non-unique keys in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldNames The keys used for result grouping. If this is
* null or an empty array, the resulting map will
* contain at most one entry.
* @param valueFieldNames The values returned per group.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @see Result#intoGroups(Name[], Name[])
*/
@NotNull
@Blocking
Map> fetchGroups(Name[] keyFieldNames, Name[] valueFieldNames) throws DataAccessException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given keys and mapped into the given entity type, using
* {@link #field(Field)} for lookup.
*
* Unlike {@link #fetchMap(Field[], Class)}, this method allows for
* non-unique keys in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keys The keys. If this is null or an empty array, the
* resulting map will contain at most one entry.
* @param type The entity type.
* @return A Map containing grouped results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @see Result#intoGroups(Field[], Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map> fetchGroups(Field[] keys, Class type) throws MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given keys and mapped into the given entity type.
*
* Unlike {@link #fetchMap(int[], Class)}, this method allows for non-unique
* keys in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldIndexes The keys. If this is null or an empty
* array, the resulting map will contain at most one entry.
* @param type The entity type.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @see Result#intoGroups(int[], Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map> fetchGroups(int[] keyFieldIndexes, Class type) throws MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given keys and mapped into the given entity type, using
* {@link #field(String)} for lookup.
*
* Unlike {@link #fetchMap(String[], Class)}, this method allows for
* non-unique keys in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldNames The keys. If this is null or an empty
* array, the resulting map will contain at most one entry.
* @param type The entity type.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @see Result#intoGroups(String[], Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map> fetchGroups(String[] keyFieldNames, Class type) throws MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given keys and mapped into the given entity type, using
* {@link #field(Name)} for lookup.
*
* Unlike {@link #fetchMap(Name[], Class)}, this method allows for
* non-unique keys in the result set.
*
* Whether this fetches an intermediate {@link Result} (accessible by
* {@link ExecuteListener} implementations), or streams records directly to
* the collector producing the result is governed by
* {@link Settings#getFetchIntermediateResult()}.
*
* The resulting map is iteration order preserving.
*
* @param keyFieldNames The keys. If this is null or an empty
* array, the resulting map will contain at most one entry.
* @param type The entity type.
* @return A Map containing the results. This will never be
* null.
* @throws DataAccessException if something went wrong executing the query
* @throws MappingException wrapping any reflection or data type conversion
* exception that might have occurred while mapping records
* @see Result#intoGroups(Name[], Class)
* @see DefaultRecordMapper
*/
@NotNull
@Blocking
Map> fetchGroups(Name[] keyFieldNames, Class type) throws MappingException;
/**
* Execute the query and return a {@link Map} with results grouped by the
* given keys and mapped by the given mapper, using {@link #field(Field)}
* for lookup.
*