Реализация интеграций IRIS с .NET или Java с помощью PEX

Введение {#Вебинар:ImplementingIntegrationswith.NetorJava-Introduction}

InterSystems IRIS 2020.1 включает PEX (Production EXtension Framework) для облегчения разработки производств IRIS Interoperability с компонентами, написанными на Java или .NET.

Благодаря PEX разработчик интеграции, владеющий Java или .NET, может воспользоваться мощью, масштабируемостью и надежностью фреймворка InterSystems IRIS Interoperability и в кратчайшие сроки начать продуктивную работу.

Для специалиста по IRIS Interoperability framework, PEX позволяет легко обогатить интеграцию уже существующими внешними компонентами на языке Java или .NET.

В этом учебнике мы рассмотрим PEX и подскажем разработчикам .NET их первые шаги в работе с PEX. Код доступен по адресу https://github.com/es-comunidad-intersystems/webinar-PE.

Учебник дополняет документацию по PEX, доступную в Интернете по адресу https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=EPEX.

 

Архитектура интероперабельности InterSystems IRIS {#Вебинар:ImplementarIntegracionescon.NetoJava-ArquitecturadeInteroperabilidadInterSystemsIRIS}

PEX позволяет вам выбрать язык программирования (в настоящее время Java или .NET, а позже Python) для реализации любого из компонентов (бизнес-сервис, бизнес-процесс, бизнес-операция, InboundAdapter, OutboundAdapter, Messages), которые формируют производство IRIS Interoperability.

Существует 3 основных компонента интероперабельности IRIS:

• Бизнес-сервисы: Компоненты, которые предлагают услуги, могут быть использованы извне. Примерами бизнес-сервисов являются REST-сервис и SOAP Web-сервис, а также сервис, который читает и обрабатывает новые файлы, записанные в каталог, сервис, который читает и обрабатывает строки таблицы базы данных, и/или сервис, который читает файлы через FTP, и т.д. Бизнес-служба может иметь ассоциированный входящий адаптер, который заботится о деталях реализации конкретного протокола (SQLInboundAdapter для чтения таблиц SQL, FileInboundAdapter для чтения файлов и т.д.). Бизнес-сервис отвечает за обработку информации, копирование ее в сообщение IRIS Interoperability, отправку сообщения в бизнес-процесс или бизнес-операцию и, возможно, ожидание ответа, если таковой имеется.  
• Бизнес-операция: Компонент, который получает сообщение IRIS Interoperability и работает с внешней системой, возможно, с помощью OutboundAdapter, который заботится о деталях реализации протокола (TCP, REST, SOAP, Files, SQL и т.д.). Бизнес-операция может возвращать или не возвращать ответ вызывающей стороне.  
• Бизнес-процесс: Процесс оркестровки, который, получая сообщение IRS Interoperability, может выполнять процессы и вызовы одного или нескольких других бизнес-процессов или операций для выполнения сложных операций и/или возврата сообщения с информацией, добавленной отправившей его Бизнес-службой.

Конфигурация компонентов сгруппирована в “Production”, класс InterSystems IRIS, который содержит определение всех интеграций, которые запускаются вместе при инициации IRIS, и конфигурацию для каждого компонента этих интеграций. Он может быть отредактирован как класс IRIS или изменен с портала управления.

 

Архитектура PEX {#Вебинар:ImplementarIntegracionescon.NetoJava-ArquitecturadePEX}

Для выполнения .NET или Java кода InterSystems IRIS использует соответствующий объектный шлюз. Этот шлюз может быть инстанцирован локально или на удаленном сервере.

Шлюзы Java и .Net {#Вебинар:ImplementarIntegracionescon.NetoJava-LosJavay.NetGateways}

Шлюз – это собственный компонент .NET или Java, который прослушивает определенный порт TCP/IP, получает запросы от процесса IRIS, выполняет их и возвращает результаты.

 

Готовые компоненты PEX {#Webinar:ImplementarIntegracionescon.NetoJava-LosComponentesPEXpre-construidos}

Чтобы использовать PEX в производстве IRIS, необходимо добавить в производство предварительно созданный компонент для каждого компонента, разработанного на Java или .NET. Предварительно созданный компонент служит оберткой для внешнего элемента, на который он ссылается, и позволяет определить его свойства и конфигурацию в рамках производства.

Компоненты Java или .NET, запускаемые из соответствующего шлюза, должны наследоваться (быть подклассами) от уже существующего компонента PEX. Ниже приведен обзор этих элементов:

Компоненты IRIS {#Webinar:ImplementarIntegracionescon.NetoJava-ComponentesdeIRIS}

Для .NET и Java

 

Компоненты Java или .NET

Эти компоненты доступны в библиотеках, которые должны быть добавлены в проект Java или .NET. Минимальная библиотека для ссылки в проекте PEX – та же, что и у шлюза. Кроме того, если вы хотите использовать сообщения IRISObject для вызова компонентов IRIS из PEX, вы должны ссылаться на библиотеку IRISClient:

 

Суперкласс для использования в компонентах .NET

 

Суперкласс для использования в Java-компонентах

 

Функции утилиты {#Вебинар:ImplementarIntegracionescon.NetoJava-FuncionesdeUtilidades}

В компонентах, реализованных на ObjectScript, InterSystems IRIS предлагает некоторые команды в форме MACRO для заполнения информацией журнала событий IRIS. Эти методы доступны в Java и .NET следующим образом:

 

Взаимодействие между родными и PEX компонентами {#Вебинар:ImplementarIntegracionescon.NetoJava-InteroperabilidadentrecomponentesnativosycomponentesPEX}

Можно комбинировать компоненты на родном языке ObjectScript компании InterSystems IRIS с компонентами PEX, разработанными на Java или .NET.

• Если оба компонента имеют тип BusinessService – InboundAdapter или BusinessOperation – OutboundAdapter, разработчик может выбрать тип данных/объекта для использования в вызовах: Вызовы осуществляются между IRIS и шлюзом Java/.NET в соответствии с правилами преобразования данных, которые определяет шлюз.
• Когда оба компонента, обменивающиеся информацией, являются Business Hosts (BS, BP, BO), компонент, который должен получить сообщение (запрос или ответ), навязывает тип объектов, используемых для сообщения:
  • Компонент PEX всегда получает сообщение EnsLib.PEX.Message
  • Компонент IRIS получает сообщение IRISObject

 

EnsLib.PEX.Message {#Вебинар:ImplementarIntegracionescon.NetoJava-EnsLib.PEX.Message}

EnsLib.PEX.Message позволяет представить сообщение, структура которого была определена в .NET или Java, в объектном сценарии IRIS. IRIS использует функцию DynamicObject для манипулирования свойствами. Внутри IRIS использует JSON в качестве транспортной среды между IRIS и .NET/Java. При создании сообщения PEX в IRIS имя класса NET/Java, который должен быть инстанцирован для использования сообщения, должно быть задано как %classname.

IRISObject {#Вебинар:ImplementarIntegracionescon.NetoJava-IRISObject}

Чтобы вызвать предварительно созданный компонент InterSystems IRIS из компонента PEX, необходимо определить сообщение типа IRISObject (в .NET полный класс – InterSystems.Data.IRISClient.ADO.IRISObject).

 

Первые шаги с PEX и .NET {#Вебинар:ImplementarIntegracionescon.NetoJava-PrimerosPasosconPEXy.NET}

В этих первых шагах мы:

• Создадим проект .NET с необходимыми библиотеками PEX, версия 4.5 фреймворка .NET
• Добавим BusinessOperation и Simple сообщение в проект .NET
• Настроим шлюз .NET компании Intersystems IRIS
• Создайте производство интероперабельности
• Добавьте предварительно созданный BO

Создание проекта .NET с помощью Visual Studio 2019 {#Webinar:ImplementingIntegrationswith.NetorJava-Creatinga.NETProjectwithVisualStudio2019}

Создадим новый проект типа “Class Library .Net Standard in C #” в Visual Studio. Назовем его “PEX.Webinar.FirstDemo”:

 

 

Для работы с PEX добавляем необходимые зависимости из “Solution Explorer” и контекстного меню “Add Reference”:

 

, и добавляем две библиотеки (совместимые с .NET Framework 4.5! ), расположенные в подкаталоге инсталляции InterSystems IRIS с помощью кнопки “Browse”:

 

Затем из проводника решения Class1.cs переименовывается в “FirstOperation.cs”, а класс модифицируется для наследования от класса PEX BusinessOperation (InterSystems.EnsLib.PEX.BusinessOperation). Все 3 метода PEX.BusinessOperation перезаписываются:

 

На данный момент не определены ни сообщения, ни задачи для выполнения. По этой причине в 3 метода добавлены функции LOGINFO. С другой стороны, метод суперкласса не нужно вызывать, поэтому мы можем исключить вызовы базового класса (base.OnInit (), base.OnTearDown(), base.OnMessage). Мы оставляем реализацию следующим образом:

 

Это позволяет скомпилировать начальную версию проекта .NET с помощью меню “Build Solution”. Затем IRIS генерирует следующий файл, который используется далее:

InterSystems IRIS Interoperability Production Creation {#Вебинар:ImplementingIntegrationswith.NetorJava-InterSystemsIRISInteroperabilityProductionCreation}

Портал управления IRIS теперь позволяет выбрать меню “Interoperability”, пространство имен “Ensemble”, а также меню “Configure” и “Production”. Вкладка “Действия” и кнопка “Новый” позволяют определить новое производство IRIS Integration.

Чтобы активировать службу тестирования, выберите вкладку “Settings”, включите опцию “Testing Enabled” в последнем разделе списка (“Development and Debugging”) и нажмите кнопку Apply:

 

Добавление .NET-шлюза в производство {#Вебинар:ImplementingIntegrationswith.NetorJava-Addingthe.NETGatewaytotheProducción}

Для работы с PEX необходимо запустить соответствующий Java или .NET шлюз. InterSystems рекомендует конфигурировать и запускать эти шлюзы из меню “System Administration/Configuration/Connectivity/Object Gateways” для производственных сред (live). Для среды разработки компонент для запуска шлюза может быть добавлен непосредственно в production. Это позволяет запускать и останавливать шлюз одновременно с продакшеном одним щелчком мыши, тем самым освобождая доступ к .NET DLL проекта, когда вы хотите перекомпилировать его (Visual Studio не может перекомпилировать его, если .NET шлюз был запущен).

 

Чтобы добавить компонент “.Net Gateway”, добавьте Business Service в производство, используя кнопку “+” рядом с “Services”. “EnsLib.DotNetGateway.Service” – это имя класса компонента (Service Class), который нужно добавить, а для включения компонента выберите “Enable now”.

 

Параметры конфигурации добавленного компонента можно отредактировать, щелкнув его, заполнив значения на вкладке “Settings” (Параметры) и нажав кнопку “Apply” (Применить):

 

Добавление бизнес-операции, созданной в .NET {#Вебинар:ImplementingIntegrationswith.NetorJava-AddingtheBusinessOperationcreatedin.NET}

Теперь мы добавим бизнес-операцию PEX, используя кнопку “+” рядом с “Operations”, чтобы сослаться на ранее созданный в .NET код. “EnsLib.PEX.BusinessOperation” – это тип класса, (необязательный) компонент называется “PEX.Webinar.FirstOperation”, и он включен с помощью “Enable Now”.

 

Далее компонент настраивается (щелчком по добавленному компоненту) и выбором вкладки “Settings” справа:

Чтобы применить изменения, нажмите кнопку “Применить”:

 

Добавление и тестирование производства {#Webinar:ImplementingIntegrationswith.NetorJava-AddingandStartingtheProduction}

Кнопка “Start” запускает производство и все его компоненты:

InterSystems IRIS позволяет провести простое, изолированное тестирование компонента. Выберите “Бизнес-операцию” под названием “PEX.Webinar.FirstOperation” и выберите кнопку “Test” на вкладке Actions:

 

На следующем экране заполняются следующие данные:

 

При нажатии на кнопку “Invoke Testing Service”, система IRIS Interoperability framework отправляет сообщение компоненту, и выполняется код .NET.

Нажав “Visual Trace”, можно просмотреть детали. Белая точка (#3) отображает трассировку “LOGINFO”, реализованную в .NET.

Журнал событий IRIS содержит компиляцию всех сгенерированных сообщений LOGINFO(), в том числе в OnInit() и OnTearDown().

 

Следующие шаги с PEX: завершение производства {#Вебинар:ImplementingIntegrationswith.NetorJava-NextStepswithPEX:CompletingtheProduction}

Ниже приведены другие типы компонентов, созданные в .NET:

• .NET Messages
• .NET Бизнес-сервисы
• .NET Бизнес-процесс

Создание и использование PEX-сообщения с данными {#Вебинар:ImplementingIntegrationswith.NetorJava-CreatingandUsingaPEXMessagewithData}

Чтобы передать информацию из Ensemble в компоненты PEX, определите класс в .NET как подкласс InterSystems.EnsLib.PEX.Message со свойствами для передаваемой информации. Продолжая упрощенный пример, добавим к сообщению строковое свойство “value”. Бизнес-операция PEX станет сообщением того же типа с содержимым, преобразованным в заглавные буквы.

Класс Message в .NET {#Вебинар:ImplementarIntegracionescon.NetoJava-Clasedemensajeen.NET}

В проект .NET добавляется новый файл “FirstMessage.cs” со следующим определением:

FirstMessage

 

Использование сообщения из .NET {#Вебинар:ImplementarIntegracionescon.NetoJava-Usodelmensajedesde.NET}

В бизнес-операции FirstOperation тип данных для OnMessage определен как Object. Для его использования необходимо привести его к классу “FirstMessage”:

 

OnMessageV2

Производство IRIS должно быть остановлено (кнопкой “Stop”), или .NET Gateway должен быть, по крайней мере, отключен (двойной щелчок на компоненте) и скомпилировать .NET проект.

Использование класса из InterSystems IRIS {#Webinar:ImplementarIntegracionescon.NetoJava-UsodelaclasedesdeInterSystemsIRIS}

Кнопка “Тест” (Служба тестирования) не позволяет заполнить динамические свойства класса EnsLib.PEX.Message. Однако, Служба тестирования может быть использована с IRIS-нативным типом сообщения “Ens.StringRequest” и может быть преобразована (через преобразование данных) в сообщение PEX. Преобразование вызывается из предварительно созданного бизнес-процесса типа Router.

Трансформация данных {#Вебинар:ImplementingIntegrationswith.NetorJava-DataTransformation}

Преобразование данных создается для копирования данных из собственного сообщения ансамбля:

 

Трансформация данных может быть создана на портале управления “Interoperability”/”Build”/”Data Transformations” с помощью кнопки “New”:

 

После этого задаются параметры преобразования из “исходного” в “целевое” сообщение, как описано в предыдущей таблице, используя графический инструмент и заполняя текст на вкладке “Action” справа, чтобы получить две строки текста, отображаемые внизу. Затем на вкладке “Инструменты” можно сохранить, скомпилировать и протестировать.

 

Теперь, открыв вкладку “Инструменты”, вы можете протестировать это преобразование данных:

 

Откроется окно Test, где вы можете указать значения для исходного сообщения (в StringValue) и проверить результат:

Как вы можете видеть, сообщение PEX использует внутреннее представление JSON для передачи значений между IRIS и Java или .NET.

 

Создание бизнес-процесса типа Router {#Вебинар:ImplementingIntegrationswith.NetorJava-CreatingaRoutertypeBusinessProcess}

Теперь можно добавить бизнес-процесс типа Router в Production и определить правило маршрутизации, которое вызывает созданную трансформацию данных и отправляет сообщение существующей бизнес-операции.

На портале управления вернитесь на экран конфигурации производства (“Interoperability” / “Configure” / “Production”) и добавьте бизнес-процесс типа “EnsLib.Message.Router”, нажав на “+” рядом с “Processes”, и заполните следующим образом:

 

Осталось отредактировать правило маршрутизации для этого компонента. Для этого выберите компонент “MessageRouter” в производстве и нажмите на увеличительное стекло рядом с именем бизнес-правила:

 

Редактор правил позволяет отредактировать правило для отправки всех сообщений “Ens.StringRequest” в бизнес-операцию “PEX.Webinar.FirstOperation” после применения к ним трансформации. Кнопка “+” позволяет добавлять элементы в правила и редактировать элемент при его предварительном выборе. Правило должно выглядеть следующим образом:

По умолчанию этот компонент не ожидает ответа. Измените настройки на вкладке “Настройки” компонента, чтобы получать ответ от Бизнес-операции:

 

Тестирование маршрутизатора с помощью службы тестирования {#Webinar:ImplementarIntegracionescon.NetoJava-PruebadelEnrutadorconelServiciodePruebas}

Вернувшись на страницу производства, вы можете использовать кнопку “Start” для запуска производства, выбрать компонент “MessageRouter” и на вкладке “Actions” нажать кнопку “Test”, чтобы отправить сообщение типа “Ens.StringRequest”:

 

Сообщение “Test Response” можно просмотреть в разделе “Test Results”, а полный журнал сообщений показывает все детали выполнения на различных компонентах производства IRIS Interoperability:

Response:

  {#Webinar:ImplementarIntegracionescon.NetoJava-}

Трассировка сообщений:

 

.NET Business Services {#Вебинар:ImplementarIntegracionescon.NetoJava-BusinessServiceen.NET}

.NET Implementation {#Вебинар:ImplementingIntegrationswith.NetorJava-Implementationin.NET}

Вернитесь в Visual Studio, чтобы создать бизнес-сервис .NET. В этом начальном примере эта бизнес-служба не связана с конкретным “Входящим адаптером”; она использует “EnsLib.InboundAdapter”, компонент, который запускается через регулярные промежутки времени (в соответствии с установленным значением CallInterval) и делает вызов бизнес-службы каждый CallInterval. 

В Visual Studio для класса “FirstService” создается новый файл “FirstService.cs”. Обработка каждого события, обнаруженного входящим адаптером, производится с помощью метода “OnProcessInput”. Объект, задаваемый в параметре, зависит от реализации InboundAdapter; в данном случае он не используется:

FirstService:OnProcessInput

FirstService:OnProcessInput

 

Чтобы отправить сообщение любому компоненту продакшена без его перекомпиляции, можно использовать параметр, настраиваемый с портала управления; значения указываются в виде JSON-строки в параметре конфигурации “RemoteSettings”.

Параметры

 

Если значение, указанное для “TargetConfigName”, равно null, бизнес-сервис не отправит сообщение ни в одно место назначения. Чтобы обнаружить эту проблему как можно раньше, можно проверить значение TargetConfigName при запуске компонента в вызове OnInit():

FirstService:OnInit

Теперь вы можете изменить OnProcessInput, чтобы использовать значение TargetConfigName:

OnProcessInput

 

PEX Business Service в InterSystems IRIS {#Вебинар:ImplementarIntegracionescon.NetoJava-BusinessServicePEXenInterSystemsIRIS}

На портале управления добавьте компонент типа Business Service к определению Production, нажав на “+” рядом с надписью 

 

Затем настройте компонент (щелкнув на добавленном компоненте) и выберите вкладку “Настройки” справа: 

 

Когда эта бизнес-служба активирована, выполняется каждый CallIntervall связанного с ней адаптера OnTask() (Ens.InboundAdapter). Здесь OnTask просто вызывает FirstService.OnProcessInput(). То есть, каждый callInterval и FirstService.OnProcessInput() генерирует сообщение, которое отправляется компоненту, определенному в “TargetConfigName”. Это можно проверить в Message Viewer:

 

С деталями вызова:

 

 

.NET Business Process {#Вебинар:ImplementarIntegracionescon.NetoJava-BusinessProcess.NET}

.NET Implementation {#Вебинар:ImplementingIntegrationswith.NetorJava-.NETImplementation}

Как и каждый бизнес-хост, бизнес-процесс имеет методы CallBack OnInit() и OnTearDown(). Конкретные методы Бизнес-процесса следующие:

Важно отметить, что бизнес-процесс может иметь длительное время выполнения (часы или дни, ожидая асинхронного ответа). Для этого IRIS Framework может прерывать и возобновлять выполнение процесса. Все значения, которые вы хотите сохранить во время выполнения процесса, должны быть помещены в свойства класса, которые IRIS сохраняет персистентно. Это необходимо указать с помощью обозначения “[persistent]”.

В данном примере реализована минимальная реализация, в которой бизнес-процесс направляет полученное им PEX-сообщение в пункт назначения:

Используются две переменные, которые могут быть изменены с портала управления:

FirstProcess

 

Когда вы получаете сообщение, оно асинхронно отправляется в TargetConfigName:

FirstProces:OnRequest

OnResponse позволяет управлять ответами на вызовы:

FirstProcess:OnResponse

В конце процесса возвращается ответ:

FirstProcess:OnComplete

 

Бизнес-процесс PEX в InterSystems IRIS {#Вебинар:ImplementarIntegracionescon.NetoJava-BusinessProcessPEXenIntersystemsIRIS}

Мы добавляем бизнес-процесс EnsLib.PEX.BusinessProcess, настраиваем его по необходимости и изменяем TargetConfigName для бизнес-сервиса “PEX.Webinar.FirstProcess”, чтобы отправлять сообщения новому процессу вместо того, чтобы отправлять их непосредственно в BO. 

 

“Настройки” компонента определяются следующим образом:

Результат в трассировке выглядит следующим образом:

 

Заключение

PEX позволяет реализовать интеграцию на .NET или Java очень легко и предлагает всю мощь и надежность уровня интероперабельности InterSystems IRIS для разработчиков, владеющих этими языками.