DesignerDeveloperGuide

Среда разработки. Руководство разработчика

Версия 4.6.0

© 2015-2023, ООО "Процессные технологии"

# Обзор

Среда разработки представляет собой RCP-приложение и технологически построен на основе GEF (JPDL) и Graphiti (BPMN). Платформа Eclipse реализует модель сервисов OSGi (OSGi Framework) на платформе Java.

OSGi Framework предоставляет унифицированную среду для работы приложений (называемых bundles), связывающую:

- среду выполнения приложения (Execution Environment);

- модули, дополняющие политики загрузки классов Java private классами для модуля и контролируемым связыванием модулей;

- управление жизненным циклом модулей приложения, позволяющее динамически устанавливать, запускать, останавливать, обновлять и удалять модули;

- сервисы регистрации, обеспечивающие динамическое совместное использование объектов приложениями.

Платформа Eclipse представляет собой набор подсистем, реализованных небольшим исполняемым приложением ядра и набором модулей (плагинов), расширяющих функциональность платформы. В контексте данного документа термины «модуль» и «плагин» равнозначны и взаимозаменяемы. Использование обоих терминов обусловлено главным образом стилистическими соображениями.

Ядро платформы Eclipse в процессе выполнения динамически обнаруживает, конфигурирует и запускает плагины платформы. Eclipse поддерживает динамическое подключение плагинов, описываемых дескрипторами плагинов (файлах MANIFEST.MF и plugin.xml). Для расширения функциональности, плагины платформы в дескрипторах плагинов определяют точки расширения (extension points). Точка расширения представляет собой xml описание интерфейса расширяемого компонента плагина. Расширяющие плагины используют точки расширения для добавления функциональности. Платформа Eclipse не разграничивает плагины, созданные пользователями и плагины самой платформы.

Платформа Eclipse реализована на Java, что обеспечивает переносимость разработанных приложений для работы на разных платформах под различными операционными системами.

GEF предоставляет основу для создания графических редакторов. GEF реализована как набор плагинов расширяющих плагины платформы Eclipse. GEF связывает элементы модели приложения с их графическими представлениями, реализованными с помощью графических компонент библиотеки Draw2d. Контроллеры GEF поддерживают визуальное представление элементов модели в MVC (model-view-controller) архитектуре. Для каждого элемента представления, соответствующий этому представлению контроллер интерпретирует события интерфейса пользователя и трансформирует их в команды обработки соответствующего элемента модели.

Обобщенная архитектура GEF показана на Рис. 1. Назначение компонентов GEF представлено в Табл. 1.

Табл. 1 Компоненты архитектуры GEF.

Компонент	Назначение компоненты
Модель (Model)	Модель представляет собой сохраняемые данные. Модель должна предусматривать механизм уведомления о внесенных изменениях.
Представление (View)	Представление это визуальное отображение модели. Оно состоит из фигур отображающих элементы модели. Модель может быть представлена как графически, так и виде иерархической (древовидной) структуры.
Контроллер (Controller)	Контроллеры связывают элементы модели и соответствующие им элементы представления. В соответствии с представлением контроллеры могут быть графическими или иерархическими. Они ответственны за редактирование элементов модели через представление, а также отображение изменений элементов модели в представлении. Контроллеры используют политики редактирования – элементы, выполняющие большинство задач редактирования.
Действие (Action)	Действия это элементы, обрабатывающие ввод данных. Действия конвертируют события интерфейса пользователя в запросы, которые используют программный интерфейс контроллеров.
Запрос (Request)	Запросы это элементы инкапсулирующие события интерфейса пользователя. Запросы позволяют абстрагироваться от источника события.
Команда (Command)	Команды инкапсулируют данные об изменениях модели. Команды возвращаются контроллерами в ответ на запросы. Команды также содержат информацию о возможности взаимодействия.
Событие (Event)	События это изменения в интерфейсе пользователя, приводящие к изменениям представления или модели.

Рис. 1 Обобщенная архитектура GEF.

Graphiti представляет собой каркас для построения графики, основанный на GEF и EMF.

# Процесс сборки из исходного кода

• jdk8 https://docs.aws.amazon.com/corretto/latest/corretto-8-ug/downloads-list.html
• jdk11 https://docs.aws.amazon.com/corretto/latest/corretto-11-ug/downloads-list.html (для runawfe v4.6.0)
• maven https://dlcdn.apache.org/maven/maven-3/3.6.3/

Исходный код системы доступен в открытом репозитории.

