Package org.sql2o

Class Sql2o

java.lang.Object

org.sql2o.Sql2o

public class Sql2o
extends Object

Sql2o is the main class for the sql2o library.

An Sql2o instance represents a way of connecting to one specific database. To create a new instance, one need to specify either jdbc-url, username and password for the database or a data source.

Internally the Sql2o instance uses a data source to create jdbc connections to the database. If url, username and password was specified in the constructor, a simple data source is created, which works as a simple wrapper around the jdbc driver.

Some jdbc implementations have quirks, therefore it may be necessary to use a constructor with the quirks parameter. When quirks are specified, Sql2o will use workarounds to avoid these quirks.

Author:

Lars Aaberg

Constructor Summary

Constructors

Constructor	Description
Sql2o(String jndiLookup)
Sql2o(String url, String user, String pass)	Creates a new instance of the Sql2o class.
Sql2o(String url, String user, String pass, Quirks quirks)	Created a new instance of the Sql2o class.
Sql2o(DataSource dataSource)	Creates a new instance of the Sql2o class, which uses the given DataSource to acquire connections to the database.
Sql2o(DataSource dataSource, Quirks quirks)	Creates a new instance of the Sql2o class, which uses the given DataSource to acquire connections to the database.

Method Summary

Modifier and Type	Method	Description
Connection	beginTransaction()	Begins a transaction with isolation level Connection.TRANSACTION_READ_COMMITTED.
Connection	beginTransaction(int isolationLevel)	Begins a transaction with the given isolation level.
Connection	beginTransaction(ConnectionSource connectionSource)	Begins a transaction with isolation level Connection.TRANSACTION_READ_COMMITTED.
Connection	beginTransaction(ConnectionSource connectionSource, int isolationLevel)	Begins a transaction with the given isolation level.
Query	createQuery(String query)	Deprecated. create queries with Connection class instead, using try-with-resource blocks try (Connection con = sql2o.open()) { return sql2o.createQuery(query, name).executeAndFetch(Pojo.class); }
Query	createQuery(String query, boolean returnGeneratedKeys)	Deprecated. create queries with Connection class instead, using try-with-resource blocks try (Connection con = sql2o.open()) { return sql2o.createQuery(query, name, returnGeneratedKeys).executeAndFetch(Pojo.class); }
ConnectionSource	getConnectionSource()	Gets the ConnectionSource that Sql2o uses internally to acquire database connections.
DataSource	getDataSource()	Deprecated. use getConnectionSource() as more general connection provider
Map<String,String>	getDefaultColumnMappings()	Gets the default column mappings Map.
Quirks	getQuirks()
boolean	isDefaultCaseSensitive()	Gets value indicating if this instance of Sql2o is case sensitive when mapping between columns names and property names.
Connection	open()	Opens a connection to the database
Connection	open(ConnectionSource connectionSource)	Opens a connection to the database
void	runInTransaction(StatementRunnable runnable)	Calls the StatementRunnable.run(Connection, Object) method on the StatementRunnable parameter.
void	runInTransaction(StatementRunnable runnable, Object argument)	Calls the StatementRunnable.run(Connection, Object) method on the StatementRunnable parameter.
void	runInTransaction(StatementRunnable runnable, Object argument, int isolationLevel)	Calls the StatementRunnable.run(Connection, Object) method on the StatementRunnable parameter.
<V> V	runInTransaction(StatementRunnableWithResult<V> runnableWithResult)
<V> V	runInTransaction(StatementRunnableWithResult<V> runnableWithResult, Object argument)
<V> V	runInTransaction(StatementRunnableWithResult<V> runnableWithResult, Object argument, int isolationLevel)
void	setConnectionSource(ConnectionSource connectionSource)	Sets the ConnectionSource that Sql2o uses internally to acquire database connections.
void	setDefaultCaseSensitive(boolean defaultCaseSensitive)	Sets a value indicating if this instance of Sql2o is case sensitive when mapping between columns names and property names.
void	setDefaultColumnMappings(Map<String,String> defaultColumnMappings)	Sets the default column mappings Map.
void	withConnection(StatementRunnable runnable)	Invokes the run method on the StatementRunnableWithResult instance.
void	withConnection(StatementRunnable runnable, Object argument)	Invokes the run method on the StatementRunnableWithResult instance.
<V> V	withConnection(StatementRunnableWithResult<V> runnable)	Invokes the run method on the StatementRunnableWithResult instance.
<V> V	withConnection(StatementRunnableWithResult<V> runnable, Object argument)	Invokes the run method on the StatementRunnableWithResult instance.

