Перейти к основному содержанию
`Ctrl`+`K`

# Начало работы с фреймворком

## Требования к аппаратному обеспечению рабочего места разработчика

Характеристика сервера | Рекомендуемые параметры
--- | ---
ОС | Linux (Debian, Astra, Alt), Windows 10 и выше
CPU | 8 ядер 3.5 GHz или более
Оперативная память | 16 – 32 Gb или более
Память | SSD 20 Gb свободного места
Монитор | разрешение 1920×1080

Использование виртуальной машины может заметно снизить производительность при сборке и отладке проекта.

## Создание новой БД для проекта

Для создания базы данных используется команда `CREATE DATABASE`, после которой указывается название базы данных.

Для выполнения запросов будем использовать графический клиент pgAdmin, хотя также можно использовать консольный клиент psql.

Создадим для проекта нового пользователя бд и базу данных, например:

    Логин: sampleproject
    Пароль: sampleproject

    БД: sampleproject

Чтобы создать нового пользователя и новую БД:

1. Откройте pgAdmin.

2. Подключитесь под суперпользователем к СУБД.

3. В левой части программы выберите базу данных `postgres`

4. Выделите ее и правой кнопкой мыши запустите инструмент Query Tool

### Создание пользователя

В центральной части программы откроется поле для ввода кода SQL.

1. В окно запроса введите следующий код:

       CREATE ROLE sampleproject WITH
           LOGIN
           NOSUPERUSER
           NOCREATEDB
           NOCREATEROLE
           INHERIT
           NOREPLICATION
           CONNECTION LIMIT -1
           PASSWORD 'sampleproject';

       GRANT pg_signal_backend TO "sampleproject";

2. Для создания пользователя выполним операцию `Execute/refresh`.

### Создание БД

1. В окно запроса введите следующий код:

       CREATE DATABASE "sampleproject"
           WITH
           OWNER = "sampleproject"
           ENCODING = 'UTF8'
           CONNECTION LIMIT = -1;

2. Для создания выполните операцию `Execute/refresh`.

### Подключение расширений

К созданной БД необходимо подключить расширения, которые использует система `Global`.

Для этого:

1. Обновите список баз

2. В левой части программы выберите базу данных `sampleproject`

3. Выделите ее и правой кнопкой мыши запустите инструмент Query Tool

4. В окно запроса введите следующий код:

       CREATE EXTENSION if not exists plpgsql;
       CREATE EXTENSION if not exists fuzzystrmatch;
       CREATE EXTENSION if not exists pg_trgm;
       CREATE EXTENSION if not exists pg_stat_statements;
       CREATE EXTENSION if not exists "uuid-ossp";
       CREATE EXTENSION if not exists dict_xsyn;
       CREATE EXTENSION if not exists ltree;

5. Для подключения расширений выполните операцию `Execute/refresh`.

## Настройка рабочего места

### Развёртывание рабочего места под Windows

### Развёртывание рабочего места под Astra Linux

### Развёртывание рабочего места под Alt Linux

## Прикладной проект

Прикладной проект собирает конечное решение из набора прикладных модулей. Собранное решение разворачивается на сервере приложения для работы с пользователями.

### Структура проекта

- Проект(Application)

  - `build.sbt`
    Настройка сборки проекта

  - project
    Дополнительные настройки проекта

  - `модуль`

    - `src.main.java`

    - `src.main.scala`

      - `ru.bitec.app.[модуль]`
        Файлы модуля компилируемые языком scala

    - `src.main.resources`

      - `META-INF\module-info.xml`
        Мета данные о модуле

      - `ru.bitec.app.[модуль]`
        Файлы модуля не требующие компиляции

    - build.sbt
      Файл сборки модуля

  - `модуль_N`

  - `модуль_N+1`

Внимание

`ru.bitec.app.[moduleName]` – это отдельные каталоги!

Точка в именах директорий запрещена! IDE Intellij Idea в обозревателе проекта группирует каталоги через точку для удобства просмотра

### Модуль

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

Для включения модуля в сборку необходимо объявить его и включить в агрегацию в корневом build.sbt проекта application.

Модуль представляет собой некоторую неделимую совокупность функциональности системы, которая может быть включена в тот или инной прикладной проект.

Каждый объект, зарегистрированный в системе, принадлежит какому-либо модулю.

Основными составляющими модуля являются классы, выборки и серверные методы, группированные в пакеты.

#### Структура каталогов модуля

`[moduleName]`
Директория модуля разбита на строгую иерархию:

- `[moduleName]/src/main/java/ru/bitec/app/[moduleName]`
  Содержит java сущности модуля: pojo классов, перечисления и т.д. Чаще всего сущности создаются автоматически генератором кода.

- `[moduleName]/src/main/resources/META-INF`
  Содержит метаинформацию модуля: Описание, версию, зависимости, перечень приложений.

