Руководство по разработке сервисов на основе технологии расширяемого редактора

Дата последней модификации документа: 09 октября 2024.

Содержание

1. Введение

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

Разработка решателя по технологии расширяемого редактора (ExIWE - Extensible Inforesource Web Editor) состоит из следующих этапов:
  1. разработка агента (возможно, нескольких), к которому редактор ExIWE будет обращаться с целью отображения, порождения обработки или удаления подсети некоторого информационного ресурса;
  2. формирование таблицы соответствий;
  3. формирование декларативного описания решателя.

Разработка сервиса (сборка из решателя, входных и выходных параметров) выполняется на основе базовой технологии.

Решатель, построенный на основе описываемой технологии осуществляет отображение одного инфоресурса (первый выходной параметр в случае редактора или первых входной - в случае просмотрщика), при этом обрабатывать подключаемым агентом (агентами) может несколько инфоресурсов (любой входной и/или выходной параметр).

Далее будет описана разработка решателя-редактора, а примечания о разработке просмотрщика будут даны в конце документа.

2. Разработка внешнего агента

2.1. Общая информация

Работа агента UI-контроллера (специализированного системного агента, используемого в качестве интерфейсного контроллера решателя расширяемого редактора информационных ресурсов - см. раздел о сборке решателя) с внешним (по отношению к этому системному агенту UI-контроллеру) агентом (вызов внешнего агента и ожидание ответа) ведётся в 4 случаях (согласно CRUD операциям): Во всех случаях обращение к внешнему агенту при выполнении определённого действия будет выполняться только если в таблице соответствий (см. далее) будет указано, что такое взаимодействие должно выполняться. Иначе операция (CRUD) будет осуществляться базовым функционалом редактора.

Для реализации внешнего агента (выполняется по Базовой технологии - см. соответствующий раздел в Руководстве по разработке агента и шаблонов сообщений), в полной мере (для всех 4 типов операций CRUD) взаимодействующего с системным агентом UI-контроллером, необходимо реализовать агент, в котором должны присутствовать следующие четыре блока продукций: Примечание: Инфоресурсы данных шаблонов сообщений находятся в разделе "Платформа IACPaaS / Редакторы и просмотрщики".

2.2. Чтение входных сообщений

Агент (точнее его соответствующий блок продукций) при получении входного сообщения, созданного по одному из указанных шаблонов входных сообщений, обычно перед выполнением каких-то действий должен "прочитать" информацию, которая была передана в них от UI-контроллера (при помощи методов-геттеров):

2.3. Работа блоков продукций

Работа блока продукций внешнего агента может заключатся в обработке инфоресурса и/или в показе некоторого фрагмента интерфейса.
Зачастую в случае операций создания и модификации (реже в случае отображения и недоступно для удаления) удобно использовать схему 2-шагового обращения к внешнему агенту:
  1. первое обращение приводит к отображению специфичой формы порождения/редактирования (просмотра):
  2. второе обращение начинается с передачи внешнему агенту введённых данных и в итоге приводит к внесению им изменений в обрабатываемый инфоресурс (инфоресурсы):
Примечания:
Допускаются следующие "масштабы" обработки (формирования фрагментов) инфоресурсов при таком взаимодействии:
Особым случаем является режим, когда внешнему агенту поступает сообщение, сформированное по шаблону "Отобразить подсеть". Здесь внешнему агенту необходимо лишь сформировать фрагмет интерфейса, причём желательно только с полями вывода информации (например, для показа некоторой подсказки ниже обрабатываемого понятия). Примером служит поведение редатора решателей задач, когда под вершиной "входные инфоресурсы" при её раскрытии отображается текстовая подсказка о том, какой функционал будет доступен пользователю при модификации содержимого данной вершины.

В рамках работы внешнего агента рекомендуется осуществлять доступ к обрабатываемым инфоресурсам не через массивы входных, выходных, временных, собственных инфоресурсов (на чтение и с полным доступом), а с применением метода IConcept[] getProcessedInforesourcesRoots(), возвращающего массив обрабатываемых инфоресурсов, который формируется специально при вызове данного агента (см. раздел о формировании Таблицы соответствий). При применении такого метода агент становится повторно-используемым, ввиду отвязки от порядков задания списков входных, выходных, временных, собственных (на чтение и с полным доступом) инфоресурсов, определяемых разными решателями по-разному. Однако, в этом случае, в описании блока продукций агента необходимо (словесно) описать нужный этому агенту порядок и набор метаинформации обрабатываемых инфоресурсов - чтобы на основе данной информации разработчик решателя (который может не являться разработчиком агента, а быть иным лицом) смог задать правила формирования массива этих инфоресурсов в Таблице соответствий (см. далее).