# Сборка с использованием Maven ^4.1.1+

• Загрузите код с помощью Git-клиента из репозитория https://github.com/processtech/runawfe-devstudio
• Выполните команды в папке plugins

mvn clean package

• В случае успешной сборки результаты доступны в папке ru.runa.gpd.maven/target/products

Сборка при запуске из Windows PowerShell не работает по непонятной причине NPE в maven.

# Сборка с использованием Eclipse

# Необходимое программное обеспечение для сборки

Eclipse IDE (требуется редакция для разработчиков Eclipse IDE for RCP and RAP Developers версии 4.9 - 2018-09 - ! именно эта версия).

https://www.eclipse.org/downloads/packages/release/2018-09/r/eclipse-ide-rcp-and-rap-developers

Установить Graphiti из репозитория - в Eclipse IDE -> Help -> Install new software ... найти Graphiti (Incubation)

Установить AspectJ development tools 2.2.4 в Eclipse IDE -> Help -> Eclipse Marketplace ...

# Импорт проектов

Склонируйте репозиторий @git clone https://github.com/processtech/runawfe-devstudio@.

Импортируйте проекты (Import -> Existing projects into workspace) в Eclipse.

• ru.runa.gpd: плагин содержит основные компоненты среды разработки
• ru.runa.gpd.apis_removed_from_j11
• ru.runa.gpd.app: плагин содержит описание продукта (gpd.product)
• ru.runa.gpd.babel.nls_p2_ru.feature
• ru.runa.gpd.connector.wfe.ws: плагин содержит коннектор к runawfe на jboss4 или jboss7
• ru.runa.gpd.eclipse.feature
• ru.runa.gpd.feature
• ru.runa.gpd.form.ftl: плагин содержит графический редактор форм FTL на основе FCKeditor
• ru.runa.gpd.form.quick: плагин содержит декларативный графический редактор форм на основе шаблонов
• ru.runa.gpd.form.quick.feature
• ru.runa.gpd.office: плагин содержит обработчики для работы с Excel, Word
• ru.runa.gpd.platform: плагин содержит описание зависимостей для сборки
• ru.runa.gpd.xpdl: плагин содержит интеграцию с Бизнес-Студио (экспорт процессов из формата XPDL)

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

• ru.runa.gpd.alfresco
• ru.runa.gpd.maven
• ru.runa.gpd.updatesite

Можно воспользоваться встроенным Git-клиентом.

Убедитесь в отсутствии ошибок в проектах.

# Запуск и сборка

Экспорт RCP приложения выполняется на основе файла продукта ru.runa.gpd.app/gpd.product.

Для синхронизации со сборкой maven установите целевую платформу

• откройте файл ru.runa.gpd.platform/platform.target
• нажмите ссылку "Set as active platform",

Дождитесь окончания процесса !.

• нажмите ссылку "Reload Target Platform".

Это также обеспечит локализацию.

# Запуск без сборки (из Eclipse)

На вкладке "Overview" файла ru.runa.gpd.app/gpd.product выбрать ссылку:

• Для запуска в обычном отладки: "Launch an Eclipse application"
• Для запуска в режиме отладки: "Launch an Eclipse application in Debug mode"

Если запуск приложения вызывает ошибку ClassNotFoundException - зайти в Run -> Run configuration-> gpd.product-> plugins выбрать опцию "All workspace and enabled target plug-ins"

# Сборка

На вкладке "Overview" выбрать ссылку "Eclipse Product export wizard". RCP приложение будет экспортировано по заданному пути.

Замечание. Если нужно запустить собранную Среду разработки на языке, отличающимся от языка ОС по умолчанию, то нужно добавить в файл configuration/config.ini параметр osgi.nl. Например для английского языка "osgi.nl=en".

Замечание. Для корректировки параметров JVM нужно в файле runa-gpd.ini добавить строки, например

-vmargs
-Xms512m
-Xmx512m
-Xss1024k

# Обновление списка зависимостей продукта

Среда Eclipse предоставляет возможность заново сформировать список необходимых модулей RCP приложения. Для этого следует:

• удалить все модули выбрав ссылку "Удалить все"
• добавить в пустой список импортированные плагины приложения
• выбрать ссылку "Добавить обязательные модули"
• удалить сохраненную конфигурацию запуска

# Наиболее типичные ошибки

# Не запускается среда разработки (Product ID cannot be found)

выполните обновление зависимостей

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