Methods inherited from class java.lang.Object

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

Constructor Details

Sql2o

public Sql2o(String jndiLookup)

Sql2o

public Sql2o(String url,
 String user,
 String pass)

Creates a new instance of the Sql2o class. Internally this constructor will create a GenericDatasource, and call the Sql2o(javax.sql.DataSource) constructor which takes a DataSource as parameter.

Parameters:

url - JDBC database url

user - database username

pass - database password

Sql2o

public Sql2o(String url,
 String user,
 String pass,
 Quirks quirks)

Created a new instance of the Sql2o class. Internally this constructor will create a GenericDatasource, and call the Sql2o(javax.sql.DataSource) constructor which takes a DataSource as parameter.

Parameters:

url - JDBC database url

user - database username

pass - database password

quirks - Quirks allows sql2o to work around known quirks and issues in different JDBC drivers.

Sql2o

public Sql2o(DataSource dataSource)

Creates a new instance of the Sql2o class, which uses the given DataSource to acquire connections to the database.

Parameters:

dataSource - The DataSource Sql2o uses to acquire connections to the database.

Sql2o

public Sql2o(DataSource dataSource,
 Quirks quirks)

Creates a new instance of the Sql2o class, which uses the given DataSource to acquire connections to the database.

Parameters:

dataSource - The DataSource Sql2o uses to acquire connections to the database.

quirks - Quirks allows sql2o to work around known quirks and issues in different JDBC drivers.

Method Details

getQuirks

public Quirks getQuirks()

getDataSource

@Deprecated
public DataSource getDataSource()

Deprecated.

use getConnectionSource() as more general connection provider

Gets the DataSource that Sql2o uses internally to acquire database connections.

Returns:

The DataSource instance

getConnectionSource

public ConnectionSource getConnectionSource()

Gets the ConnectionSource that Sql2o uses internally to acquire database connections.

Returns:

The ConnectionSource instance

setConnectionSource

public void setConnectionSource(ConnectionSource connectionSource)

Sets the ConnectionSource that Sql2o uses internally to acquire database connections.

Parameters:

connectionSource - the ConnectionSource instance to use

getDefaultColumnMappings

public Map<String,String> getDefaultColumnMappings()

Gets the default column mappings Map. column mappings added to this Map are always available when Sql2o attempts to map between result sets and object instances.

Returns:

The Map<String,String> instance, which Sql2o internally uses to map column names with property names.

setDefaultColumnMappings

public void setDefaultColumnMappings(Map<String,String> defaultColumnMappings)

Sets the default column mappings Map.

Parameters:

defaultColumnMappings - A Map instance Sql2o uses internally to map between column names and property names.

isDefaultCaseSensitive

public boolean isDefaultCaseSensitive()

Gets value indicating if this instance of Sql2o is case sensitive when mapping between columns names and property names.

Returns:

setDefaultCaseSensitive

public void setDefaultCaseSensitive(boolean defaultCaseSensitive)

Sets a value indicating if this instance of Sql2o is case sensitive when mapping between columns names and property names. This should almost always be false, because most relational databases are not case sensitive.

Parameters:

defaultCaseSensitive -

createQuery

@Deprecated
public Query createQuery(String query,
 boolean returnGeneratedKeys)

Deprecated.

create queries with Connection class instead, using try-with-resource blocks try (Connection con = sql2o.open()) { return sql2o.createQuery(query, name, returnGeneratedKeys).executeAndFetch(Pojo.class); }

Creates a Query

Parameters:

query - the sql query string

returnGeneratedKeys - boolean value indicating if the database should return any generated keys.

Returns:

the Query instance

createQuery

@Deprecated
public Query createQuery(String query)

Deprecated.

create queries with Connection class instead, using try-with-resource blocks try (Connection con = sql2o.open()) { return sql2o.createQuery(query, name).executeAndFetch(Pojo.class); }

Creates a Query

Parameters:

query - the sql query string

Returns:

the Query instance

open

public Connection open(ConnectionSource connectionSource)

Opens a connection to the database

Parameters:

connectionSource - the ConnectionSource implementation substitution, that will be used instead of one from Sql2o instance.

Returns:

instance of the Connection class.

open

public Connection open()

Opens a connection to the database

Returns:

instance of the Connection class.

withConnection

public <V> V withConnection(StatementRunnableWithResult<V> runnable,
 Object argument)

Invokes the run method on the StatementRunnableWithResult instance. This method guarantees that the connection is closed properly, when either the run method completes or if an exception occurs.

Type Parameters:

V -

Parameters:

runnable -

argument -

Returns:

withConnection

