Использование библиотеки

Подключение библиотеки в проект

Для использования библиотеки необходимо ее подключить в проект. Способ подключения зависит от вида проекта. Например, для maven проекта нужно добавить зависимость


  <dependency>
    <groupId>ru.funsys.avalanche</groupId>
    <artifactId>avalanche-sql</artifactId>
    <version>${avalanche.version}</version>
  </dependency>

где ${avalanche.version} - номер версии библиотеки, например:


  <properties>
    <avalanche.version>1.3.2</avalanche.version>
  </properties>

Помимо добавления зависимости возможно потребуется добавить maven репозиторий, в котором опубликованы библиотеки "Avalanche - application framework for Java". Это можно сделать несколькими способами, например в файл pom.xml проекта или в файл settings.xml локального maven репозитория.

Использование библиотеки в коде проекта

В программной модели приложения использования библиотеки avalanche-sql осуществляется через вызовы методов адаптера ru.funsys.avalanche.sql.Adapter. Ссылку на экземпляр объекта адаптера можно получить в классе наследнике класса ru.funsys.avalanche.Application по средствам вызова метода getAdapter(String name), где параметр name это имя адаптера, определенного в конфигурации. Или явно определить поле адаптера в классе наследнике класса ru.funsys.avalanche.Application.

Пример получения ссылки на экземпляр адаптера (фрагмент кода), в конфигурационном файле приложения должна быть определена дочерняя секция <adapter> с именем database в конфигурации класса DemoApplication


...
class public DemoApplication extends Application {

	...
	
	public ... demoMethod(...) {
		Adapter database = (Adapter) getAdapter("database");
		...
		// Выполнить запрос данных
		ResultSet resultSet = database.select(...);
		...
	}
	
	...

}

Пример декларации поля адаптера database (фрагмент кода) в классе DemoApplication, в конфигурационном файле приложения должна быть определена дочерняя секция <adapter> в конфигурации класса DemoApplication. Поле класса database будет установлено автоматически либо по имени, либо по типу соответствующего адаптера.


...
class public DemoApplication extends Application {

	...
	
	private Adapter database;
	
	...
	
	public ... demoMethod(...) {
		...
		// Выполнить запрос данных
		ResultSet resultSet = database.select(...);
		...
	}
	
	...

}

Изменение файла конфигурации приложения

В файле конфигурации приложения должна быть определена секция, содержащая конфигурационные параметры класса ru.funsys.avalanche.sql.Database, обязательно должны быть определены атрибуты name и resource. Допускается определение конфигурации класса ru.funsys.avalanche.sql.Database как секцией <function>, так и секцией <application>.

Пример определения в секции <function>


	<!-- 
	Сервисные функции работы с БД, источник данных БД определяется в конфигурации 
	контекста WEB приложение (для Tomcat см. вложенный элемент <Resource> секции <context>)
	 -->
	<function class="ru.funsys.avalanche.sql.Database" name="database" description="Функция доступа к БД"
	             resource="java:/jboss/datasources/PostgresDataSource">
	</function>

Пример определения в секции <application>, обязательно должен быть определен атрибут function в значении true


	<!-- 
	Сервисные функции работы с БД, источник данных БД определяется в конфигурации 
	контекста WEB приложение (для Tomcat см. вложенный элемент <Resource> секции <context>)
	 -->
	<application class="ru.funsys.avalanche.sql.Database" name="database" description="Функция доступа к БД"
	             resource="java:/jboss/datasources/PostgresDataSource" function="true">
	</application>

Если приложение должно работать с несколькими базами данных, то в конфигурации приложения определяются несколько секций класса ru.funsys.avalanche.sql.Database. Для каждого источника данных своя секция класса.

В секциях <application> одной или несколькими дочерними секциями adapter определяются адаптеры доступа к объектам ru.funsys.avalanche.sql.Database

Пример определения адаптера ru.funsys.avalanche.sql.Adapter, в атрибуте uri указывается локальное имя экземпляра класса ru.funsys.avalanche.sql.Database (значение атрибута name соответствующей секции <function> или <application>).


    <application class="ru.domain.DemoApplication" name="demo"
                 description="Пример определения адаптера">
	          
        <adapter class="ru.funsys.avalanche.sql.Adapter" name="database" uri="database"" />

    </application>

Конфигурирование удаленного доступа

Доступ адаптера ru.funsys.avalanche.sql.Adapter к удаленному узлу с экземпляром класса ru.funsys.avalanche.sql.Database осуществляется через пару <interface> и <connector>. Секция <connector> добавляется в конфигурацию приложения удаленного узла. Экземпляр класса ru.funsys.avalanche.sql.Database публикуется в секции <connector> при помощи дочерней секции pulish/ Секция <interface> добавляется в конфигурацию приложения локального узла. В конфигурации приложения локального узла секция с классом ru.funsys.avalanche.sql.Database может отсутствовать.

