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

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

Характеристика сервера

Рекомендуемые параметры

ОС

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

pgAdminQueryTool

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

В центральной части программы откроется поле для ввода кода 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.

pgAdminQueryTool

Создание БД#

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

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

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

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

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

Для этого:

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

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

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

  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.

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

Установка#

  1. Установите IntelliJ IDEA Community Edition

  2. Установите в IDE IntelliJ IDEA SCALA Plugin

  3. Установите Global3FrameworkStarterKit

  4. Распакуйте архив с дистрибутивом сервера приложений globalserver.zip в директорию C:\Global3se

  5. Скорипуйте проект в директорию C:\Projects\projectName

Настройка переменных окружения Windows#

Добавьте переменные окружения Windows:

  • G3_HOME = C:\Global3se
    Путь к каталогу, в который разархивирован дистрибутив Global 3SE

  • G3_PUBLISH = C:\Global3se\application
    Путь к каталогу, в который будет производиться сборка проекта

Настройка проекта#

Настройку проекта можно сделать в ручном и автоматическом режиме с помощью gsf-cli - утилиты командной строки Global System Framework

Развертывание вручную#

  1. Откройте в IDE Intellij Idea проект
    Для примера будем использовать путь: C:\Projects\SampleProject\application

  2. Откройте файл C:\Projects\SampleProject\application\project\orm\config\persistence.xml

  3. Поменяйте параметры соединения с БД Postgres проекта для persistence-unit pgdev: \

     <property name="eclipselink.jdbc.url" value="jdbc:postgresql://pgProject:5432/sampleProject"/>
 <property name="eclipselink.jdbc.driver" value="org.postgresql.Driver"/>
 <property name="eclipselink.jdbc.user" value="sampleproject"/>
 <property name="eclipselink.jdbc.password" value="sampleproject"/>

    Где:
    eclipselink.jdbc.url – строка соединения
    eclipselink.jdbc.driver – драйвер jdbc
    eclipselink.jdbc.user – пользователь бд
    eclipselink.jdbc.password – пароль

Конфигурация Global Server#

Перед запуском Global Server необходимо добавить информацию о проекте в конфигурационный файл. Для этого:

  1. Откройте файл C:\Global3se\application\config\global3.config.xml в текстовом редакторе

  2. В раздел databases добавьте новую базу данных

     <?xml version="1.0"?>
 <database alias="SampleProject" 
             driver="org.postgresql.Driver" 
             schema="PUBLIC" 
             url="jdbc:postgresql://pg12:5432/sampleProject" 
             connectionType="proxyShared" 
             authenticationType="btk">
     <users>
         <!--user определяет схему-->
         <user name="sampleProject" password="sampleProject"/>
     </users>
     <metaManager mode="Xml" 
                 defaultNamespace="ru.bitec.app.btk" 
                 sbtName="SampleProject_sbt"/>
     <eclipseLink persistenceUnitName="pgdev" autoCommit="false"/>
 </database>

  3. В раздел sbts добавьте конфигурацию sbt

     <sbt name="SampleProject_sbt"
     source="C:\Projects\SampleProject\application"
     sourceMode="Dev"
     sbtMode="External"
     gitPullOnSbtStart="false"
     binaryFolder="c:\Global3se\application\appbin"
 >
 </sbt>

  4. В разделе development включить режим конфигуратора

     <development>
     <!--enabled - режим отладки. Делает видимым панель отладки в главном
         меню приложения-->
     <debugMode enabled="true"/>
     <!--enabled - Доступность флага "Конфигуратор" в диалоге
         подключения-->
     <configurator enabled="true"/>
 </development>

gsf-cli - утилита командной строки Global System Framework#

gsf-cli - утилита командной строки Global System Framework предназначена для автоматизации работы разработчика

Инструкция по развертыванию проекта в автоматическом режиме Командная утилита G3Server

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

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

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

  • Проект(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 проект
    refreshSBT

  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.