org.seasar.doma.jdbc.builder

Class SelectBuilder

java.lang.Object

org.seasar.doma.jdbc.builder.SelectBuilder

public class SelectBuilder
extends java.lang.Object

A builder for an SQL SELECT statement.

This is not thread safe.

Java

 SelectBuilder builder = SelectBuilder.newInstance(config);
 builder.sql("select");
 builder.sql("id").sql(",");
 builder.sql("name").sql(",");
 builder.sql("salary");
 builder.sql("from Emp");
 builder.sql("where");
 builder.sql("name like ").param(String.class, "S%");
 builder.sql("and");
 builder.sql("age > ").param(int.class, 20);
 Emp emp = builder.getEntitySingleResult(Emp.class);
 

built SQL

 select
 id,
 name,
 salary
 from Emp
 where
 name like 'S%'
 and
 age > 20
 

Method Summary

Modifier and Type	Method and Description
void	callerClassName(java.lang.String className) Sets the caller class name.
void	callerMethodName(java.lang.String methodName) Sets the caller method name.
void	ensureResult(boolean ensureResult) Whether to ensure that one or more rows are found in a result set.
void	ensureResultMapping(boolean ensureResultMapping) Whether to ensure that all entity properties are mapped to columns of a result set.
void	fetch(FetchType fetchType) Set the fetch type.
void	fetchSize(int fetchSize) Sets the fetch size.
<ELEMENT> java.util.List<ELEMENT>	getEntityResultList(java.lang.Class<ELEMENT> elementClass) Executes an SQL SELECT statement and returns the entity results.
<RESULT> RESULT	getEntitySingleResult(java.lang.Class<RESULT> resultClass) Executes an SQL SELECT statement and returns a single entity result.
java.util.List<java.util.Map<java.lang.String,java.lang.Object>>	getMapResultList(MapKeyNamingType mapKeyNamingType) Executes an SQL SELECT statement and returns the map results.
java.util.Map<java.lang.String,java.lang.Object>	getMapSingleResult(MapKeyNamingType mapKeyNamingType) Executes an SQL SELECT statement and returns a single map result.
<RESULT> java.util.Optional<RESULT>	getOptionalEntitySingleResult(java.lang.Class<RESULT> resultClass) Executes an SQL SELECT statement and returns a single entity result as Optional.
java.util.Optional<java.util.Map<java.lang.String,java.lang.Object>>	getOptionalMapSingleResult(MapKeyNamingType mapKeyNamingType) Executes an SQL SELECT statement and returns a single map result as Optional.
<ELEMENT> java.util.List<java.util.Optional<ELEMENT>>	getOptionalScalarResultList(java.lang.Class<ELEMENT> elementClass) Executes an SQL SELECT statement and returns the scalar results that are wrapped with Optional.
<RESULT> java.util.Optional<RESULT>	getOptionalScalarSingleResult(java.lang.Class<RESULT> resultClass) Executes an SQL SELECT statement and returns a single scalar result as Optional.
<ELEMENT> java.util.List<ELEMENT>	getScalarResultList(java.lang.Class<ELEMENT> elementClass) Executes an SQL SELECT statement and returns the scalar results.
<RESULT> RESULT	getScalarSingleResult(java.lang.Class<RESULT> resultClass) Executes an SQL SELECT statement and returns a single scalar result.
Sql<?>	getSql() Returns the built SQL.
<P> SelectBuilder	literal(java.lang.Class<P> paramClass, P param) Appends a parameter as literal.
<E> SelectBuilder	literals(java.lang.Class<E> elementClass, java.util.List<E> params) Appends a parameter list as literal.
void	maxRows(int maxRows) Sets the maximum number of rows for a ResultSet object.
static SelectBuilder	newInstance(Config config) Creates a new instance.
void	options(SelectOptions options) Sets the options about the SQL SELECT execution.
<P> SelectBuilder	param(java.lang.Class<P> paramClass, P param) Appends a parameter.
<E> SelectBuilder	params(java.lang.Class<E> elementClass, java.util.List<E> params) Appends a parameter list.
void	queryTimeout(int queryTimeout) Sets the query timeout limit in seconds.
SelectBuilder	removeLast() Removes the last SQL fragment or parameter.
SelectBuilder	sql(java.lang.String sql) Appends an SQL fragment.
void	sqlLogType(SqlLogType sqlLogType) Sets the SQL log format.
<TARGET> java.util.stream.Stream<TARGET>	streamEntity(java.lang.Class<TARGET> targetClass) Executes an SQL SELECT statement and returns the stream of entity results.
<TARGET,RESULT> RESULT	streamEntity(java.lang.Class<TARGET> targetClass, java.util.function.Function<java.util.stream.Stream<TARGET>,RESULT> mapper) Executes an SQL SELECT statement, handles the stream of entity values and returns the result.
protected <TARGET,RESULT> RESULT	streamEntityInternal(java.lang.Class<TARGET> targetClass, java.util.function.Function<java.util.stream.Stream<TARGET>,RESULT> mapper)
java.util.stream.Stream<java.util.Map<java.lang.String,java.lang.Object>>	streamMap(MapKeyNamingType mapKeyNamingType) Executes an SQL SELECT statement and returns the stream of map results.
<RESULT> RESULT	streamMap(MapKeyNamingType mapKeyNamingType, java.util.function.Function<java.util.stream.Stream<java.util.Map<java.lang.String,java.lang.Object>>,RESULT> mapper) Executes an SQL SELECT statement, handles the stream of map values and returns the result.
protected <RESULT> RESULT	streamMapInternal(MapKeyNamingType mapKeyNamingType, java.util.function.Function<java.util.stream.Stream<java.util.Map<java.lang.String,java.lang.Object>>,RESULT> mapper)
<TARGET> java.util.stream.Stream<java.util.Optional<TARGET>>	streamOptionalScalar(java.lang.Class<TARGET> targetClass) Executes an SQL SELECT statement and returns the stream of Optional scalar results.
<RESULT,TARGET> RESULT	streamOptionalScalar(java.lang.Class<TARGET> targetClass, java.util.function.Function<java.util.stream.Stream<java.util.Optional<TARGET>>,RESULT> mapper) Executes an SQL SELECT statement, handles the stream of Optional scalar values and returns the result.
protected <RESULT,TARGET> RESULT	streamOptionalScalarInternal(java.lang.Class<TARGET> targetClass, java.util.function.Function<java.util.stream.Stream<java.util.Optional<TARGET>>,RESULT> mapper)
<TARGET> java.util.stream.Stream<TARGET>	streamScalar(java.lang.Class<TARGET> targetClass) Executes an SQL SELECT statement and returns the stream of scalar results.
<RESULT,TARGET> RESULT	streamScalar(java.lang.Class<TARGET> targetClass, java.util.function.Function<java.util.stream.Stream<TARGET>,RESULT> mapper) Executes an SQL SELECT statement, handles the stream of scalar values and returns the result.
protected <RESULT,TARGET> RESULT	streamScalarInternal(java.lang.Class<TARGET> targetClass, java.util.function.Function<java.util.stream.Stream<TARGET>,RESULT> mapper)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

