Утилита util-db предназначен для установления соединения с сервером базы данных (БД) и выполнения SQL-запросов бандлов приложения JaBricks объектов БД. При взаимодействии с СУБД модуль util-db использует бандлы JDBC-драйверов.

Зависимость модуля util-db от драйверов JDBC, исполненных по технологии бандлов, определяет необходимость обязательной их инсталляции в приложение согласно спецификации OSGi. Поскольку разным приложениям требуются только определенные драйверы JDBC для взаимодействия с СУБД, то модуль util-db представлен в нескольких вариантах. По́стфикс в наименовании бандла определяет используемый в модуле драйвер JDBC; отсутствие по́стфикса в наименовании утилиты util-db определяет возможность его использования со всеми доступными серверами БД.

Модуль util-db может взаимодействовать с серверами БД типа Oracle, MSSQL, PostgreSQL, MySQL, Apache Derby. Вместе с util-db в конфигурацию приложения JaBricks необходимо включить соответствующие выполненные в виде бандлов драйверы JDBC. Вы можете скачать бандлы JDBC драйверов, которые использует util-db.

Для подключения к СУБД на сайте имеется модуль db-connection, который, по сути, является интерфейсной оболочкой утилиты util-db. Модуль db-connection имеет форму в виде диалогового окна с компонентами отпределения логина и пароля. Остальные параметры подключения (тип провайдера, хост, порт и т.д) определяются в файле инициализации приложения.

Ниже представлены описания доступных в util-db драйверов JDBC различных СУБД, «порожденные» модули util-db и примеры их использования.

JDBC драйверы и бандлы взаимодействия с СУБД

Oracle
Обычный JDBC драйвер для взаимодействия с сервером Oracle (ojdbc6.jar, ojdbc7.jar, ojdbc8.jar) выполнен не по технологии OSGi-бандла; его необходимо преобразовать в бандл. Пример проекта создания бандла JDBC драйвера Oracle представлен здесь. Проект включает бандл драйвера ojdbc6-11.2.0.4.jar.

Утилита util-db-oracle, в отличие от util-db, в приложении JaBricks можно использовать только для взаимодействия с SQL-сервером Oracle. Параметры подключения к Oracle, определяемые в файле инициализации приложения, представлены здесь.

MSSQL
JDBC драйвер взаимодействия с сервером MSSQL, выполненные в виде бандлов для JRE7/JRE8, можно скачать из Maven репозитория. На сайте можно скачать бандл драйвера mssql-jdbc-6.3.6.jre8-preview.jar.

Для взаимодействия только с сервером MSSQL в приложении JaBricks можно использовать утилиту util-db-mssql. Параметры подключения к серверу MSSQL, определяемые в файле инициализации приложения, представлены здесь.

MySQL

Обычный драйвер JDBC для взаимодействия с сервером MySQL (mysql-connector-java-XXX-bin.jar) выполнен не по технологии OSGi-бандла. Для его использования в приложении JaBricks драйвер необходимо преобразовать в бандл. Пример проекта преобразования JDBC драйвера MySQL в бандл представлен здесь. На сайте можно скачать бандл драйвера com.mysql.jdbc-5.1.7.jar.

Для взаимодействия только с сервером MySQL в приложении JaBricks можно использовать бандл util-db-mysql. Параметры подключения к серверу MySQL, определяемые в файле инициализации приложения, представлены здесь.

PostgreSQL

JDBC драйвер взаимодействия с сервером PostgreSQL, выполненные в виде бандлов, можно скачать из Maven репозитория. На сайте можно скачать OSGi-бандл JDBC драйвера org.postgresql-9.1.jar.

Бандл util-db-postgres.jar можно использовать только для взаимодействия с сервером PostgreSQL. Параметры подключения к СУБД PostgreSQL, определяемые в файле инициализации приложения, представлены здесь.

Apache Derby

СУБД Apache Derby, в отличие от представленных выше SQL серверов, функционирует под управлением JVM. При использовании Derby имеется возможность выполнить либо сетевое (многопользовательское) подключение к серверу, либо монопольное подключение. Во втором случае сервер Derby работает в режиме "EmbeddedDriver" и запускается под управлением виртуальной машины JVM вместе с приложением. Пример использования сервера Derby в режиме "EmbeddedDriver" представлен здесь. На сайте можно скачать бандл JDBC драйвера для Derby org.apache.derby-10.10.1000001.jar.

