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 java.lang.Object
implements JdbiConfig<SqlStatements>

Configuration holder for SqlStatements.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static class	SqlStatements.StatementCacheKey

Field Summary

Fields

Modifier and Type	Field	Description
private boolean	allowUnusedBindings
private boolean	attachAllStatementsForCleanup
private boolean	attachCallbackStatementsForCleanup
private java.util.Map<java.lang.String,java.lang.Object>	attributes
private java.util.Collection<StatementContextListener>	contextListeners
private java.util.Collection<StatementCustomizer>	customizers
private java.lang.Integer	queryTimeout
static int	SQL_TEMPLATE_CACHE_SIZE	The default size of the SQL template cache.
private SqlLogger	sqlLogger
private SqlParser	sqlParser
private JdbiCache<SqlStatements.StatementCacheKey,java.util.function.Function<StatementContext,java.lang.String>>	templateCache
private TemplateEngine	templateEngine

Constructor Summary

Constructors

Modifier	Constructor	Description
	SqlStatements()
private	SqlStatements(SqlStatements that)

Method Summary

Modifier and Type	Method	Description
SqlStatements	addContextListener(StatementContextListener listener)
SqlStatements	addCustomizer(StatementCustomizer customizer)	Provides a means for custom statement modification.
private static JdbiCacheLoader<SqlStatements.StatementCacheKey,java.util.function.Function<StatementContext,java.lang.String>>	cacheLoaderFunction(StatementContext ctx)
<T> T	cacheStats()	Returns cache statistics for the internal template cache.
SqlStatements	createCopy()	Returns a copy of this configuration object.
(package private) void	customize(java.sql.Statement statement)
SqlStatements	define(java.lang.String key, java.lang.Object value)	Define an attribute for StatementContext for statements executed by Jdbi.
SqlStatements	defineMap(java.util.Map<java.lang.String,?> values)	Defines attributes for each key/value pair in the Map.
java.lang.Object	getAttribute(java.lang.String key)	Obtain the value of an attribute
java.util.Map<java.lang.String,java.lang.Object>	getAttributes()	Returns the attributes which will be applied to SQL statements created by Jdbi.
(package private) java.util.Collection<StatementContextListener>	getContextListeners()
(package private) java.util.Collection<StatementCustomizer>	getCustomizers()
java.lang.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	isUnusedBindingAllowed()
(package private) java.lang.String	preparedRender(java.lang.String template, StatementContext ctx)
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(java.lang.Integer seconds)	Jdbi does not implement its own timeout mechanism: it simply calls Statement.setQueryTimeout(int), leaving timeout handling to your jdbc driver.
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

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

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

setRegistry

Field Detail

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

attributes

private final java.util.Map<java.lang.String,java.lang.Object> attributes

templateEngine

private TemplateEngine templateEngine

templateCache

private JdbiCache<SqlStatements.StatementCacheKey,java.util.function.Function<StatementContext,java.lang.String>> templateCache

sqlParser

private SqlParser sqlParser

sqlLogger

private SqlLogger sqlLogger

queryTimeout

private java.lang.Integer queryTimeout

allowUnusedBindings

private boolean allowUnusedBindings

attachAllStatementsForCleanup

private boolean attachAllStatementsForCleanup

attachCallbackStatementsForCleanup

private boolean attachCallbackStatementsForCleanup

customizers

private final java.util.Collection<StatementCustomizer> customizers

contextListeners

private final java.util.Collection<StatementContextListener> contextListeners

Constructor Detail

SqlStatements

public SqlStatements()

SqlStatements

private SqlStatements(SqlStatements that)

Method Detail

define

public SqlStatements define(java.lang.String key,
                            java.lang.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(java.util.Map<java.lang.String,?> values)

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

Parameters:

values - map of attributes to define.

Returns:

this

getAttribute

public java.lang.Object getAttribute(java.lang.String key)

Obtain the value of an attribute

Parameters:

key - the name of the attribute

Returns:

the value of the attribute

getAttributes

public java.util.Map<java.lang.String,java.lang.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 java.lang.Integer getQueryTimeout()

setQueryTimeout

@Beta
public SqlStatements setQueryTimeout(@Nullable
                                     java.lang.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

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.

customize

void customize(java.sql.Statement statement)
        throws java.sql.SQLException

Throws:

java.sql.SQLException

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.

getCustomizers

java.util.Collection<StatementCustomizer> getCustomizers()

getContextListeners

java.util.Collection<StatementContextListener> getContextListeners()

preparedRender

java.lang.String preparedRender(java.lang.String template,
                                StatementContext ctx)

cacheLoaderFunction

private static JdbiCacheLoader<SqlStatements.StatementCacheKey,java.util.function.Function<StatementContext,java.lang.String>> cacheLoaderFunction(StatementContext ctx)