newInstance

public static SelectBuilder newInstance(Config config)

Creates a new instance.

Parameters:

config - the configuration

Returns:

a builder

Throws:

DomaNullPointerException - if config is null

sql

public SelectBuilder sql(java.lang.String sql)

Appends an SQL fragment.

Parameters:

sql - the SQL fragment

Returns:

a builder

Throws:

DomaNullPointerException - if sql is null

removeLast

public SelectBuilder removeLast()

Removes the last SQL fragment or parameter.

Returns:

a builder

param

public <P> SelectBuilder param(java.lang.Class<P> paramClass,
                               P param)

Appends a parameter.

The parameter type must be one of basic types or holder types.

Type Parameters:

P - the parameter type

Parameters:

paramClass - the parameter class

param - the parameter

Returns:

a builder

Throws:

DomaNullPointerException - if paramClass is null

params

public <E> SelectBuilder params(java.lang.Class<E> elementClass,
                                java.util.List<E> params)

Appends a parameter list.

The element type of the list must be one of basic types or holder types.

Type Parameters:

E - the element type of the list

Parameters:

elementClass - the element class of the list

params - the parameter list

Returns:

a builder

Throws:

DomaNullPointerException - if elementClass or params is null

literal

public <P> SelectBuilder literal(java.lang.Class<P> paramClass,
                                 P param)