- `[moduleName]/src/main/resources/orm`
  Содержит индексные файлы ORM.

- `[moduleName]/src/main/resources/ru/bitec/app/[moduleName]`
  Содержит файлы моделей Odm, Orm, Dvm, Avm

- `[moduleName]/src/main/scala/ru/bitec/app/[moduleName]`
  Содержит файлы прикладной бизнес-логики и контроллера view, пакетов: Dvi, Dpi, Api, Avi, Pkg

- `[moduleName]/src/test/scala/ru/bitec/app/[moduleName]`
  Содержит юнит-тесты прикладных методов

#### Зависимости

Модуль может использовать или требовать наличия некоторого набора других модулей. Это требование выражается в том, что объекты или функциональность, заложенная в модуль, не будут работать в случае отсутствия в системе другого, требуемого модуля.

Зависимости позволяют увеличить повторное использование кода, за счет выделения часто используемого функционала в низкоуровневые модули.

Базовые модули:

- gtk
  Обеспечивает интеграцию с сервером приложения

- btk
  Основная функциональность фреймворка, доступная всем более высокоуровневым модулям.

Эти модули не требуют для своей работы наличия других модулей, являясь платформой системы.

Зависимость модулей описывается в файле настроек сборки build.sbt для модуля.

##### Подключение внешних библиотек

Допускается подключение к прикладным модулям внешних библиотек (`*.jar`). В файле build.sbt прикладного проекта необходимо прописать зависимость модуля от этих библиотек.

    lazy val bts = project.
      dependsOn(btk).
      settings(CommonSetting.setting: _*).
      settings(
      libraryDependencies ++= Seq(
        "org.apache.httpcomponents" % "httpmime" % "4.5.2",
        "org.apache.httpcomponents" % "httpcore" % "4.4.5",
        "org.apache.httpcomponents" % "httpclient" % "4.5.2" )
      )

Если подключаемая библиотека опубликована в нестандартном репозитории, необходимо объявить путь к этому репозиторию.

    lazy val btk = project.
      dependsOn(gtk).
      settings(commonSettings: _*).
      settings(
        resolvers += "nuiton-maven" at
          "https://nexus.nuiton.org/nexus/content/groups/releases/",
        libraryDependencies += "nl.knaw.dans.common" % "dans-dbf-lib" % "1.0.0-beta-10"
      )

Если объявить зависимость с двумя символами «%», в качестве разделителя:

`"nl.knaw.dans.common" %% "dans-dbf-lib" % "1.0.0-beta-10"`

к имени библиотеки будет добавляться суффикс с версией scala.

Все библиотеки зависимостей из списка «libraryDependencies» копируются в каталог `.commonlib`.

За формирование каталога `.commonlib` отвечают sbt-задания `publishLibDependencies` и `publishDevDependencies`, выполняемые в зависимости от режима сборки проекта автоматически или вручную.

Внимание

При выполнении sbt задачи `publishDevDependencies` в Intellij Idea может выдаваться ошибка вида:

    [error] download error: Caught javax.net.ssl.SSLHandshakeException:
    sun.security.validator.ValidatorException: PKIX path building failed:
    sun.security.provider.certpath.SunCertPathBuilderException: unable to
    find valid certification path to requested target
    (sun.security.validator.ValidatorException: PKIX path building failed:
    sun.security.provider.certpath.SunCertPathBuilderException: unable to
    find valid certification path to requested target) while downloading
    https://ivy.global-system.ru/

Ошибка проверки возникает из-за того, что в хранилище доверенных корневых сертификатов Java нет CA-сертификата промежуточного сервера для let’s encrypt.

Исправить ошибку можно следующим образом:

1. Добавить сертификат в стандартное хранилище доверенных CA-сертификатов
   Для Java приложений сгенерировать новый CA-сертификат R3 для Let’s Encrypt можно с помощью утилиты keytool.
   Java Keytool — это инструмент командной строки, который может генерировать пары открытый ключ / закрытый ключ и сохранять их в хранилище ключей. Исполняемый файл утилиты распространяется вместе с Java SDK (или JRE)
   пример использования:

       keytool -importcert -file mycertfile.pem -keystore cacerts -alias "Alias"

   Стандартный пароль хранилища: changeit

2. Заменяем хранилище
   `C:\Program Files\Java\jdk[версия]\jre\lib\security\cacerts` файлом из архива `Global3FrameworkStarterKit.zip`

## Первая сборка проекта

Когда проект открывается впервые, IDE Intellij Idea проиндексирует его состав и выполнит обновление sbt проекта. После этого необходимо выполнить агрегацию библиотек проекта и собрать проект.

1. Дождитесь окончания инициализации проекта и индексации исходного кода

2. Обновите sbt проект