Бандл util-db-derby можно использовать только для взаимодействия с сервером Apache Derby в монопольном режиме (Embedded Derby JDBC driver), т.е. для создания SQL-соединения типа «org.apache.derby.jdbc.EmbeddedDriver». Параметры подключения к серверу Apache Derby, определяемые в файле инициализации приложения, представлены здесь.

Примечание :
1. При подключении к серверу Apache Derby модуль util-db-derby использует опцию bootPassword, формируемую динамически из логина и пароля в формате «login@PASSWORD» : логин в нижнем регистре, символ-разделитель '@', пароль в верхнем регистре.
2. Готовую базу данных Derby можно скачать вместе с драйвером JDBC (логин «derby», пароль «derby»), представленную в Уроке 9 и в Уроке 10.
3. При использовании собственной БД Derby и модуля util-db-derby необходимо учитывать определенные в п.1 особенности подключения.

Описание модуля util-db

Модуль util-db включает базовый класс DAOImpl, который реализует интерфейс IDAO. Классы DAOOracle, DAOMSSQL, DAOPostgres, DAOMySQL, DAODerby наследуют свойства DAOImpl и переопределяют методы взаимодействия с соответствующим сервером БД.

«Порожденные» от util-db модули включают один из классов, наследующего свойства DAOImpl и определяющего тип провайдера СУБД. Так, к примеру, модуль util-db-oracle имеет только класс DAOOracle, а модуль util-db-mysql — класс DAOMySQL и т.д.

Методы интерфейса IDAO

Листинг

public interface IDAO 
{
    // Объект описания подключения к серверу
    public  void       setConnect (Connect connect);
    public  Connect    getConnect ();

    // Метода создания соединения с сервером
    public  Connection createConnection (Connect connect);

    // Метод чтения соединения с сервером
    public  Connection getConnection ();

    // Метод отключения от сервера БД
    public  void       disconnect ();

    // Методы определения провайдера БД
    public  boolean    isOracle  ();
    public  boolean    isMSSQL   ();
    public  boolean    isPostgres();
    public  boolean    isMySQL   ();
    public  boolean    isDerby   ();

    // Метод выполнения SQL-запроса 
    public  boolean    execSQL (String sql);

    // Чтение ошибки выполнения транзакции
    public  String     getExceptionText();
}

setConnect (Connect)
Определение объекта описания подключения Connect к серверу. Connect включает параметры подключения и объект реализации IDAO. Для создания Connect можно использовать модуль form-connection.

getConnect
Метод чтения объекта Connect, включающего объект реализации IDAO с установленным JDBC соединением java.sql.Connection к конкретному серверу базы данных JDBC.

createConnection (Connect)
Метод установления соединения java.sql.Connection с сервером БД. Если соединение не будет установлено, то метод вернет NULL. Текст и код ошибки соединения можно получить методом getExceptionText().

getConnection
Метод getConnection возвращает объект соединения java.sql.Connection с сервером БД. Если соединение с сервером БД не установлено, то метод вернет NULL. JDBC соединение java.sql.Connection можно использовать в бандлах для выполнения различных операций с сервером БД.

disconnect
Метод разрывает соединение с сервером БД.

execSQL (sql)
Метод выполнения SQL-запроса execSQL в качестве параметра принимает текстовую строку SQL-скрипта и возвращает логический результат выполнения — true, если транзакция завершилась успешно, в противном случае false. При возникновении ошибки выполнения транзакции метод логирует текст ошибки с кодом и SQL-скриптом.

getExceptionText
Метод getExceptionText возвращает код и текст ошибки от сервера БД при ошибке установления соединения, либо при аварийном завершении какой-либо транзакции в методе execSQL.

Методы isOracle, isMSSQL, isPostgres, isMySQL, isDerby определяют принадлежность объекта реализации к конретному провайдеру БД. Данные методы можно использовать для проверки при одновременном соединении приложения с разными серверами БД.

Использование модуля util-db в бандлах

Чтобы можно было использовать util-db в бандлах необходимо в секции <Import-Package> манифеста MANIFEST.MF указать наименование пакета org.jabricks.db. После этого модуль util-db станет доступным в бандле.

Для взаимодействия с сервером БД необходимо установить соединение java.sql.Connection. Предполагается, что данное соединение создает модуль подключения form-connection. Следующий пример демонстрирует получение JDBC соединения java.sql.Connection в модуле util-db.