Добавьте параметр запуска (добавьте в runa-gpd.ini строки)

-vmargs
-Dru.runa.gpd.form.ftl.debug=true

В лог (${GPD}/workspace/.metadata/.log) будут выведены отладочные сообщения, на странице редактора форм будет отображаться отладочные сообщения JavaScript.

# Расширение функциональности среды разработки

Среда разработки предоставляет возможность расширения функциональности базирующейся на eclipse extensions points (Eclipse extension point).

Для начала работы требуется создать новый plug-in проект и добавить в его зависимости необходимые плагины (как минимум те, в которых определены extension points, это ru.runa.gpd, для тегов форм ru.runa.gpd.form.ftl).

Также можно всю работу делать в существующем проекте (например ru.runa.gpd), но изменения в дальнейшем могут быть потеряны при обновлении версии.

Инструкция о том как создавать новый проект, и еще.

Создание (и редактирование) расширений производится стандартным способом.

Рассмотрим на примере добавления нового FTL тега.

Откройте файл plugin.xml, перейдите на вкладку Extensions, добавить и выберите ru.runa.gpd.form.ftl.tags (если его нет в списке – удостоверьтесь что плагин, объявляющий данную точку расширения находится в зависимостях разрабатываемого плагина)

Действия добавить, удалить элемент дерева (кроме корня – ссылки на точку расширения) производятся в контекстном меню по правой кнопке на выбранном элементе (на рисунке мы добавляем параметр к тегу).

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

После проделанной работы новый плагин необходимо включить в сборку Среды разработки, это можно сделать 2-мя способами:

• в файле ru.runa.gpd/gpd.product на вкладке "Конфигурация" добавить плагин и собрать среду разработки заново
• собрать плагин независимо (из plugin.xml, вкладка "Обзор" -> "Мастер экспорта") и собранный плагин зарегистрировать в существующей Среде разработки

# Типы форм

В данный момент поддерживаются следующие типы форм:

• FTL (HTML + Freemarker)
• HTML (HTML + vartags, только для обеспечения совместимости с версией 3 в режиме только чтение)
• Quick (форма на основе FTL шаблона)

Этот список можно расширить собственным типом формы.

Схема точки расширения: ru.runa.gpd.formtype

• element[@name] – название типа формы
• element[@contributor] – класс, расширяющий ru.runa.gpd.form.FormType
• element[@type] – расширение файлов формы

Описание методов ru.runa.gpd.form.FormType

 IEditorPart openForm(IFile formFile, FormNode formNode) 

Открывает форму для редактирования

- Map<String, Integer> getFormVariableNames(IFile formFile, FormNode formNode)

Возвращает список переменных из формы в виде Название – Тип использования {чтение, запись, не удалось определить}

void validate(IFile formFile, FormNode formNode)

Осуществляет проверку формы

# Элементы языка исполнения процессов

Это элементы, доступные из палитры Среды разработки (как в JPDl так и в BPMN).

Схема точки расширения: ru.runa.gpd.elements

• element[@model] - класс модели, наследник ru.runa.gpd.lang.model.GraphElement
• element[@icon] – рисунок в палитре
• element[@label] – текст в палитре
• element[@type] – тип элемента (блок или переход)
• element[@bpmn] – идентификатор элемента языка BPMN (если он фигурирует в этом языке)
• element[@jpdl] – идентификатор элемента языка JPDL (если он фигурирует в этом языке)

• element/gef[@graphicalEditPart] – отвечает за отображение на графе элемента языка JPDL
• element/gef[@treeEditPart] – отвечает за отображение в дереве схемы элемента языка JPDL
• element/gef[@figure] – отвечает за отрисовку на графе элемента языка JPDL

• element/graphiti[@create] – класс, отвечающий за создание элемента
• element/graphiti[@add] – класс, отвечающий за добавление элемента на граф
• element/graphiti[@update] – класс, отвечающий за обновление элемента
• element/graphiti[@layout] – класс, отвечающий за компоновку элемента на графе
• element/graphiti[@fizedSize] – имеет ли данный элемент фиксированный размер
• element/graphiti[@width] – ширина элемента при создании, в единицах сетки
• element/graphiti[@height] – высота элемента при создании, в единицах сетки

# Обработчики

# Способ регистрации обработчиков через настройки Среды разработки

В разработке.

# Способ с использованием механизма расширений

Используя механизм eclipse extensions можно добавить обработчики в любой плагин.

Схема точки расширения: ru.runa.gpd.handlers

