Package org.jdbi.v3.core.statement

Class SqlStatements

java.lang.Object

org.jdbi.v3.core.statement.SqlStatements

All Implemented Interfaces:

JdbiConfig<SqlStatements>

public final class SqlStatements
extends Object
implements JdbiConfig<SqlStatements>

Configuration holder for SqlStatements.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	SQL_TEMPLATE_CACHE_SIZE	The default size of the SQL template cache.

Constructor Summary

Constructors

Constructor	Description
SqlStatements()

Method Summary

Modifier and Type	Method	Description
SqlStatements	addContextListener(StatementContextListener listener)
SqlStatements	addCustomizer(StatementCustomizer customizer)	Provides a means for custom statement modification.
<T> T	cacheStats()	Returns cache statistics for the internal template cache.
SqlStatements	createCopy()	Returns a copy of this configuration object.
SqlStatements	define(String key, Object value)	Define an attribute for StatementContext for statements executed by Jdbi.
SqlStatements	defineMap(Map<String,?> values)	Defines attributes for each key/value pair in the Map.
Object	getAttribute(String key)	Obtain the value of an attribute
Map<String,Object>	getAttributes()	Returns the attributes which will be applied to SQL statements created by Jdbi.
Integer	getQueryTimeout()
SqlLogger	getSqlLogger()	Returns the current logger.
SqlParser	getSqlParser()
TemplateEngine	getTemplateEngine()	Returns the TemplateEngine which renders the SQL template.
TimingCollector	getTimingCollector()	Deprecated. use getSqlLogger() instead
boolean	isAttachAllStatementsForCleanup()	If true, all statements created within Jdbi.withHandle(org.jdbi.v3.core.HandleCallback<R, X>), Jdbi.useHandle(org.jdbi.v3.core.HandleConsumer<X>), Jdbi.inTransaction(org.jdbi.v3.core.HandleCallback<R, X>) and Jdbi.useTransaction(org.jdbi.v3.core.HandleConsumer<X>) are attached to the Handle object for cleanup.
boolean	isAttachCallbackStatementsForCleanup()	If true, statements created within Jdbi.withHandle(org.jdbi.v3.core.HandleCallback<R, X>), Jdbi.useHandle(org.jdbi.v3.core.HandleConsumer<X>), Jdbi.inTransaction(org.jdbi.v3.core.HandleCallback<R, X>) and Jdbi.useTransaction(org.jdbi.v3.core.HandleConsumer<X>) will be attached to the Handle object in the callback for cleanup.
boolean	isScriptStatementsNeedSemicolon()	If true, script statements parsed by a Script object will have a trailing semicolon.
boolean	isUnusedBindingAllowed()
void	setAttachAllStatementsForCleanup(boolean attachAllStatementsForCleanup)	Sets whether all statements created will automatically attached to the corresponding Handle object automatically.
void	setAttachCallbackStatementsForCleanup(boolean attachCallbackStatementsForCleanup)	Sets whether statements created within the Jdbi.withHandle(org.jdbi.v3.core.HandleCallback<R, X>), Jdbi.useHandle(org.jdbi.v3.core.HandleConsumer<X>), Jdbi.inTransaction(org.jdbi.v3.core.HandleCallback<R, X>) and Jdbi.useTransaction(org.jdbi.v3.core.HandleConsumer<X>) callback methods will automatically attached to the Handle object and therefore cleaned up when the callback ends.
SqlStatements	setQueryTimeout(Integer seconds)	Jdbi does not implement its own timeout mechanism: it simply calls Statement.setQueryTimeout(int), leaving timeout handling to your jdbc driver.
void	setScriptStatementsNeedSemicolon(boolean scriptStatementsNeedSemicolon)	If true, script statements parsed by a Script object will have a trailing semicolon.
SqlStatements	setSqlLogger(SqlLogger sqlLogger)	Sets a SqlLogger instance to log all SQL operations.
SqlStatements	setSqlParser(SqlParser sqlParser)	Sets the SqlParser used to parse parameters in SQL statements executed by Jdbi.
SqlStatements	setTemplateCache(JdbiCacheBuilder cacheBuilder)	Sets the cache used to avoid repeatedly parsing SQL statements.
SqlStatements	setTemplateEngine(TemplateEngine templateEngine)	Sets the TemplateEngine used to render SQL for all SQL statements executed by Jdbi.
SqlStatements	setTimingCollector(TimingCollector timingCollector)	Deprecated. use setSqlLogger(org.jdbi.v3.core.statement.SqlLogger) instead
SqlStatements	setUnusedBindingAllowed(boolean unusedBindingAllowed)	Sets whether or not an exception should be thrown when any arguments are given to a query but not actually used in it.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.jdbi.v3.core.config.JdbiConfig

setRegistry

Field Details

SQL_TEMPLATE_CACHE_SIZE

public static final int SQL_TEMPLATE_CACHE_SIZE

The default size of the SQL template cache.

See Also:

• Constant Field Values

Constructor Details

SqlStatements

public SqlStatements()

Method Details

define

public SqlStatements define(String key,
 Object value)

Define an attribute for StatementContext for statements executed by Jdbi.

Parameters:

key - the key for the attribute

value - the value for the attribute

Returns:

this

defineMap

public SqlStatements defineMap(Map<String,?> values)

Defines attributes for each key/value pair in the Map.

Parameters:

values - map of attributes to define.

Returns:

this

getAttribute

public Object getAttribute(String key)

Obtain the value of an attribute

Parameters:

key - the name of the attribute

Returns:

the value of the attribute

getAttributes

public Map<String,Object> getAttributes()

Returns the attributes which will be applied to SQL statements created by Jdbi.

Returns:

the defined attributes.

addCustomizer

public SqlStatements addCustomizer(StatementCustomizer customizer)

Provides a means for custom statement modification. Common customizations have their own methods, such as Query.setMaxRows(int)

Parameters:

customizer - instance to be used to customize a statement

Returns:

this

addContextListener

public SqlStatements addContextListener(StatementContextListener listener)

getTemplateEngine

public TemplateEngine getTemplateEngine()

Returns the TemplateEngine which renders the SQL template.

Returns:

the template engine which renders the SQL template prior to parsing parameters.

setTemplateEngine

public SqlStatements setTemplateEngine(TemplateEngine templateEngine)

Sets the TemplateEngine used to render SQL for all SQL statements executed by Jdbi. The default engine replaces <name>-style tokens with attributes defined on the statement context.

Parameters:

templateEngine - the new template engine.

Returns:

this

setTemplateCache

@Beta
public SqlStatements setTemplateCache(JdbiCacheBuilder cacheBuilder)

Sets the cache used to avoid repeatedly parsing SQL statements.

Parameters:

cacheBuilder - the cache builder to use to create the cache.

Returns:

this

getSqlParser

public SqlParser getSqlParser()

setSqlParser

public SqlStatements setSqlParser(SqlParser sqlParser)

Sets the SqlParser used to parse parameters in SQL statements executed by Jdbi. The default parses colon-prefixed named parameter tokens, e.g. :name.

Parameters:

sqlParser - the new SQL parser.

Returns:

this

getTimingCollector

@Deprecated
public TimingCollector getTimingCollector()

Deprecated.

use getSqlLogger() instead

Returns:

the timing collector

setTimingCollector

@Deprecated
public SqlStatements setTimingCollector(TimingCollector timingCollector)

Deprecated.

use setSqlLogger(org.jdbi.v3.core.statement.SqlLogger) instead

Sets the TimingCollector used to collect timing about the SQL statements executed by Jdbi. The default collector does nothing.

Parameters:

timingCollector - the new timing collector

Returns:

this

getSqlLogger

public SqlLogger getSqlLogger()

Returns the current logger.

Returns:

A SqlLogger instance

setSqlLogger

public SqlStatements setSqlLogger(SqlLogger sqlLogger)

Sets a SqlLogger instance to log all SQL operations.

Parameters:

sqlLogger - The logger. Using null turns off all logging

Returns:

this

getQueryTimeout

@Beta
public Integer getQueryTimeout()

setQueryTimeout

@Beta
public SqlStatements setQueryTimeout(@Nullable
 Integer seconds)

Jdbi does not implement its own timeout mechanism: it simply calls Statement.setQueryTimeout(int), leaving timeout handling to your jdbc driver.

Parameters:

seconds - the time in seconds to wait for a query to complete; 0 to disable the timeout; null to leave it at defaults (i.e. Jdbi will not call setQueryTimeout(int))

Returns:

this

isUnusedBindingAllowed