В рамках одной таблицы соответствий некоторый агент может быть подключен несколько раз. Это несколько усложняет код его блоков продукций, но уменьшает число разрабатываемых агентов (возможно, стоит придерживаться принципа "одна метаинформация - один агент", а не "одна вершина метаинформации - один агент"). В этом случае режим работы (подсеть, которую предполагается породить/отображить/модифицировать/удалить) необходимо различать, например, по имени по мета-вершины, соответствующей порождаемой (например, "xxx".equals(getMetaConcept().getName()) или отображаемой/модифицируемой/удаляемой (например, "yyy".equals(getMetaRelation().getEnd().getValue()) вершины. Более продвинутый и точный способ - получить полный список обрабатываемых агентом вершин метаинформации, а затем сравнить полученную в сообщении вершину (getMetaConcept() или getMetaRelation().getEnd()) с элементами этого списка методом is(IConcept concept), однако для этого агенту необходимо иметь доступ к метаинформации обрабатываемого инфоресурса, что обычно не обеспечивается разработчиком решателя и сервиса.

2.4. Отправка "ответных" сообщений

При отправке внешним агентом сообщения, сформированного по одному из 'ответных' шаблонов ("Шаблон Результат формирования подсети", "Шаблон Результат отображения подсети", "Шаблон Результат обработки подсети" и "Шаблон Результат удаления подсети") его (сообщение) необходимо наполнить данными, используя один из доступных методов-сеттеров (для задания порождённого или обработанного понятия и/или отображаемого интерфейса): Примечание: в случае, если не были установлены параметры в выходном сообщении, агент UI-контроллер решателя, получив незаполненное сообщение, не найдёт в нём необходимых данных, и сообщит об этой ошибочной ситуации в интерфейсе редактора.
Особый случай отправки ответа агенту UI-контроллеру:
В случае, если ответное сообщение UI-контролеру будет слать не сам внешний агент, а какой-то дополнительный агент (или же внешний агент, но не в одном из описанных блоков продукций, а после работы своих других БП или после работы вспомогательных агентов), то для формирования ответного сообщения по указанным шаблонам невозможно использовать указанные выше методы (ввиду отсутствия объекта входного сообщения, принадлежащего классу GenerateSubnetworkMessage или ProcessSubnetworkMessage или ShowSubnetworkMessage или DeleteSubnetworkMessage). В этом случае необходимо использовать следующие методы для наполнения выходных сообщений данными: Значения параметров для вызова указанных методов изначально извлекаются (внешним агентом) из соответствующих исходных входных сообщений, полученных от агента UI-контроллер, а далее должны быть переданы вспомогательным агентам или сохранены в локальную структуру.

3. Разработка таблицы соответствий

Разработка таблицы соответствия состоит из 2 этапов:
Метаинформация таблицы соответствий (Платформа IACPaaS / Редакторы и просмотрщики / Структура таблицы соответствий) в текстовом представлении (в нотации текстового представления информационных ресурсов) выглядит следующим образом:
Структура таблицы соответствий
{
    ~new орграф метаинформации
    {
        ~one ~ref -> инфоресурс$;    # Ссылка на корневую вершину орграфа грамматики (метаинформации), который расширяет описываемая таблица соответствий
    }
    ~copymm ~new орграф конкретной метаинформации
    {
        ~one ~ref -> инфоресурс$;    # Ссылка на корневую вершину орграфа грамматики (метаинформации), представляющему конкретную метаинформацию
    }    
    ~seq соответствие
    {
        ~new вершина
        {
            ~one ~ref -> инфоресурс$; # При формировании таблицы соответствий здесь должна быть ссылка на вершину орграфа грамматики (метаинформации), которой требуется сопоставить
                                      # обращение к агенту или порождающую грамматику языка текстового представления информации
                                      # или, начиная с которой, редактор должен быть переведен в режим просмотра нижележащей подсети
                                      # или, начиная с которой, редактор не должен отображать нижележащую подсеть
        }
        ~copymm ~new обращение к агенту
        {
            ~new агент
            {
                ~one ~ref -> Платформа IACPaaS / Ядро платформы / Структура агента$; # При формировании таблицы соответствий здесь должна быть ссылка на корневую вершину орграфа,
                                                                                     # описывающего декларативную спецификацию агента, к которому должно быть выполнено обращение.
            }
            ~copy ~new типы операций # Здесь задаются типы операций, выполнение которых требует обращения к агенту: создание подсети, отображение подсети, модификация подсети
                                     # удаление подсети. При этом должен быть задан хотя бы один тип операции.
            {
                ~copymm ~new ["создание"] # Если требуется, чтобы обращение к агенту выполнялось при создании подсети, то данная вершина должна быть порождена
                                          # при формировании таблицы соответствий, в противном случае, порождать её не нужно.
                ~copymm ~new ["отображение"] # Если требуется, чтобы обращение к агенту выполнялось при отображении содержимого подсети,
                                             # то данная вершина должна быть порождена при формировании таблицы соответствий,
                                             # в противном случае, порождать её не нужно.
                ~copymm ~new ["модификация"] # Если требуется, чтобы обращение к агенту выполнялось при редактировании содержимого подсети,
                                             # то данная вершина должна быть порождена при формировании таблицы соответствий,
                                             # в противном случае, порождать её не нужно.
                ~copymm ~new ["удаление"] # Если требуется, чтобы обращение к агенту выполнялось при удалении подсети, то данная вершина должна быть порождена
                                          # при формировании таблицы соответствий, в противном случае, порождать её не нужно.
            }
            ~copymm ~new ["интерактивное"] # Признак, определяющий, как должно выполняться обращение к агенту: по инициативе пользователя
                                           # или в процессе автопорождения.
                                           # Если обращение к агенту должно быть инициировано пользователем, то данная вершина должна быть порождена 
                                           # при формировании таблицы соответствий, в противном случае, порождать её не нужно.
            
            ~copymm ~new ["сделать полное раскрытие"] # Признак, опеределяющий, нужно ли раскрывать все вершины сгенерированной подсети (в случае, если в агенте выполнялось создание подсети).
                                                      # Если требуется раскрыть все вершины сгенерированной подсети, то данная вершина должна быть порождена 
                                                      # при формировании таблицы соответствий, в противном случае, порождать её не нужно
                                                      # (будет раскрыто только корневое понятие сгенерированной подсети).
            параметры
            {
                *   # При формировании таблицы соответствий здесь может быть описан произвольный орграф грамматики (метаинформации),
            }       # задающий параметры сообщения для агента
            ~copymm ссылки на обрабатываемые инфоресурсы
                    # Здесь задаются правила формирования массива ссылок на обрабатываемые инфоресурсы,
                    # помещаемых в сообщения внешнему агенту, согласно структуре ШС Сформировать подсеть и Обработать подсеть:
                    # для каждой ссылки описывается, какое выбрать множество обрабатываемых инфоресурсов в сервисе/решателе
                    # и на какой из них установить ссылку - по заданному порядковому номеру в этом множестве
            {
                ~seq ссылка на обрабатываемый инфоресурс
                ~ALT {
                    входной инфоресурс { порядковый номер [int] }   # начинать с 1
                    выходной инфоресурс { -> порядковый номер; }    # начинать с 1
                    временный инфоресурс { -> порядковый номер; }   # начинать с 1
                    собственный инфоресурс { -> порядковый номер; } # начинать с 1
                    собственный инфоресурс на чтение { -> порядковый номер; } # начинать с 1
                }
            }
        }
    }
}

Общая информация о содержимом таблицы соответствия представлена в комментариях выше и в документе.

Опишем особо вершину "параметры", содержимое которой, в случае его наличия, призвано управлять работой внешнего агента. Если под данной вершиной сформировать некоторую подсеть типа метаинформация, используя вершины типа "нетерминал" и/или "терминал-значение", то внешний агент, получив ссылку на такую посдесть и "прочитав" её, может, например, определить, по какому режиму ему необходимо работать (описание правил создания такой подсети необходимо помещать в описание блока продукций агента). Тем самым, можно, например, организовать работу агента в "соответствиях" с совпадающей мета-вершиной в разных таблицах соответствий, если его работа в нескольких случаях должна быть весьма схожа и нет необходимости заводить разные агенты.

Пример — фрагмент таблицы соответствий для решателя Расширенный редактор агентов:
Платформа IACPaaS / Разработка программных ЕХ / Таблица соответствия для расширенного редактора агентов <<< Платформа IACPaaS / Редакторы и просмотрщики / Структура таблицы соответствий
{
  метаинформация
  {
    инфоресурс [ -> Платформа IACPaaS / Ядро платформы / Структура агента$; ]
  }
  соответствие [1]
  {
    понятие
    {
      инфоресурс [ -> Платформа IACPaaS / Ядро платформы / Структура агента$ / код; ]
    }
    обращение к агенту
    {
      агент { Структура агента [ -> Платформа IACPaaS / Разработка программных ЕХ / Интерфейсный контроллер загрузчика агентов$;] }
      ["интерактивное"]
      параметры {} 
    }
  }
  соответствие [2]
  {
    понятие
    {
      инфоресурс [ -> Платформа IACPaaS / Ядро платформы / Структура агента$ / исходный код; ]
    }
    обращение к агенту
    {
      агент { Структура агента [ -> Платформа IACPaaS / Разработка программных ЕХ / Интерфейсный контроллер генератора агентов$;] }
      ["интерактивное"]
      параметры {} 
    }
  }
}

4. Разработка решателя

4.1. Общие сведения

Формирование декларативного описания решателя, разрабатываемого на основе расширяемого редактора информационных ресурсов, выполняется в соответствии с разделом 3 документа Руководство по разработке решателя, при этом:

4.2. Формирование web-страниц решателя

В качестве содержимого (стартовой) web-страницы решателя необходимо указать (в приведенном здесь порядке) следующие элементы:
  1. вызов решателя в виде ui-запроса к нему с единственным параметром action="nav": <ui action="nav"/>;
  2. вызов шаблона {{IweCSS}} — для отображения решателя со стилями редактора.

В качестве web-страницы решателя со стилями редактора необходимо сделать ссылку на вершину IweCSS, находящуюся в инфоресурсе Редактор инфоресурсов (находится в папке Редакторы и просмотрщики раздела Платформа IACPaaS)

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

Пример — фрагмент решателя "Расширенный редактор агентов":
Расширенный редактор агентов <<< Платформа IACPaaS / Ядро платформы / Структура решателя задач
{
  ..
  стартовая страница ["Расширенный редактор агентов"]
  web-страницы
  {
    название [Расширенный редактор агентов]
    {
      содержимое ['...']
      #<ui action="nav"/>
      #{{IwvCSS}}
      #{{IweCSS}}
    }
    название [Расширенный редактор агентов JarDownload]
    {
      содержимое ['...']
      #<ui action="down"/>
    }
    название [ -> Платформа IACPaaS / Редакторы и просмотрщики / Просмотрщик инфоресурсов$ / web-страницы / IwvCSS; ]
    название [ -> Платформа IACPaaS / Редакторы и просмотрщики / Редактор инфоресурсов$ / web-страницы / IweCSS; ]
    название [ -> Платформа IACPaaS / Редакторы и просмотрщики / Просмотрщик инфоресурсов$ / web-страницы / IweDownload; ]
  }
}

4.3. Формирования массива ссылок на обрабатываемые ресурсы

Предположим, имеются два агента, которых в качестве внешних необходимо присоединить через таблицу соответстий. Каждый из агентов в своём описании требует указать ему в качестве первого обрабатываемого инфоресурса - инфоресурс для чтения, сформированный по некоторой различной метаинформации (Х1 и Х2), а в качестве второго обрабатываемого инфоресурса - инфоресурс для дополнительной записи данных, сформированный по некоторой различной метаинформации (У1 и У2). Таким образом, помимо метаинформации отображаемого выходного инфоресурса (и таблицы соответствий в качестве собственного на чтение - см. далее), в решателе необходимо указать метаинформации двух входных и ещё двух выходных (после отображаемого обрабатываемого) инфоресурсов:
Решатель для примера <<< Платформа IACPaaS / Ядро платформы / Структура решателя
{
  входные инфоресурсы
  {
    инфоресурс [ -> Х1$; ]
    инфоресурс [ -> Х2$; ]
  }
  сообственные инфоресурсы
  {
    инфоресурс [ -> ТС$; ]
  }
  выходные инфоресурсы [2]
  {
    инфоресурс [ -> У1$; ]
    инфоресурс [ -> У2$; ]
  }
}
Для передачи нужных обрабатываемых инфоресурсов первому агенту, необходимо в его "соответствии" так задать правила их формирования:
ссылки на обрабатываемые инфоресурсы
{
  ссылка на обрабатываемый инфоресурс [1]
  {
    входной инфоресурс { порядковый номер [1] }
  }
  ссылка на обрабатываемый инфоресурс [2]
  {
    выходной инфоресурс { порядковый номер [1] }
  }
}
Для передачи нужных обрабатываемых инфоресурсов второму агенту, необходимо в его "соответствии" так задать правила их формирования:
ссылки на обрабатываемые инфоресурсы
{
  ссылка на обрабатываемый инфоресурс [1]
  {
    входной инфоресурс { порядковый номер [2] }
  }
  ссылка на обрабатываемый инфоресурс [2]
  {
    выходной инфоресурс { порядковый номер [2] }
  }
}
Отметим, что в обоих случаях ссылка на отображаемый обрабатываемый инфоресурс не передаётся, так как доступ к нему возможен через данные входящего сообщения.

5. Дополнение - Расширяемый просмотрщик

Помимо создания решателей на основе расширяемого редактора инфоресурсов возможно также создание решателей-просмотрщиков — на основе расширяемого просмотрщика инфоресурсов (используя всё тот же агент "Интерфейсный контроллер расширяемых редакторов-просмотрщиков инфоресурсов").

Процедура формирования таких решателей аналогична вышеприведённой за единственным исключением: