Common Database

The core JDBC related classes.

1. Common classes

Two common classes used throughout the framework are the Database and DatabaseConnection classes.

1.1. Database

The Database class represents a DBMS instance and provides connections to that instance.

There are multiple ways to aquire a Database instance.

By specifying a JDBC url via a system property.

System.setProperty("codion.db.url", "jdbc:h2:mem:h2db");

Database database = Database.instance();

By setting the JDBC url configuration value directly (which also sets the system property).

Database.URL.set("jdbc:h2:mem:h2db");

Database database = Database.instance();

By instantiating a DatabaseFactory directly.

String url = "jdbc:h2:mem:h2db";

DatabaseFactory databaseFactory = DatabaseFactory.instance(url);

Database database = databaseFactory.create(url);

By instantiating a DBMS specific DatabaseFactory directly.

String url = "jdbc:h2:mem:h2db";

H2DatabaseFactory databaseFactory = new H2DatabaseFactory();

Database database = databaseFactory.create(url);

A Database instance provides java.sql.Connection instances via the createConnection method.

Database.URL.set("jdbc:h2:mem:h2db");

Database database = Database.instance();

User user = User.parse("scott:tiger");

java.sql.Connection connection = database.createConnection(user);

1.2. DatabaseConnection

The DatabaseConnection class represents a connection to a database instance and is a wrapper around a java.sql.Connection instance and provides transaction control.

A DatabaseConnection instance is created via the databaseConnection factory methods.

Database.URL.set("jdbc:h2:mem:h2db");

Database database = Database.instance();

User user = User.parse("scott:tiger");

DatabaseConnection databaseConnection =
        DatabaseConnection.databaseConnection(database, user);

databaseConnection.startTransaction();
try {
  java.sql.Connection connection = databaseConnection.getConnection();
  connection.createStatement().execute("select 1");
  databaseConnection.commitTransaction();
}
catch (SQLException e) {
  databaseConnection.rollbackTransaction();
  throw new DatabaseException(e);
}
catch (Exception e) {
  databaseConnection.rollbackTransaction();
  throw new RuntimeException(e);
}

databaseConnection.close();