public boolean isUnusedBindingAllowed()

setUnusedBindingAllowed

public SqlStatements setUnusedBindingAllowed(boolean unusedBindingAllowed)

Sets whether or not an exception should be thrown when any arguments are given to a query but not actually used in it. Unused bindings tend to be bugs or oversights, but are not always. Defaults to false: unused bindings are not allowed.

Parameters:

unusedBindingAllowed - the new setting

Returns:

this

See Also:

• Argument

isAttachAllStatementsForCleanup

public boolean isAttachAllStatementsForCleanup()

If true, all statements created within Jdbi.withHandle(org.jdbi.v3.core.HandleCallback<R, X>), Jdbi.useHandle(org.jdbi.v3.core.HandleConsumer<X>), Jdbi.inTransaction(org.jdbi.v3.core.HandleCallback<R, X>) and Jdbi.useTransaction(org.jdbi.v3.core.HandleConsumer<X>) are attached to the Handle object for cleanup.

Returns:

True if statements are attached to their handle for cleanup

Since:

3.38.0

setAttachAllStatementsForCleanup

@Beta
public void setAttachAllStatementsForCleanup(boolean attachAllStatementsForCleanup)

Sets whether all statements created will automatically attached to the corresponding Handle object automatically. This can be useful when mostly short-lived handles are used because closing the handle will now clean up all outstanding resources from any statement. The default is false.

Parameters:

attachAllStatementsForCleanup - If true, all statements are automatically attached to the Handle

Since:

3.38.0

isAttachCallbackStatementsForCleanup

public boolean isAttachCallbackStatementsForCleanup()

If true, statements created within Jdbi.withHandle(org.jdbi.v3.core.HandleCallback<R, X>), Jdbi.useHandle(org.jdbi.v3.core.HandleConsumer<X>), Jdbi.inTransaction(org.jdbi.v3.core.HandleCallback<R, X>) and Jdbi.useTransaction(org.jdbi.v3.core.HandleConsumer<X>) will be attached to the Handle object in the callback for cleanup.

Returns:

True if statements are attached to their handle within Jdbi callbacks

Since:

3.38.0

setScriptStatementsNeedSemicolon

public void setScriptStatementsNeedSemicolon(boolean scriptStatementsNeedSemicolon)

If true, script statements parsed by a Script object will have a trailing semicolon. Some databases (e.g. Oracle) require that trailing semicolon while others (e.g. MySQL) do not and may consider it a syntax error. If executing a script against the database results in syntax errors that point at semicolons, change the value of this setting.
The default setting is true for historical reasons.

Parameters:

scriptStatementsNeedSemicolon - If true, parsed statements will have a trailing semicolon.

Since:

3.43.0

isScriptStatementsNeedSemicolon

public boolean isScriptStatementsNeedSemicolon()

If true, script statements parsed by a Script object will have a trailing semicolon. Some databases (e.g. Oracle) require that trailing semicolon while others (e.g. MySQL) do not and may consider it a syntax error. If executing a script against the database results in syntax errors that point at semicolons, change the value of this setting.

Returns:

True if parsed statements will have a trailing semicolon.

Since:

3.43.0

setAttachCallbackStatementsForCleanup

public void setAttachCallbackStatementsForCleanup(boolean attachCallbackStatementsForCleanup)

Sets whether statements created within the Jdbi.withHandle(org.jdbi.v3.core.HandleCallback<R, X>), Jdbi.useHandle(org.jdbi.v3.core.HandleConsumer<X>), Jdbi.inTransaction(org.jdbi.v3.core.HandleCallback<R, X>) and Jdbi.useTransaction(org.jdbi.v3.core.HandleConsumer<X>) callback methods will automatically attached to the Handle object and therefore cleaned up when the callback ends. The default is true.

Parameters:

attachCallbackStatementsForCleanup - If true, statements created within the Jdbi callbacks are attached to the handle

Since:

3.38.0

cacheStats

@Beta
public <T> T cacheStats()

Returns cache statistics for the internal template cache. This returns a cache specific object, so the user needs to know what caching library is in use.

createCopy

public SqlStatements createCopy()

Description copied from interface: JdbiConfig

Returns a copy of this configuration object. Changes to the copy should not modify the original, and vice-versa.

Specified by:

createCopy in interface JdbiConfig<SqlStatements>

Returns:

a copy of this configuration object.