3. Выполните агрегацию библиотек проекта
   Для этого запустите на панели sbt задачу `publishDevDependencies`
   При этом sbt задача просканирует проект на наличие зависимостей и сформирует в корне проекта каталог `.commonlib` со всеми необходимыми библиотеками.

   Внимание

   При выполнении sbt задачи `publishDevDependencies` в Intellij Idea может выдаваться ошибка вида:

       [error] download error: Caught javax.net.ssl.SSLHandshakeException:
       sun.security.validator.ValidatorException: PKIX path building failed:
       sun.security.provider.certpath.SunCertPathBuilderException: unable to
       find valid certification path to requested target
       (sun.security.validator.ValidatorException: PKIX path building failed:
       sun.security.provider.certpath.SunCertPathBuilderException: unable to
       find valid certification path to requested target) while downloading
       https://ivy.global-system.ru/

   Ошибка проверки возникает из-за того, что в хранилище доверенных корневых сертификатов Java нет CA-сертификата промежуточного сервера для let’s encrypt.
   Для исправления ошибки замените хранилище `C:\Program Files\Java\jdk\[версия]\jre\lib\security\cacerts` файлом из архива `Global3FrameworkStarterKit.zip`

4. Выполнить сборку проекта: Build | Build Project

## Развертывание первоначальных данных

Для генерации начальных данных в БД проекта необходимо провести успешную сборку проекта и запустить утилиту создания таблиц.

1. Если требуется сборка проекта, выполните команду `Build project`
   Пункт меню Intellij Idea: `Build > Build Project`

2. После сборки проекта запустите генерацию таблиц
   В обозревателе проекта Intellij Idea вызовите контекстное меню на корневой директории проекта `application` пункт `External Tolls > Generate tables`
   При этом происходит создание таблиц схемы, установка начальных данных и создается пользователь admin с полными правами(пароль admin)

После этого конфигурация готова для разработки.

## Запуск приложения

Для запуска и отладки приложения вам необходимо ознакомиться с основными принципами запуска и отладки в idea

Для отладки проекта:

1. Выберите в выпадающем списке конфигураций запуска `Global 3 SE`
   Данная конфигурация создается автоматически дополнительным плагином. Конфигурация появляется при следующем запуске idea. В случаи если плагин не установлен, конфигурацию для запуска необходимо создать вручную.

2. Выполните Debug `Global 3 SE`

3. Подключитесь к запущенному серверу
   Для этого откройет браузер по адресу `http://localhost:8080/`

При этом в консоли будет выводиться лог работы сервера. При запуске не должно быть сообщений с типом `[ERROR]` или стеков ошибок.

## Регистрация

При первом запуске система Global Postgres потребует зарегистрировать БД Для регистрации базы данных.

1. Сформируйте файл запроса лицензии
   Для формирования файла запроса лицензии необходимо нажать на кнопку «Сформировать и скачать файл запроса лицензии».

2. Запросите лицензионный файл
   Сформированный файл запроса лицензии вместе с заявкой на регистрацию отправьте по электронной почте контактному лицу ООО «Бизнес-Технологии». В заявке рекомендуется указать имена модулей, которые будут созданы.

3. Зарегистрируйте лицензию
   Для этого в диалоге требования регистрации нажмите на кнопку `Установить лицензионный файл`, и выберете полученный файл в открывшемся диалоге.

## Отладка приложений

Для отладки прикладного кода:

1. Откройте файл с кодом для отладки

2. Установите точку остановки на требуемой строке

3. Откройте приложение в браузере и выполните отлаживаемое действие
   Выполнение программы будет остановлено на отмеченной строке.

### Отладка бизнес-логики

Для отладки и тестирования кода Dpi/Api-классов можно воспользоваться Unit-тестами. Для этого, в каталоге с тестами соответствующего модуля создайте класс, унаследованный от `ru.bitec.app.gtk.eclipse.api.ApiTest`.

Смотрите пример: `ru.bitec.app.cur.Cur_CurrencyTest`

### Перекомпиляция кода без перезапуска сервера

При отладке приложений, в большинстве случаев, нет необходимости перезапуска веб-сервера при внесении изменений в код любого модуля проекта Application. Для применения изменений необходимо:

1. Выключите кэш
   Выполните пункт меню `Файл \ Использовать кэш` в отлаживаемом приложении

2. Скомпилируйте изменённый модуль
   `Compile module` в контекстном меню модуля или `Build project` на панели инструментов. В отдельных случаях можно компилировать отдельный класс.

3. Обновите приложение
   В главном меню отлаживаемого приложения выполнить `Файл \ SBT \ Обновить и переоткрыть текущую форму`

4. Повторите отлаживаемое действие.

### Отладка выборки

Для отладки пользовательских интерфейсов предусмотрен специальный инструмент `Selection debug window`. Вызвать его можно в любом месте системы с помощью сочетания клавиш `ctrl+alt+shift+W`.