public <V> V withConnection(StatementRunnableWithResult<V> runnable)

Invokes the run method on the StatementRunnableWithResult instance. This method guarantees that the connection is closed properly, when either the run method completes or if an exception occurs.

Type Parameters:

V -

Parameters:

runnable -

Returns:

withConnection

public void withConnection(StatementRunnable runnable)

Invokes the run method on the StatementRunnableWithResult instance. This method guarantees that the connection is closed properly, when either the run method completes or if an exception occurs.

Parameters:

runnable -

withConnection

public void withConnection(StatementRunnable runnable,
 Object argument)

Invokes the run method on the StatementRunnableWithResult instance. This method guarantees that the connection is closed properly, when either the run method completes or if an exception occurs.

Parameters:

runnable -

argument -

beginTransaction

public Connection beginTransaction(int isolationLevel)

Begins a transaction with the given isolation level. Every statement executed on the return Connection instance, will be executed in the transaction. It is very important to always call either the Connection.commit() method or the Connection.rollback() method to close the transaction. Use proper try-catch logic.

Parameters:

isolationLevel - the isolation level of the transaction

Returns:

the Connection instance to use to run statements in the transaction.

beginTransaction

public Connection beginTransaction(ConnectionSource connectionSource,
 int isolationLevel)

Begins a transaction with the given isolation level. Every statement executed on the return Connection instance, will be executed in the transaction. It is very important to always call either the Connection.commit() method or the Connection.rollback() method to close the transaction. Use proper try-catch logic.

Parameters:

connectionSource - the ConnectionSource implementation substitution, that will be used instead of one from Sql2o instance.

isolationLevel - the isolation level of the transaction

Returns:

the Connection instance to use to run statements in the transaction.

beginTransaction

public Connection beginTransaction()

Begins a transaction with isolation level Connection.TRANSACTION_READ_COMMITTED. Every statement executed on the return Connection instance, will be executed in the transaction. It is very important to always call either the Connection.commit() method or the Connection.rollback() method to close the transaction. Use proper try-catch logic.

Returns:

the Connection instance to use to run statements in the transaction.

beginTransaction

public Connection beginTransaction(ConnectionSource connectionSource)

Begins a transaction with isolation level Connection.TRANSACTION_READ_COMMITTED. Every statement executed on the return Connection instance, will be executed in the transaction. It is very important to always call either the Connection.commit() method or the Connection.rollback() method to close the transaction. Use proper try-catch logic.

Parameters:

connectionSource - the ConnectionSource implementation substitution, that will be used instead of one from Sql2o instance.

Returns:

the Connection instance to use to run statements in the transaction.

runInTransaction

public void runInTransaction(StatementRunnable runnable)

Calls the StatementRunnable.run(Connection, Object) method on the StatementRunnable parameter. All statements run on the Connection instance in the run method will be executed in a transaction. The transaction will automatically be committed if the run method finishes without throwing an exception. If an exception is thrown within the run method, the transaction will automatically be rolled back. The isolation level of the transaction will be set to Connection.TRANSACTION_READ_COMMITTED

Parameters:

runnable - The StatementRunnable instance.

runInTransaction

public void runInTransaction(StatementRunnable runnable,
 Object argument)

Calls the StatementRunnable.run(Connection, Object) method on the StatementRunnable parameter. All statements run on the Connection instance in the run method will be executed in a transaction. The transaction will automatically be committed if the run method finishes without throwing an exception. If an exception is thrown within the run method, the transaction will automatically be rolled back. The isolation level of the transaction will be set to Connection.TRANSACTION_READ_COMMITTED

Parameters:

runnable - The StatementRunnable instance.

argument - An argument which will be forwarded to the run method

runInTransaction

public void runInTransaction(StatementRunnable runnable,
 Object argument,
 int isolationLevel)

Calls the StatementRunnable.run(Connection, Object) method on the StatementRunnable parameter. All statements run on the Connection instance in the run method will be executed in a transaction. The transaction will automatically be committed if the run method finishes without throwing an exception. If an exception is thrown within the run method, the transaction will automatically be rolled back.

Parameters:

runnable - The StatementRunnable instance.

argument - An argument which will be forwarded to the run method

isolationLevel - The isolation level of the transaction

runInTransaction

public <V> V runInTransaction(StatementRunnableWithResult<V> runnableWithResult)

runInTransaction

public <V> V runInTransaction(StatementRunnableWithResult<V> runnableWithResult,
 Object argument)

runInTransaction

public <V> V runInTransaction(StatementRunnableWithResult<V> runnableWithResult,
 Object argument,
 int isolationLevel)