Appends a parameter as literal.

The parameter type must be one of basic types or holder types.

Type Parameters:

P - the parameter type

Parameters:

paramClass - the parameter class

param - the parameter

Returns:

a builder

Throws:

DomaNullPointerException - if paramClass is null

literals

public <E> SelectBuilder literals(java.lang.Class<E> elementClass,
                                  java.util.List<E> params)

Appends a parameter list as literal.

The element type of the list must be one of basic types or holder types.

Type Parameters:

E - the element type of the list

Parameters:

elementClass - the element class of the list

params - the parameter list

Returns:

a builder

Throws:

DomaNullPointerException - if elementClass or params is null

getEntitySingleResult

public <RESULT> RESULT getEntitySingleResult(java.lang.Class<RESULT> resultClass)

Executes an SQL SELECT statement and returns a single entity result.

Type Parameters:

RESULT - the entity type

Parameters:

resultClass - the entity class

Returns:

a single entity or null if the result is none

Throws:

DomaNullPointerException - if resultClass is null

DomaIllegalArgumentException - if resultClass is not entity class

UnknownColumnException - if there is the column that is unknown to the entity

NoResultException - if you set true to ensureResult(boolean) and the result is none

ResultMappingException - if you set true to ensureResultMapping(boolean) and all properties in the entity are not mapped to columns in a result set

NonUniqueResultException - if the number of fetched rows is greater than or equal to 2

JdbcException - if a JDBC related error occurs

getOptionalEntitySingleResult

public <RESULT> java.util.Optional<RESULT> getOptionalEntitySingleResult(java.lang.Class<RESULT> resultClass)

Executes an SQL SELECT statement and returns a single entity result as Optional.

Type Parameters:

RESULT - the entity type

Parameters:

resultClass - the entity class

Returns:

a single entity

Throws:

DomaNullPointerException - if resultClass is null

DomaIllegalArgumentException - if resultClass is not entity class

UnknownColumnException - if there is the column that is unknown to the entity

NoResultException - if you set true to ensureResult(boolean) and the result is none

ResultMappingException - if you set true to ensureResultMapping(boolean) and all properties in the entity are not mapped to columns in a result set

NonUniqueResultException - if the number of fetched rows is greater than or equal to 2

JdbcException - if a JDBC related error occurs

getScalarSingleResult

public <RESULT> RESULT getScalarSingleResult(java.lang.Class<RESULT> resultClass)

Executes an SQL SELECT statement and returns a single scalar result.

Type Parameters:

RESULT - the basic type or the holder type

Parameters:

resultClass - the basic class or the holder class

Returns:

a single scalar or null if the result is none

Throws:

DomaNullPointerException - if resultClass is null

DomaIllegalArgumentException - if resultClass is not entity class

NonSingleColumnException - if there are multiple columns in a result set

NoResultException - if you set true to ensureResult(boolean) and the result is none

NonUniqueResultException - if the number of fetched rows is greater than or equal to 2

JdbcException - if a JDBC related error occurs

getOptionalScalarSingleResult

public <RESULT> java.util.Optional<RESULT> getOptionalScalarSingleResult(java.lang.Class<RESULT> resultClass)

Executes an SQL SELECT statement and returns a single scalar result as Optional.

Type Parameters:

RESULT - the basic type or the holder type

Parameters:

resultClass - the basic class or the holder class

Returns:

a single scalar

Throws:

DomaNullPointerException - if resultClass is null

DomaIllegalArgumentException - if resultClass is neither the basic class nor the holder class

NonSingleColumnException - if there are multiple columns in a result set

NoResultException - if you set true to ensureResult(boolean) and the result is none

NonUniqueResultException - if the number of fetched rows is greater than or equal to 2

JdbcException - if a JDBC related error occurs

getMapSingleResult

