Разработка плагина

• Архитектура системы
• Сборка системы
• Архитектура плагинов
• Разработка плагина
• Компоненты плагина
• Подключение плагина к проекту Maven
• Взаимодействие между плагином и ядром
• Front-End
• Локализация
• Миграция базы данных
• API для мобильных приложений
• Доработка ядра

Компоненты плагина

Плагин (серверная часть) является Maven-модулем и включает в себя следующие компоненты:

• Схема БД, включающая, как минимум, регистрацию плагина в таблице plugins.
• Код Back-End:
• Код работы с моделями данных
• Реализация интерфейса PluginConfiguration
• Реализация API для доступа клиентского компонента (при необходимости)
• Код Front-End

Нужно выбрать уникальный идентификатор плагина, который не должен совпадать с идентификаторами уже имеющихся плагинов. Такой идентификатор должен использоваться при именовании различных артефактов, относящихся к функционированию плагина, во избежание конфликтов с другими плагинами. Такие артефакты включают в себя названия объектов БД, создаваемых и управляемых плагином, URI для HTTP API, предоставляемого плагином и т.д.

Код плагина нужно размещать в директории с названием – идентификатором плагина, в папке plugins. Структура директорий описана в предыдущем разделе.

Подключение плагина к проекту Maven

Для подключения плагина к проекту нужно выполнить следующие шаги:

• Добавить элемент dependency, ссылающийся на плагин, в конфигурацию Maven для основного веб-приложения (server/pom.xml).

  <dependency>
  <groupId>com.hmdm.plugin</groupId>
  <artifactId>yourProjectName</artifactId>
  <version>0.1.0</version>
  <scope>runtime</scope>
  </dependency>
  

  Примечание: в файле server/pom.xml эти элементы записаны в одну строку. Это делать не обязательно, так как используется только в служебных скриптах Headwind MDM.

• Добавить элемент module в файл plugins/pom.xml.

Взаимодействие между плагином и ядром

Для использования плагина ядром плагин должен реализовать интерфейс com.hmdm.plugin.PluginConfiguration.

Данная реализация должна предоставить ядру системы текстовый идентификатор плагина, а также список Guice-модулей, инициализирующих плагин.

При старте основного веб-приложения код инициализации приложения создаст экземпляр класса, реализующего интерфейс com.hmdm.plugin.PluginConfiguration и загрузит его модули в Guice-контейнер для дальнейшего использования.

Front-End

При инициализации основного веб-приложения, оно загрузит список доступных плагинов с сервера, и для каждого из плагинов произведет загрузку JavaScript-модуля плагина с сервера.

Front-End модуль плагина должен удовлетворять следующим требованиям для интеграции с основным веб-приложением:

• Если плагин содержит UI, доступный для выбора из пункта меню «Функции» основного веб-приложения, то Angular-модуль плагина должен добавить состояние с именем вида plugin-<pluginname> в $stateProvider основного приложения по следующему образцу (на примере плагина «Messaging»):



В этом случае основное веб-приложение добавит соответствующий пункт в меню «Функции», при выборе которого пользователем будет открываться соответствующая страница, предоставленная плагином.



• Если плагин содержит UI, доступный для выбора из пункта меню «Настройки» основного веб-приложения, то Angular-модуль плагина должен добавить состояние с именем вида plugin-settings-<pluginname> в $stateProvider основного приложения по следующему образцу (на примере плагина «Messaging»):



В этом случае основное веб-приложение добавит соответствующий пункт в меню «Настройки», при выборе которого пользователем будет открываться страница настроек, предоставленная плагином.



• Angular-модуль плагина может также добавить обработчик с именем вида plugin-<pluginname>-device-selected в $rootScope основного веб-приложения. Этот обработчик будет вызываться каждый раз, когда на вкладке «Устройства» основного приложения пользователь будет выбирать какое-либо устройство для просмотра данных плагина, относящихся к этому устройству. Данные выбранного пользователем устройства будут передаваться обработчику в качестве параметра, и задача такого обработчика состоит в перенаправлении пользователя на соответствующую страницу, предоставляемую плагином.

Локализация

Для инициализации модуля локализации, нужно выполнить вызов localization.loadPluginResourceBundles в методе .run модуля плагина.

Строки для локализации должны находиться в файлах i18n/xx_XX.json и содержать в себе подстроку plugin.<pluginname> (чтобы избежать пересечений с другими строками в проекте).

Миграция базы данных

Плагин ответственен за создание и миграцию той части базы данных, которая относится к функциональности плагина. Создание и миграция схемы БД для хранения данных плагина осуществляется с помощью средств библиотеки управления миграциями БД Liquibase.

Соответственно, плагин должен предоставить ресурсный файл журнала миграции БД в формате, требуемом для Liquibase, и класс, наследующий от com.hmdm.guice.module.AbstractLiqubaseModule, который должен быть включен в список Guice-модулей, возвращаемых конфигурацией плагина.

Проект предъявляет следующие требования к наименованию объектов БД для избежания конфликтов между разными плагинами:

• Наименования всех записей журнала миграции БД должны начинаться с plugin_<pluginname>_
• Наименования всех объектов БД (таблицы, индексы, ограничения и т.д.) должны начинаться с plugin_<pluginname>_
• Журнал миграции БД для плагина в обязательном порядке должен содержать запись, регистрирующую плагин в таблице plugins. В этой регистрационной записи необходимо указать:
• Идентификатор плагина
• Наименование (оно также будет использоваться в качестве текста для пунктов меню, относящихся к плагину)
• Описание плагина (опционально)
• Путь к JavaScript-файлу, содержащему Angular-модуль плагина
• Путь к HTML-шаблону для страницы, доступной из меню «Функции» основного веб-приложения (если такая страница предоставляется плагином)
• Путь к HTML-шаблону для страницы, доступной из меню «Настройки» основного веб-приложения (если такая страница предоставляется плагином)
• Наименование прав (permissions) для ограничения доступа к страницам настроек и функций плагина, если необходимо.

API для мобильных приложений

Для приёма и обработки запросов от мобильных устройств плагины могут предоставлять точки доступа с использованием REST-котроллеров.

Основное требование к HTTP API, предоставляемому плагином, заключается в том, что все такие точки доступа должны иметь URI, организованные как /rest/plugins/<pluginname>/ во избежание конфликтов с HTTP API, предоставляемыми другими плагинами.

Например, для загрузки фотографий мобильными устройствами плагин «Фотографии» предоставляет точку доступа с URI в виде /rest/plugins/photo/photo/upload.

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