Пример конфигурации приложения удаленного узла. В ней должны быть определены секция с классом ru.funsys.avalanche.sql.Database и секция <connector>.


	<!-- 
	Сервисные функции работы с БД, источник данных БД определяется в конфигурации 
	контекста WEB приложение (для Tomcat см. вложенный элемент <Resource> секции <context>)
	 -->
	<function class="ru.funsys.avalanche.sql.Database" name="database" description="Функция доступа к БД"
	             resource="java:/jboss/datasources/PostgresDataSource">
	</function>          
	
	<connector class="HttpConnector" name="http-connector">

		<publish name="database" function="database" />

	<connector>

В HTTP коннекторе используется порт HTTP сервера, под управлением которого выполняется приложение.

В параметре function секции <publish указывается имя публикуемой функции. Параметр name секции <publish указывается имя под которым локальная функция будет известна удаленным узлам.

Пример конфигурации приложения локального узла. В ней должны быть определены секция с классом приложения, в которой есть дочерняя секция <adapter> и секция <interface>.


    <interface name="http-interface" uri="http://host:port/context/http-connector"
 	    description="Обмен по HTTP протоколу" />

    <application class="ru.domain.DemoApplication" name="demo"
                 description="Пример определения адаптера">
	          
        <adapter class="ru.funsys.avalanche.sql.Adapter" name="database" uri="http-interface/database" />

    </application>

где:

host - DNS имя или IP адрес удаленного узла;
port - номер HTTP порта удаленного узла;
context - имя контекста WEB приложения (имя WEB приложения);
http-connector - имя HTTP коннектора, указанное в атрибуте name секции <connector> конфигурации приложения удаленного узла;

В параметре uri адаптера указывается пара значений через символ "слеш". Первое значение это имя локального интерфейса. Второе значение это значение атрибута name секции <publish> в конфигурации приложения удаленного узла.

Параметры класса ru.funsys.avalanche.sql.Database

Параметр	Значение по умолчанию	Описание
name		Имя экземпляра в конфигурации приложения
description		Описание экземпляра в конфигурации приложения
logger	ROOT	Имя логгера в конфигурации log4j
timeout	30000	Время ожидания выполнения запроса в параллельном потоке, в мс
limit	300000	Лимит времени выполнения запроса, по истечению которого ожидать завершения выполнения запроса в другом потоке не имеет смысла, в мс
user		Имя пользователя выполнения запроса
using		Пароль пользователя выполнения запроса
readOnly	true	Режим только для чтения
isolation	-1	Используемый уровень изоляции при выполнении выражений select. Значение по умолчанию DEFAULT_TRANSOCTION
transactionIsolation	-1	Используемый уровень изоляции при выполнении транзакции. Значение по умолчанию DEFAULT_TRANSOCTION
useGetParameterType	false	Использовать метод получения типа устанавливаемого параметра в SQL запросах
parameterCase	-1	Тип преобразования параметры запроса метаданных: 0 - к нижнему регистру, 1 - к верхнему

Использование класса MultiDatabase

Для использования класса MultiDatabase необходимо настроить:

Второй источник данных на локальном или удаленном хосте
Второй экземпляр объекта Datasource на локальном или удаленном хосте
При использовании удаленного хоста добавить коннектор и зарегистрировать в нем объект Datasource, на локальном узле добавить интерфейс для работы у удаленным коннектором
В экземпляре объекта MultiDatabase прописать два адаптера на два экземпляра Datasource
В экземплярах функциональных объектов изменить параметр uri адаптера, указать адрес экземпляра MultiDatabase

Рис.3 Логическая схема использования класса MultiDatabase.

Пример секций в конфигурационном файле (определение источников данных не показано, которые зависят от использованного WEB сервера)

	<!-- Секции конфигурации определения экземпляров объектов Database для каждой копии БД       -->

	<!-- Сервисные функции работы с БД, источник данных БД определяется в конфигурации           -->
	<!-- контекста WEB приложение (для Tomcat см. вложенный элемент <Resource> секции <context>) -->
	<application class="ru.funsys.avalanche.sql.Database" name="primaryDatabase" description="Функция доступа к БД Primary"
	             resource="java:/comp/env/jdbc/primaryDS" function="true">
	</application>          

	<application class="ru.funsys.avalanche.sql.Database" name="secondaryDatabase" description="Функция доступа к БД Secondary"
	             resource="java:/comp/env/jdbc/secondaryDS" function="true">
	</application>          

	...
	
	<!-- Определение экземпляра MultiDatabse                                                     -->
	<function class="ru.funsys.avalanche.sql.MultiDatabase" name="multi" description="Функции записи данных в две БД">

		<adapter class="ru.funsys.avalanche.sql.Adapter" name="primary" uri="primaryDatasource" />

		<adapter class="ru.funsys.avalanche.sql.Adapter" name="secondary" uri="secondaryDatasource" />

	</function>          

	...
	
	<!-- Определение экземпляра класса наследника Apllication                                   -->
	<application class="..." name="..." description="Функционал информационной системы">

		<adapter class="ru.funsys.avalanche.sql.Adapter" name="database" uri="multi" />

	</application>          
	
	...