public java.util.Map<java.lang.String,java.lang.Object> getMapSingleResult(MapKeyNamingType mapKeyNamingType)

Executes an SQL SELECT statement and returns a single map result.

Parameters:

mapKeyNamingType - a naming convention for the keys of the map

Returns:

a single map or null if the result is none

Throws:

DomaNullPointerException - if mapKeyNamingType is null

NoResultException - if you set true to ensureResult(boolean) and the result is none

NonUniqueResultException - if the number of fetched rows is greater than or equal to 2

JdbcException - if a JDBC related error occurs

getOptionalMapSingleResult

public java.util.Optional<java.util.Map<java.lang.String,java.lang.Object>> getOptionalMapSingleResult(MapKeyNamingType mapKeyNamingType)

Executes an SQL SELECT statement and returns a single map result as Optional.

Parameters:

mapKeyNamingType - a naming convention for the keys of the map

Returns:

a single map

Throws:

DomaNullPointerException - if mapKeyNamingType is null

NoResultException - if you set true to ensureResult(boolean) and the result is none

NonUniqueResultException - if the number of fetched rows is greater than or equal to 2

JdbcException - if a JDBC related error occurs

getEntityResultList

public <ELEMENT> java.util.List<ELEMENT> getEntityResultList(java.lang.Class<ELEMENT> elementClass)

Executes an SQL SELECT statement and returns the entity results.

Type Parameters:

ELEMENT - the entity type

Parameters:

elementClass - the entity class

Returns:

the entity results

Throws:

DomaNullPointerException - if elementClass is null

DomaIllegalArgumentException - if elementClass is not entity class

UnknownColumnException - if there is the column that is unknown to the entity

NoResultException - if you set true to ensureResult(boolean) and the result is none

ResultMappingException - if you set true to ensureResultMapping(boolean) and all properties in the entity are not mapped to columns in a result set

JdbcException - if a JDBC related error occurs

getScalarResultList

public <ELEMENT> java.util.List<ELEMENT> getScalarResultList(java.lang.Class<ELEMENT> elementClass)

Executes an SQL SELECT statement and returns the scalar results.

Type Parameters:

ELEMENT - the basic type or the holder type

Parameters:

elementClass - the basic class or the holder class

Returns:

the scalar results

Throws:

DomaNullPointerException - if elementClass is null

DomaIllegalArgumentException - if elementClass is neither the basic class nor the holder class

UnknownColumnException - if there is the column that is unknown to the entity

NoResultException - if you set true to ensureResult(boolean) and the result is none

ResultMappingException - if you set true to ensureResultMapping(boolean) and all properties in the entity are not mapped to columns in a result set

JdbcException - if a JDBC related error occurs

getOptionalScalarResultList

public <ELEMENT> java.util.List<java.util.Optional<ELEMENT>> getOptionalScalarResultList(java.lang.Class<ELEMENT> elementClass)

Executes an SQL SELECT statement and returns the scalar results that are wrapped with Optional.

Type Parameters:

ELEMENT - the basic type or the holder type

Parameters:

elementClass - the basic class or the holder class

Returns:

the scalar results

Throws:

DomaNullPointerException - if elementClass is null

DomaIllegalArgumentException - if elementClass is neither the basic class nor the holder class

UnknownColumnException - if there is the column that is unknown to the entity

NoResultException - if you set true to ensureResult(boolean) and the result is none

ResultMappingException - if you set true to ensureResultMapping(boolean) and all properties in the entity are not mapped to columns in a result set

JdbcException - if a JDBC related error occurs

getMapResultList

public java.util.List<java.util.Map<java.lang.String,java.lang.Object>> getMapResultList(MapKeyNamingType mapKeyNamingType)

Executes an SQL SELECT statement and returns the map results.

Parameters:

mapKeyNamingType - a naming convention for the keys of the map

Returns:

the map results

Throws:

DomaNullPointerException - if mapKeyNamingType is null

JdbcException - if a JDBC related error occurs

streamEntity

public <TARGET> java.util.stream.Stream<TARGET> streamEntity(java.lang.Class<TARGET> targetClass)