• delegable[@className] – полное название класса обработчика на стороне сервера
• delegable[@actionHandler] – может ли данный обработчик быть использован в элементах "Обработчик", "Задача сценария"?
• delegable[@assignmentHandler] – может ли данный обработчик быть использован для назначения роли?
• delegable[@botTaskHandler] – может ли данный обработчик быть использован для работы бота?
• delegable[@decisionHandler] – может ли данный обработчик быть использован для принятия решения в элементе "Ветвление"?
• delegable[@label] – отображаемое название в Среде разработки
• delegable[@cellEditorProvider] – класс, расширяющий ru.runa.gpd.extension.DelegableProvider, позволяет создать UI для редактирования конфигурации.

# Использование конфигуратора с декларативным заданием конфигурации обработчика

Использование в качестве cellEditorProvider класс ru.runa.gpd.extension.handler.ConfigBasedProvider позволяет задать конфигурацию с помощью XML-файла (описания структуры конфигурации). Файл должен находиться в папке conf того же плагина, где определено расширение и иметь название simpleClassName.xml, где simpleClassName - название класса обработчика без указания пакета.

На стороне сервера обработчик может наследоваться от ru.runa.wfe.extension.handler.CommonParamBasedHandler, который настроен на работу с конфигурацией со структурой XML, генерируемой ru.runa.gpd.extension.handler.ConfigBasedProvider в Среде разработки.

Замечание: Для обработчиков ветвлений delegable[@cellEditorProvider] должен реализовывать интерфейс ru.runa.gpd.extension.decision.IDecisionProvider.

# Организационные функции (ru.runa.wfe.extension.OrgFunction)

Используются в инициализаторе роли.

Схема точки расширения: ru.runa.gpd.orgfunctions

• orgfunction[@className] – полное название класса орг. функции
• orgfunction[@label] – название, используется для отображения в Среде разработки
• orgfunction/parameter – определение параметров орг. функции
• orgfunction/parameter [@name] –название, используется для отображения в Среде разработки
• orgfunction/parameter [@type] – тип переменных, которые могут быть использованы в качестве динамического значения параметра
• orgfunction/parameter [@value] – начальное значение параметра
• orgfunction/parameter [@multiple] – если значение установлено в true, то таких параметров может быть несколько подряд.

Замечание: orgfunction/parameter [@multiple] может быть установлено в true только для последнего параметра.

# Конструкторы ролей

Откройте Среду разработки, Роли, кнопка изменить. Появится диалоговое окно с редактированием инициализатора роли. Оно имеет древовидную структуру со степенью вложенности 2 (корневая – переход по табам, вторая – раскрывающиеся блоки в содержимом таба). Элементы GUI, открывающиеся в блоках могут быть добавлены в этот диалог.

См. схему точки расширения: ru.runa.gpd.swimlaneelements

# Валидаторы

Используются для проверки переменных.

Замечание: в данный момент нельзя добавить новый глобальный валидатор (имеется только валидатор, основанный на Groovy).

Схема точки расширения: ru.runa.gpd.validators

• validator[@name] – название валидатора, на сервере по нему должно быть соответствие в файле конфигурации validators.xml
• validator[@label] – отображаемое имя
• validator[@description] - отображаемое описание
• validator[@applicable] – типы переменных, к которым может быть применен данный валидатор. Множественные значения указываются через запятую, например. Пустое значение означает все типы. Значением являются полное название java класса (например java.lang.Long), иерархия наследования поддерживается.
• validator/param – параметры валидатора
• validator/param[@name] – название параметра. В классе валидатора по этому имени доступно значение параметра.
• validator/param[@label] – отображаемое имя
• validator/param[@type] – тип значения параметра

# Форматы (типы) переменных

См. соответствующий раздел в руководстве по работе с переменными.

# Freemarker теги

В терминах freemarker теги являются методами, которые на сервере при отображении формы исполняются и на выходе дают некий HTML.

Схема точки расширения: ru.runa.gpd.form.ftl.tags