Листинг примера получения Connection

В коде сначала выполняется чтение объекта подключения Connect, который включает реализацию класса DAOImpl с установленным соединением к конкретному серверу БД. После этого можно получить JDBC соединение java.sql.Connection для выполнения различных транзакций.

import org.jabricks.db.objects.Connect;
import org.jabricks.db.interfaces.IDAO;

import java.sql.Connection;

. . .

Connect    connect    = (new DAOImpl()).getConnect();
if (connect != null) {
    IDAO dao   = connect.getDAO();
    Connection connection = dao.getConnection();
}

Пример выполнение SQL-запроса

Метод выполнения SQL-запроса execSQL (sql) возвращает логический результат выполнения. Если транзакция завершается с ошибкой, то информация об ошибке (код и текст ошибки) логируется в файл и/или консоль в зависимости от установленных в системе флагов протоколирования. Вместе с информацией об ошибке логируется также текст SQL-запроса.

Следующий код демонстрирует пример использования util-db в бандле для выполнения SQL-запроса. Сначала необходимо получить JDBC соединение Connection. После этого запоминается и сбрасывается флаг autocommit. Этого можно было бы и не делать, поскольку транзакция касается только одной записи в одной таблице. Далее транзакция выполняется и завершается (commit). При наличии ошибки исполнения транзакции выполняется откат (rollback) и вывод текста ошибки в консоль.

Листинг

import org.jabricks.db.objects.Connect;
import org.jabricks.db.interfaces.IDAO;

import java.sql.Connection;

. . .

Connect     connect   ;  // Объект описания подключения
IDAO        dao       ;  // Объект доступа к серверу БД
Connection  connection;  // Объект соединения с сервером
boolean     autocommit;  // Флаг завершения транзакции   

. . .

connect    = (new DAOImpl()).getConnect();
dao        = new DAOImpl();
connection = dao.getConnection();
autocommit = true;

String sql = "insert into tableName (id, name) "
                   + "values (15, 'JaBricks')";
try {
    // Запоминаем autocommit
    autocommit = connection.getAutoCommit();
    connection.setAutoCommit(false);

    if (!dao.execSQL(sql))
        throw new SQLException("Текст ошибки");

    // Завершение транзакции
    connection.commit();

    // Восстановление autocommit
    connection.setAutoCommit(autocommit);
} catch (SQLException e){
    try {
        // Откат транзакции
        connection.rollback();
    } catch (SQLException e1) { }
    // Информация об ошибке
    String error = dao.getExceptionText();
    System.err.println(error);

    // Восстановление autocommit
    connection.setAutoCommit(autocommit);
}

Чтобы получить в бандле информацию об ошибке необходимо использовать метод getExceptionText(). В примере информация об ошибке выводится непосредственно в консоль. Лучше использовать модуль логирования util-logger.

Зависимости

Модуль доступа к серверам БД util-db не зависит от других модулей приложения JaBricks и имеет связи только с JDBC-драйверами, представленными в первой колонке таблицы. В последней колонке таблицы представлены разновидности модуля util-db для взаимодействия с конкретной СУБД :

Модуль	Описание	Примечание
ojdbc6-11.2.0.1.jar	бандл JDBC драйвера Oracle	util-db-oracle
mssql-jdbc-6.3.6.jre8-preview.jar	бандл JDBC драйвера MSSQL	util-db-mssql
com.mysql.jdbc-5.1.7.jar	бандл JDBC драйвера MySQL	util-db-mysql
org.postgresql-9.1.901.jdbc4.1-rc9.jar	бандл JDBC драйвера PostgreSQL	util-db-postgres
org.apache.derby-10.10.1000001.jar	Embedded Derby JDBC driver	util-db-derby

В таблице представлены бандлы взаимодействия с СУБД и JDBC драйверов, которые можно скачать. При необходимости Вы можете использовать собственные драйверы JDBC.

Подключение модуля util-db

Для подключения модуля util-db в приложение JaBricks необходимо :

разместить модуль в поддиректории «configuration/bundles/»;
внести в файл инициализации бандлов «bundles.ini» наименование модуля : util-db-1.0.1.jar.

GAV параметры модуля util-db имеют следующие значения :

	• groupId	: org.jabricks.db
	• artifactId	: util-db
	• version	: 1.0.1

Подробнее о включении модуля в приложение Jabricks представлено здесь.