Executes an SQL SELECT statement and returns the stream of entity results.

The caller must close the stream.

Type Parameters:

TARGET - the entity type

Parameters:

targetClass - the entity class

Returns:

the stream of the entity results

Throws:

DomaNullPointerException - if targetClass is null

DomaIllegalArgumentException - if targetClass is not entity class

JdbcException - if a JDBC related error occurs

streamEntity

public <TARGET,RESULT> RESULT streamEntity(java.lang.Class<TARGET> targetClass,
                                           java.util.function.Function<java.util.stream.Stream<TARGET>,RESULT> mapper)

Executes an SQL SELECT statement, handles the stream of entity values and returns the result.

Type Parameters:

RESULT - the result type

TARGET - the entity type

Parameters:

targetClass - the entity class

mapper - the mapper function

Returns:

the result

Throws:

DomaNullPointerException - if targetClass or mapper is null

DomaIllegalArgumentException - if targetClass is not entity class

UnknownColumnException - if there is the column that is unknown to the entity

NoResultException - if you set true to ensureResult(boolean) and the result is none

ResultMappingException - if you set true to ensureResultMapping(boolean) and all properties in the entity are not mapped to columns in a result set

JdbcException - if a JDBC related error occurs

streamEntityInternal

protected <TARGET,RESULT> RESULT streamEntityInternal(java.lang.Class<TARGET> targetClass,
                                                      java.util.function.Function<java.util.stream.Stream<TARGET>,RESULT> mapper)

streamScalar

public <TARGET> java.util.stream.Stream<TARGET> streamScalar(java.lang.Class<TARGET> targetClass)

Executes an SQL SELECT statement and returns the stream of scalar results.

The caller must close the stream.

Type Parameters:

TARGET - the basic type or the holder type

Parameters:

targetClass - the basic class or the holder class

Returns:

the stream of scalar results

Throws:

DomaNullPointerException - if targetClass is null

DomaIllegalArgumentException - if targetClass is neither the basic class nor the holder class

JdbcException - if a JDBC related error occurs

streamScalar

public <RESULT,TARGET> RESULT streamScalar(java.lang.Class<TARGET> targetClass,
                                           java.util.function.Function<java.util.stream.Stream<TARGET>,RESULT> mapper)

Executes an SQL SELECT statement, handles the stream of scalar values and returns the result.

Type Parameters:

RESULT - the result type

TARGET - the basic type or the holder type

Parameters:

targetClass - the basic class or the holder class

mapper - the mapper function

Returns:

the result

Throws:

DomaNullPointerException - if targetClass or mapper is null

DomaIllegalArgumentException - if targetClass is neither the basic class nor the holder class

NonSingleColumnException - if there are multiple columns in a result set

NoResultException - if you set true to ensureResult(boolean) and the result is none

JdbcException - if a JDBC related error occurs

streamScalarInternal

protected <RESULT,TARGET> RESULT streamScalarInternal(java.lang.Class<TARGET> targetClass,
                                                      java.util.function.Function<java.util.stream.Stream<TARGET>,RESULT> mapper)

streamOptionalScalar

public <TARGET> java.util.stream.Stream<java.util.Optional<TARGET>> streamOptionalScalar(java.lang.Class<TARGET> targetClass)

Executes an SQL SELECT statement and returns the stream of Optional scalar results.

The caller must close the stream.

Type Parameters:

TARGET - the basic type or the holder type

Parameters:

targetClass - the basic class or the holder class

Returns:

the stream of Optional scalar results

Throws:

DomaNullPointerException - if targetClass is null

DomaIllegalArgumentException - if targetClass is neither the basic class nor the holder class

JdbcException - if a JDBC related error occurs

streamOptionalScalar

public <RESULT,TARGET> RESULT streamOptionalScalar(java.lang.Class<TARGET> targetClass,
                                                   java.util.function.Function<java.util.stream.Stream<java.util.Optional<TARGET>>,RESULT> mapper)

Executes an SQL SELECT statement, handles the stream of Optional scalar values and returns the result.

Type Parameters:

RESULT - the result type

TARGET - the basic type or the holder type