• tag[@id] – название тега, на сервере должно быть соответствие в файле конфигурации ftl.form.tags.xml
• tag[@name] – отображаемое имя тега
• tag[@image] – путь к рисунку тега, отображаемому в графическом редакторе
• tag[@width], tag[@height] – размеры рисунка
• tag/param[@name] - отображаемое имя параметра
• tag/param[@type] – тип отображения параметра (text – поле ввода значения, combo – выбор из фиксированного списка, varcombo – выбор из списка переменных, richcombo – выбор из списка переменных с возможностью ввести фиксированное значение)
• tag/param[@variableAccess] – задействована ли переменная в данном параметре и как (запись, чтение). Используется для поиска переменных формы
• tag/param[@variableTypeFilter] – фильтр по типу списка переменных
• tag/param/paramValue – статические значения параметра в списке. Действуют при пустом значении tag/param[@values] и tag/param[@type] = combo
• tag/param/paramValue[@name] – отображаемое имя
• tag/param/paramValue[@value] – значение выбранной опции

# Добавление нового пункта меню

Откройте файл plugin.xml плагина ru.runa.gpd в редакторе манифеста модуля.

Создайте элемент меню. Для этого в контекстном меню элемента "Главное меню" (main menu) точки расширения org.eclipse.ui.actionSets последовательно выбрать пункты "Создать" (New), затем "menu". Редактор манифеста модуля создаст новый элемент расширения menu, а в правой части окна редактора отобразятся свойства этого элемента:

• id – уникальный идентификатор элемента;
• label – метка отображаемая на элементе;
• path – путь локализации пункта меню в структуре меню.

Добавьте элемент сепаратор в созданный пункт меню. Для того, чтобы созданный пункт меню мог использоваться для расширения другими плагинами, сепаратор должен иметь имя "additions".

В контекстном меню элемента "Главное меню" (main menu) точки расширения org.eclipse.ui.actionSets последовательно выбрать пункты "Создать" (New), затем "action". Редактор манифеста модуля создаст новый элемент расширения action, а в правой части окна редактора отобразятся свойства этого элемента:

• id – уникальный идентификатор элемента;
• label – метка отображаемая на элементе;
• accelerator – устаревшее, не рекомендуется использовать (Deprecated);
• definitionId – идентификатор команды связанной с данным действием;
• menubarPath – путь локализации действия в структуре меню;
• toolbarPath – путь локализации действия в линейке инструментов;
• icon – относительный путь к файлу, содержащему изображение для данного элемента;
• disabledIcon – относительный путь к файлу, содержащему изображение для неактивного элемента;
• hoverIcon - относительный путь к файлу, содержащему изображение для элемента, когда указатель мыши находится над ним;
• tooltip – текст всплывающей подсказки;
• helpContextId – идентификатор контекстной справки;
• style – атрибут представления действия (push, radio, toggle, pulldown);
• state – необязательный атрибут начального состояния;
• pulldown – устаревшее, не рекомендуется использовать (Deprecated);
• class – полный путь к классу обработчику действия. Класс должен реализовывать интерфейс org.eclipse.ui.IWorkbenchWindowActionDelegate или org.eclipse.ui.IWorkbenchWindowPulldownDelegate. Если атрибут retarget установлен в true, данный атрибут игнорируется;
• retarget – если данный атрибут установлен в true, используется глобальный обработчик действия;
• allowLabelUpdate – используется если атрибут retarget установлен в true. Если данный атрибут установлен в true то label и tooltip данного действия замещаются атрибутами глобального обработчика;
• enablesFor – если данный атрибут не задан, он игнорируется. Определяет сколько элементов должно быть выбрано, чтобы выполнить данное действие.

После введения полного пути классу обработчику действия (атрибут class), выбрать ссылку class. В результате среда Eclipse сгенерирует класс обработчик действия по введенному пути, содержащий методы-заглушки. Для задания функциональности действия необходимо реализовать функциональность этих методов.

# Добавление плагина расширения в Среду разработки

# Способ 1. Используя копирование в папку plugins ^4.1.1-

1. В файле configuration/config.ini измените свойство org.eclipse.update.reconcile=true
2. Скопируйте плагин (jar файл или папку) в директорию plugins
3. Запустите среду разработки

В случае проблем запустите среду разработки командой

runa-gpd -clean -console

и далее в консоли посмотрите статус плагина командой

ss

# Способ 2. Используя OSGi консоль

Запустите среду разработки командой

runa-gpd -console

Далее в консоли

install file:///path/to/plugin.jar
start <BundleId>, где <BundleId> - идентификатор плагина после инсталляции

После этого при перезапуске среды разработки (без опции -clean) он должен быть запущен. Если автозапуск не действует - диагностируйте в консоли

diag <BundleId>

# Code

BundleContext bundleContext = plugin.getBundle().getBundleContext();
Bundle bundle = context.installBundle("file:///path/to/plugin.jar");
bundle.start();