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 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)