Данное руководство показывает процесс создания простейшего сервиса с Javascript-интерфейсом на платформе IACPaaS. В конечном итоге разработчик получит сервис со следующим интерфейсом:
Целевой сервис
Этот сервис демонстрирует следующие возможности:Далее в руководстве по шагам описываются все этапы создания сервиса, начиная с создания инфоресурса сервиса и заканчивая программным кодом интерфейса на Javascript.
Создание нового инфоресурса типа «Сервис» выполняется в личном фонде («Мой Фонд»). В рамках данного руководства это выполняется в папке «Сервисы». В начале необходимо нажать на кнопку с плюсом:
Создание инфоресурса сервиса
После этого отображается диалог создания узла:
Создание узла
Здесь на первом шаге нужно выбрать тип «Единица Хранения» и либо нажать кнопку «вперед», либо кнопку «Параметры».
После этого отображается второй шаг – «Параметры»:
Параметры создания узла
Так как создается сервис, то требуется выбрать «Сервис». Далее – ввести название («AbstractUITest») и описание в текстовые поля и нажать кнопку «сохранить».
По аналогии с созданием сервиса создается инфоресурс решателя (узел) – с помощью кнопки «плюс». В рамках данного руководства это выполняется в папке «Решатели». Затем выбирается «Единица хранения» на первом шаге (Создание узла). На втором шаге (параметры) вместо «Сервис» нужно выбрать «Решатель». Далее - ввести название (здесь - «AbstractUiSolver») и описание в текстовые поля и нажать кнопку «сохранить».
Параметр - «Решатель»
По аналогии с созданием сервиса и решателя создается инфоресурс агента (узел) – с помощью кнопки «плюс». В рамках данного руководства это выполняется в папке «Агенты». Затем выбирается «Единица хранения» на первой шаге (Создание узла). На втором шаге (параметры) выбирается «Агент». Далее - ввести название (здесь - «AbstractUiAgent», а в Вашем случае необходимо выбрать и использовать иное имя, перекликающееся с "внутренним именем" агента - см. далее) и описание в текстовые поля и нажать кнопку «сохранить».
Параметр - «Агент»
Для заполнения инфоресурса сервиса вначале необходимо заполнить инфоресурс решателя. Для начала этого процесса требуется открыть созданный решатель в режиме редактирования путём нажатия на названии инфоресурса решателя в личном фонде:
Решатель в личном фонде
Откроется редактор решателя, в котором автоматически сформированы вершины «корневой агент», «интерфейсный контроллер», «входные инфоресурсы», «выходные инфоресурсы», «собственные инфоресурсы», «собственные инфоресурсы на чтение» и «временные инфоресурсы»:
Структура решателя
Разрабатываемый решатель не будет ничего обрабатывать, так что онтологии не задаются.
Теперь требуется указать корневой агент и агент интерфейсный контроллер. Для этого требуется зайти в соответствующие узлы (помечены зеленым на рис. выше, при пред-заполнении решателя). Указать, какие агенты будут использоваться для решателя, необходимо с помощью установки ссылок по метапонятиям «Структура агента», расположенных в упомянутых узлах. Для этого требуется нажать на стрелку справа от метапонятия «Структура агента»:
Начало указания агентов решателя
В открывшемся фрейме в обоих случаях (для корневого и для интерфейсного агентов) найти созданного агента (здесь - AbstractUiAgent) и нажать на стрелку вниз:
Выбор агента
После успешного указания агентов они должны появиться в структуре решателя в виде ссылок.
Далее необходимо описать веб-страницы решателя. В данном руководситве будет создана одна страница - единственная для решателя. Для этого в начале требуется нажать на метавершину «web-страницы» и далее на метавершину «название»:
Веб-страницы
В появившемся фрейме ввести имя первой веб-страницы (AbstractUi):
Создание имени веб-страницы
Далее необходимо задать содержимое этой страницы. Для этого нажать на метавершину «содержимое»:
Создание содержимого веб-страницы
В появившемся окошке вводим текст: <ui action="init"/>:
Ввод содержимого веб-страницы
Далее нужно выбрать созданную страницу как стартовую. Для этого требуется нажать на узел «стартовая страница»:
Начало задания стартовой страницы
В открывшемся окне в выпадающем списке выбрать имя созданной веб-страницы и нажать «сохранить».
Также необходимо создать вершину «вести лог» с бинарным значением false.
Для того, чтобы начать процесс редактирования сервиса наобхожимо открыть созданный сервис в режиме редактирования. Для этого трубется нажать на названии сервиса в папке личного фонда правой кнопкой и в выпадающем меню выбрать пункт "Редактор".
Инициация редактирования сервиса
Редактор сервиса выглядит примерно так:
Редактор сервиса
Редактируя сервис, нужно указать применяемый решатель, входные и выходные ресурсы. (Вершина «папка по умолчанию» будет создана автоматически после указания решателя.) Для указания решателя трубуется нажать на стрелочку справа от мета-вершины «Структура решателя задач», как показано на рисунке выше. В открывшемся фрейме найти созданный решатель (AbstractUiSolver) и нажать на стрелочку справа от него (сослаться на решатель):
Выбор решателя в личном фонде
После этого в структуре сервиса должна появиться ссылка на выбранный решатель (выделено желтым цветом) и будет автоматически прописана папка по умолчанию (на рисунке не отображается):
Решатель, входные и выходные ресурсы сервиса
Разрабатываемый сервис основан на решателе, который не обрабатывает никакие инфоресурсы. Поэтому далее требуется лишь указать, что входные и выходные инфоресурсы отсутствуют, путём создания пустых вершин в инфоресурсе сервиса. Для этого необходимо нажать на вершинах «входные инфоресурсы» и «выходные инфоресурсы» (выделены зеленым цветом). В открывающихся формах будет указано, что задание ресурсов не требуется. В формах необходимо нажать кнопку Сохранить.
Зайти в созданный агент в режиме редактирования. Для этого нажать на названии агента в личном фонде:
Агент
Структура агента выглядит примерно так, как показано ниже. Необходимо заполнить множество продукций агента: нажать на соответствующий узел, затем создать нужное количество блоков продукций, нажимая на метавершину «блок продукций»:
Структура агента
При создании каждого блока продукций необходимо ввести его название и нажать на кнопку «Создать»:
Создание блока продукции
Первый блок продукции будет «инициализирующим» - он будет работать во время запуска сервиса (это необходимо по правилам создания решателей на платформе). Однако, ввиду отсутствия необходимости, никакие вычисления производиться этим блоко м продукций не будут - такое поведение характерно для решателей с интерфейсом.
Для описания этого блока продукций необходимо описать решаемую им задачу (создать по метавершине «описание»), указать шаблон входного сообщения и шаблоны выходных.
Если разработка агента ведётся впервые, то вначале нужно получить доступ к требуемым шаблонам (в создаваемом агенте будут использованы только системные шаблоны, предоставляемые платформой). Для инициирущего блока это «Шаблон Инициализирующее сообщение», для второго блока (будет описан далее) это «Шаблон Запрос от агента Вид», «Шаблон Отобразить окно» и «Шаблон Вернуть строку в окно» (так как разрабатывается сервис, основанный на решателе с интерфейсом).
Получение шаблонов в доступ подразумевает получение ссылок на них в личном фонде. Для этого трубуется свернуть редактор агента - нажать кнопку «Скрыть»:
Сворачивание редактора агента
Затем необходимо перейти в пункт «Фонд» в левом меню сайта, далее попасть в раздел «Платформа IACPaaS», там - в папку «Ядро платформы»:
Поиск инфоресурса «Шаблон Инициализирующее сообщение» в Фонде
Затем необходимо пролистать список единиц хранения (инфоресурсов) в поисках «Шаблон Инициализирующее сообщение», нажать на нём правую кнопку мыши, в конекстном меню выбрать пункт «Ссылка»:
«Шаблон Инициализирующее сообщение» в Фонде
После этого данный шаблон появится в личном фонде в папке «Загрузки»:
«Шаблон Инициализирующее сообщение» в личной папке «Загрузки»
Таким же образом необходимо получить ссылки на шаблонов сообщений, необходимых для работы с интерфейсом. Для этого нужно снова перейти в Фонд, зайти в раздел «Платформа IACPaaS», далее в папку «Интерфейс». В контекстном меню единиц хранения «Шаблон Запрос от агента Вид», «Шаблон Отобразить окно», «Шаблон Вернуть строку в окно» необходимого шаблона нужно выбрать пункт «Ссылка»:
Шаблоны сообщений для интерфейса
После этого ссылки на эти инфоресурсы появятся в папке «Загрузки» и они станут доступны для подключения в блоки продукций разрабатываемого агента.
Теперь необходимо вернуться в редактор агента (возобновив его отображение в меню «Работающие сервисы») и указать шаблон входного сообщения у инициирующего блока пролукций. Для этого необходимо нажать на «шаблон входного сообщения» (выделено желтым), а затем создать ссылку на нужный шаблон сообщения путём нажатия на стрелочку вверх (выделено зеленым):
Указание шаблона входного сообщения
В открывшемся окне необходимо найти в личном фонде (в папке «Загрузки») инфоресурс «Шаблон Инициализирующее сообщение» и нажать на стрелку справа:
Выбор Шаблона Инициализирующее сообщение
В результате в агенте появится ссылка на выбранный шаблон.
Инициирующий блок продукций не будет отправлять никаких выходных сообщений, поэтому теперь необходимо лишь создать вершину «шаблоны выходных сообщений» и не делать под ней никаких ссылок:
Шаблоны выходных сообщений первого блока продукций агента
На этом декларативное описание этого блока продукций закончено.
По аналогии создается и заполняется второй блок продукции. Однако, в отличие от 1-го блока продукции, в этот блок приходят сообщения, сформированные по шаблону «Запрос от агента Вид», а сам блок продукций рассылает сообщения, сформированные по нескольким шаблонам. Для этого под созданной вершиной "шаблоны выходных сообщений" создаются 3 вершины по метавершине "отправка сообщения" (им автоматически назначаются имена "1", "2" и "3") и под каждой из них прикрепляется отдельный инфоресурс шаблона выходных сообщений. В результате должно получиться так:
Второй блок продукций агента
Необходимо (для полноты инфоресурса агента) добавить описание к обоим блокам продукций и к самому агенту, используя клики по соответствующим метавершинам "описание".
Внутреннее имя и описание агента
Поле «внутреннее имя» содержит имя, которое будет использоваться в программном коде в качестве имени класса-заготовки агента и как часть имени класса-реализации агента. Оно должно быть написано английскими символами, обязательно заканчиваться на «Agent» и отличаться от уже используемых в платформе внутренних имён (при вводе уже используемого имени и попытке его сохранить - редактор выдаст ошибку). Здесь будет использовано доступное внутренее имя "AbstractUiAgent" (задействуемое и в именах классов), которое, таким образом, становится уже "занятым", поэтому в случае создания новых агентов можно, например, добавьте перед суффиксом Agent произвольную подстроку из нескольких знаков (AbstractUiMyAgent, AbstracrUi1Agent) или использовать полностью другое наименование с суффиксом Agent (MyUiAgent, ExampleUiAgent):
Создание внутреннего имени агента
Для работы агента необходимо иметь в представляющем его инфоресурсе скомпилированный байткод (который и будет запускаться). Он может быть получен только путём онлайн компиляции "текущей версии" исходного кода. Такая версия выбирается среди имеющихся версий исходного кода, хранимых в инфоресурсе агента. В данном примере будет разработана единственная версия с названием "1", которую и назначим "текущей" и тем самым используем при получении скомпилированного кода.
Формировать исходный код версии агента можно онлайн (с сохранением в инфоресурс) или локально, однако, в последнем случае, полученный локально (на ПК разработчика в некоторой IDE) исходный код должен быть перенесён в информационный ресурс агента (сохранён в некоторой версии).
Формирование исходного кода агента начинается с создания вершины "исходный код" - клик по метавершине с таким же именем.
В качестве содержимого этой вершины можно формировать несколько версий исходного кода и указать "текущую". Формирование версии исходного кода (это поддерево из нескольких вершин) начинается с нажатия на метавершину с именем "версия". В появившемся диалоге можно выбрать один из 2 способов создания - "из заготовки" или "из существующей версии". Так как агент ещё не имеет версий - необходимо использовать режим "из заготовки". В этом примере в качестве имени (и описания) версии необходимо задать "1". В результате создаётся целое поддерево из 5 вершин, содержащее в конечном итоге системный и собственный исходный код агента. При редактировании прямых потомков вершин "системный код" и "собственный код" (вершины с метавершиной "код" и именами "AbstractUIAgent.java" и "AbstractUIAgentImpl.java") можно увидеть сформированные автоматически по декларативному описанию шаблоны исходного кода:
Исходный собственный код агента
Далее разработку кода агента можно выполнять онлайн - путём редактирования вершины "AbstractUIAgentImpl.java" и после перейти к шагу 4.3, однако, при необходимости выполнять оффлайн разработку - обратитесь вначале к шагу 4.2.
Для скачивания файлов с заготовками исходного кода агента нужно развернуть под вершиной "исходный код" всё содержимое вершины "1" (метавершина "версия"), а затем, начав редактирование вершин "AbstractUiAgent.java" и "AbstractUiAgentImpl.java", скачать файлы с заготовками этих классов путём нажатия в диалогах редактирования на кнопку "Скачать файл" (см. рис. выше).
Скачать API платформы можно по ссылке из Документации.
Исходный код блоков продукций агента в данном руководстве предлагается формировать с использованием интегрированной среды разработки IntelliJ IDEA (Community edition - бесплатная версия). Её необходимо самостоятельно скачать с сайта разработчика и установить на компьютер. Запустить, создать новый проект Java, выбрать JDK 11 в качестве SDK (должен быть установлен в системе), не выбирать дополнительных компонент:
Новый проект
Не выбирая шаблон проекта, пройти по мастеру далее:
Мастер создания нового проекта
Выбирать место хранения Java-проекта и ввести его название, нажать кнопку «Finish»:
Завершение создания проекта на Java
В созданном проекте подключить загруженную библиотеку API (IACPaaS-api-1.0.jar). Для этого зайтие в меню File, где выбрать Project Structure > Project Settings > Libraries > + > Java
Подключение скачанной библиотеки iacpaas api
В открывшемся окне проводника необходимо найти загруженную ранее библиотеку api и указать её для проекта:
Подключение библиотеки iacpaas api
Затем нужно подтвердить импорт библиотеки кнопкой «Apply» и нажатием «ОК»:
Завершение подключения библиотеки
Библиотека появляется в структуре проекта:
Библиотека в структуре проекта
Далее требуется подключить скачанные исходные коды классов агента.
Для этого нужно зайти в папку расположения проекта, далее - в папку src, создать там череду вложенных подпапок "ru/dvo/iacp/is/iacpaas/mas/agents" (согласно имени пакета, в котором должны находиться коды агента) и поместить в последнюю два скачанных java файла. В результате этих действий в структуре проекта должны появиться два файла агента: один с суффиксом Agent, другой с суффиксом AgentImpl:
Файлы агента в структуре проекта
Вернувшись в IntelliJ IDEA нужно открыть файл с суффиксом Impl. Там будет помещаться код блоков продукций на Java - в местах помеченных словом комментарием TODO. (Другой файл изменять не нужно.)
Места для написания кода на Java для агента
В данном примере, как было сказано выше, инициирующий блок продукций не будет содержать кода, поэтому в методе runProducction(....InitMessage....) необходимо оставить или удалть комментарий TODO. А код для второго блока продукций будет описан позже.
Каждый раз, когда написан некоторый новый Java-код (в настоящий момент в коде находятся только заготовки методов, а сами методы пусты, так что действия данного раздела сейчас выполнять не нужно), код надо скомпилировать и в случае успешной компиляции - загрузить в платформу. Для этого нужно вначале нажать кнопку Build Project в меню Build:
Компиляция агента
Файл с исходным кодом класса-реализации агента можно найти по указанному ранее пути (папка проекта, подпапка "src", дерево вложенных подпапок "ru/dvo/iacp/is/iacpaas/mas/agents").
Для загрузки этого файла в инфоресурс агента (на платформу), необходимо открыть сайт платформы, запустить (возобновить) редактор агента, начать редактировать вершину AbstractUiAgentImpl.java (под вершинами "исходный код/1/собственный код").
В появившемся диалоге нажать кнопку "Выберите файл":
Загрузка кода агента
Далее в открывшемся окне с помощью проводника найти и указать файл AbstractUiAgentImpl.java и подтвердить выбор.
После этого редактор агента отобразит содержимое (исходный код) в открытом диалоговом окне вместо предыдущего. Для сохранения его в инфоресурс агента необходимо нажать кнопку "Сохранить в инфоресурс".
На этом загрузка кода агента считается завершенной.
Перед созданием исполняемого кода необходимо задать "текущую версию" исходного кода. Для этого под вершиной "исходный код" необходимо нажать на мета-вершину "текущая версия" и в диалоговом окне в выпадающем списке выбрать версию "1" и нажать "Сохранить".
После этого под корнем инфоресурса необходимо нажать на метавершину "исполняемый код".
При нажатии кнопки 'Скомпилировать' редактор агента выполнит проверку исходного кода (в выбранной текущей версии), скомпилирует байткод на его основе, выполнит, также и его проверку и сохранит полученный байткод в инфоресурс (его отображение будет скрыто от пользователя под вершиной "исполняемый код"). При возникновении ошибки в этом процессе редактор сообщит об этом, и исполняемый код получен не будет.
Если редактор сообщает, что инфоресурс не полон, то необходимо устанить всю найденную неполноту в инфоресурсе агента.
Создание нового исполняемого кода необходимо выполнять каждый раз после внесения изменений в исходный код текущей версии - так как исполняемый код автоматически удаляется при сохранении изменений в исходном.
Создайте на новую папку с произвольным названием на Вашем ПК. В этой папке создайте текстовый файл с произвольным именем и с расширением .js:
Папка для файлов интерфейса
В данном скриптовом файле поместите вызов метода html() у объекта jsDiv. Это метод JQuery, подставляющий содержимое элемента в указанный контейнер. Библиотека jQuery подключается в каждую интерфейсную страницу любого решателя платформой - её подключение выполнять в коде не нужно. В качестве параметра отправьте какую-нибудь строку. Если оформить ее в тегах HTML, то это будет HTML-код:
Для загрузки этого скрипта его в агент необходимо вначале сделать архив из папки интерфейса:
Создание архива папки интерфейса проекта
Далее нужно возвратится в редактор агента (на сайте платформы), найти метавершину «Javascript и ресурсы» и нажать её:
JavaScript и ресурсы
В открывшемся фрейме нажать на кнопку «Выберите файл». Далее найти архив с файлами интерфейса на Javascript и нажать «Открыть»:
Загрузка файлов интерфейса
Теперь архив сохранён в инфоресурс агента, а также распакован в папку агента на сервере платформе. Далее в (Java) код агента необходимо добавить инструкции по подключению файла(ов) интерфейса (сохранённого на платформе) в отображаемый интерфейс. Для этого нужно открыть проект в IntelliJ IDEA, найти второй блок продукции агента и написать следующий код (класс UiBuildHelper нужно импортировать):
Затем нужно скомпилировать и загрузить этот код в инфоресурс агента с помощью редактора агента, как было описано выше.
На этом сервис, решатель, агент с интерфейсом готовы.
Для запуска сервиса необходимо найти в личном фонде инфоресурс сервиса (который создавался в самом начале) и нажать на его имени:
Запуск сервиса
Запустится созданный сервис и будет отображён интерфейс:
Запущенный сервис с интерфейсом
Остановить сервис можно, нажав на крестик в правой части вкладки.
Для получения интерактивного интерфейса необходимо добавить в него поле ввода и кнопку. Введённое в поле ввода число будет отправляться на платформу, где агент умнодит его на два и отправит результат в интерфейс для отображения. Откройте снова js-файл Init и добавьте туда нужный код: ниже на 2-й строчке выполнено добавление поля ввода, а на 3-й строке - кнопки. Для правильной последующей обработки им необходимо добавить какие-нибудь идентификаторы. Здесь текстовому полю добавлен id='num', а кнопке id='go':
Далее необходимо сделать обработку нажатия кнопки. Добавьте кнопке, полученной с помощью JQuery, метод обработки нажатий click().
Получение введенного пользователем значения в поле ввода будет осуществляться с помощью метода val().
Отправление введенных данных на сервер платформы будет осущеставляться с помощью платформенного метода doAjax([...params...], callBackFunc).
Первым параметром в этом методе является массив передаваемых данных, где каждый элемент (данное) - строка вида paramName=paramValue (paramName - имя параметра, paramValue - его значение). Отметим, что для успешной передачи "сложных" имён и значений параметров агенту необходимо использовать URL-кодирование (платформа автоматически проводит URL-декодирование имени и значения каждого параметра). Для этого можно использовать стандартные функции built-in function encodeURIComponent(str) и encodeURI(str). Помимо этого для имен и значений параметров необходимо использовать кодировку UTF-8. В качестве одного из параметров передадим контролирующий действие агента параметр action со значеним, например, "load" (потом в Java коде агента используйте его, чтобы, например, отделить этот запрос от инициализирующего). Также необходимо передать параметр, хранящий введенное пользователем число. Это будет параметр x.
Вторым параметром в методе doAjax введите имя функции обратного вызова, которая будет вызвана тогда, когда придет ответ от платформы. Пусть это будет onGetResult():
В функции onGetResult() выведем полученный с платформы ответ во всплывающее окошко:
В результате выполненных действий получится следующий код на Javascript в файле Init:
Архив с данным файлом нужно вновь загрузить в агента с помощью его редактора.
Теперь необходимо в код агента добавить обработку нового запроса от интерфейса - обработку action="load". В коде обработки action="load" необходимо извлечь параметр x - число которое ввёл пользователь в поле ввода:
Это число умножается на 2:
Затем полученный результат возвращается в виде строки, используя шаблон uiReturnStringMessage:
В итоге блок продукий, обрабатывающий сообщения, сформированные по шаблону Шаблон Запрос от агента Вид (UiParamsMessage), выглядит так:
После напасания этого кода необходимо вновь его скомпилировать, запаковать и загрузить в инфоресурс агента, используя редактор агента (см. выше).
После этого необходимо вновь запустить сервис и можно убедиться, что его интерфейс и функционал работают:
Запущенный сервис с интерфейсом
Примечание: если один из скриптов агента должен обращаться к другому, то в коде исходного необходимо в пути к дополнительному скрипту использовать префикс вида '/mas-js/.../', где вместо многоточия указано внутреннее имя агента.