Parameters:

targetClass - the basic class or the holder class

mapper - the mapper function

Returns:

the result

Throws:

DomaNullPointerException - if targetClass or mapper is null

DomaIllegalArgumentException - if targetClass is neither the basic class nor the holder class

NonSingleColumnException - if there are multiple columns in a result set

NoResultException - if you set true to ensureResult(boolean) and the result is none

JdbcException - if a JDBC related error occurs

streamOptionalScalarInternal

protected <RESULT,TARGET> RESULT streamOptionalScalarInternal(java.lang.Class<TARGET> targetClass,
                                                              java.util.function.Function<java.util.stream.Stream<java.util.Optional<TARGET>>,RESULT> mapper)

streamMap

public java.util.stream.Stream<java.util.Map<java.lang.String,java.lang.Object>> streamMap(MapKeyNamingType mapKeyNamingType)

Executes an SQL SELECT statement and returns the stream of map results.

The caller must close the stream.

Parameters:

mapKeyNamingType - a naming convention for the keys of the map

Returns:

the map results

Throws:

DomaNullPointerException - if mapKeyNamingType is null

JdbcException - if a JDBC related error occurs

streamMap

public <RESULT> RESULT streamMap(MapKeyNamingType mapKeyNamingType,
                                 java.util.function.Function<java.util.stream.Stream<java.util.Map<java.lang.String,java.lang.Object>>,RESULT> mapper)

Executes an SQL SELECT statement, handles the stream of map values and returns the result.

Type Parameters:

RESULT - the result type

Parameters:

mapKeyNamingType - a naming convention for the keys of the map

mapper - the mapper function

Returns:

the result

Throws:

DomaNullPointerException - if mapKeyNamingType or mapper is null

JdbcException - if a JDBC related error occurs

streamMapInternal

protected <RESULT> RESULT streamMapInternal(MapKeyNamingType mapKeyNamingType,
                                            java.util.function.Function<java.util.stream.Stream<java.util.Map<java.lang.String,java.lang.Object>>,RESULT> mapper)

ensureResult

public void ensureResult(boolean ensureResult)

Whether to ensure that one or more rows are found in a result set.

Parameters:

ensureResult - whether to ensure

ensureResultMapping

public void ensureResultMapping(boolean ensureResultMapping)

Whether to ensure that all entity properties are mapped to columns of a result set.

Parameters:

ensureResultMapping - whether to ensure

fetch

public void fetch(FetchType fetchType)

Set the fetch type.

Parameters:

fetchType - the fetch type

fetchSize

public void fetchSize(int fetchSize)

Sets the fetch size.

If not specified, the value of Config.getFetchSize() is used.

Parameters:

fetchSize - the fetch size

See Also:

Statement.setFetchSize(int)

maxRows

public void maxRows(int maxRows)

Sets the maximum number of rows for a ResultSet object.

If not specified, the value of Config.getMaxRows() is used.

Parameters:

maxRows - the maximum number of rows

See Also:

Statement.setMaxRows(int)

queryTimeout

public void queryTimeout(int queryTimeout)

Sets the query timeout limit in seconds.

If not specified, the value of Config.getQueryTimeout() is used.

Parameters:

queryTimeout - the query timeout limit in seconds

See Also:

Statement.setQueryTimeout(int)

sqlLogType

public void sqlLogType(SqlLogType sqlLogType)

Sets the SQL log format.

Parameters:

sqlLogType - the SQL log format type

callerClassName

public void callerClassName(java.lang.String className)

Sets the caller class name.

If not specified, the class name of this instance is used.

Parameters:

className - the caller class name

Throws:

DomaNullPointerException - if className is null

callerMethodName

public void callerMethodName(java.lang.String methodName)

Sets the caller method name.

Parameters:

methodName - the caller method name

Throws:

DomaNullPointerException - if methodName is null

options

public void options(SelectOptions options)

Sets the options about the SQL SELECT execution.

Parameters:

options - the options about the SQL SELECT execution

Throws:

DomaNullPointerException - if options is null

getSql

public Sql<?> getSql()

Returns the built SQL.

Returns:

the built SQL