Разработка и использование заказных адаптеров в архитектуре Java EE Connector Architecture

Автор: Роналд Луттикхузен

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

Интероперабельность, способность к взаимодействию, разнородных систем и технологий - это одна из главных технологических целей сервисно-ориентированной архитектуры (SOA). Интероперабельность - это условие успешного принятия SOA, так как она обеспечивает повторное использование существующих ИТ-активов и, тем самым, увеличивает возврат инвестиций в эти активы (ROI).

Семейство продуктов Oracle Fusion Middleware включает полный портфель продуктов для разработки, развертывания и управления SOA. Один из этих продуктов - Oracle Integration Adapters, который предоставляет ряд адаптеров, реализующих интеграцию с совокупностью технологий, протоколов, унаследованными (legacy) системами и тиражируемыми приложениями. Другие компоненты семейства Oracle Fusion Middleware - такие как Oracle BPEL Process Manager и Oracle Enterprise Service Bus (ESB) - используют эти адаптеры для интеграции сервисов и процессов с существующими ИТ-активами. Примеры: JMS Adapter, Database Adapter, E-Business Suite Adapter и Tuxedo Adapter.

Рис. 1: Платформа Oracle SOA Platform

Однако, этот ряд адаптеров не всегда достаточен в сценариях интеграции.   В таких случаях нужно либо разработать свой адаптер, либо купить адаптер на стороне. Список соответствующих поставщиков и их адаптеров можно найти на Oracle Integration Adapters page в сети OTN.

Эта статья содержит пошаговое руководство для построения адаптеров и их использования в среде Oracle SOA Suite 10 g на основе реального опыта пользователей . Обзор вовлеченных сред и компонент дается по ходу дела. В этой статье также кратко обсуждается вопросы предложения адаптеров, их слияния и поддержки в будущих версиях Oracle Fusion Middleware, которые включат продукты бывшей BEA.

Обзор архитектуры

В этой секции дается обзор архитектуры продукта Oracle Integration Adapters и его основных компонентов (до "ныряния" в детали):

• Предложение (набор) адаптеров (Adapter offering)
• Среда адаптеров (Adapter Framework)
• Поддержка на этапе проектирования (Design-time support)

Эти компоненты вместе с их отношениями к компонентам SOA Suite и EIS-системам показаны на следующем рисунке.

Рис. 2: Краткий обзор компонент этапов проектирования и выполнения, которые участвуют в интеграции компонент SOA Suite с компонентами EIS-систем.

Введение в JCA

Адаптеры, разработанные в корпорации Oracle, реализованы как ресурс-адаптеры (resource adapters) архитектуры Java EE Connector Architecture (JCA). JCA - это Java стандарт, который описывает общую архитектуру для соединения серверов приложений, совместимых с JEE, с Enterprise Information Systems (EIS) - информационными системами предприятия. Текущий JCA стандарт поддерживает двухсторонние коммуникации и очевидно, ПО, его поддерживающее - прим. пер.), которое может быть установлено на любом сервере приложений, совместимом с JEE, включая Oracle WebLogic Server и Oracle Application Server. Вы можете использовать однородные (uniform) API-интерфейсы и контракты JCA для программируемого соединения к унаследованным системам вместо того, чтобы изучать и использовать API-интерфейсы каждой EIS-системы или другой механизм интерфейса.

Как показано на Рис. 3, ресурс-адаптер в JCA инкапсулирует логику соединения к одной EIS или технологии. Компоненты на стороне клиента (Client components) могут вызывать адаптер для соединения с базовой (underlying) EIS. Используя эти адаптеры, разработчики избавляются от необходимости вникать в детали всех API-интерфейсов и интерфейсных механизмов EIS и технологий, которые должны быть интегрированы. На деле разработчики должны знать только общие API-интерфейсы и контракты JCA.

Рис. 3: Обзор JCA

Есть две версии JCA, версия 1.0 (JSR-16) и версия 1.5 (JSR-112). JCA версии 1.0 определяет :

• Набор контрактов системного уровня (system-level contracts) между сервером приложений и EIS. Эти контракты реализуются ресурс-адаптерами и поддерживают управление соединениями (connection management), управлением транзакциями и механизмами безопасности. Это позволяет ресурс-адаптерам быть мощными функционально, масштабируемыми и участвовать им в глобальных транзакциях, которые "пронзают" множество компонент, включая адаптеры.
• Интерфейс CCI (Common Client Interface), который определяет, что компоненты API на стороне клиента могут использовать для взаимодействия с EIS через ресурс-адаптер JCA.
• Механизм развертывания и тиражирования (packaging) для ресурс-адаптеров.

Важные расширения в версии 1.5 включают:

• Расширенный набор контрактов системного уровня, добавляющих управление жизненным циклом и управление нитями или работой (thread - or work).
• Средства управления потоком поступающих транзакций и сообщений (Transaction and message inflow capabilities), обеспечивающие асинхронные коммуникации с EIS. Ресурс-адаптер либо подписывается на события, генерируемые EIS, или использует опрос (polling) для реализации коммуникаций в части входящих сообщений (inbound communication). Входные сообщения к другим компонентам доставляются через JMS или аналогичную инфраструктуру пересылки сообщений.

Следующие паттерны взаимодействия между компонентами приложений и EIS можно реализовать с применением JCA 1.5:

• JCA двухсторонние взаимодействия при работе с уходящими сообщениями (2-way outbound interactions): синхронные запрос/ответы от ресурс-адаптера к EIS.
• JCA односторонние взаимодействия при работе с уходящими сообщениями: асинхронная подписка или "выстрелил" (отправил) и забыл" (fire-and- forget) от ресурс-адаптера к EIS
• JCA односторонние взаимодействия при работе со входящими сообщениями: асинхронная публикация, генерируемая событиями (Asynchronous event- publishing) от EIS к ресурс-адаптеру через опрос (polling) или "выстреливающие" (firing) события

Оба сервера Oracle WebLogic Server 10 g R3 и Oracle Application Server 10 g R3 поддерживают JCA версии 1.5.

Oracle Adapter Framework - это слой (layer) поверх ресурс-адаптеров JCA. Он использует сервисные технологии для показа своих адаптеров и API. Преимущество (такого подхода) в том, что приложения не на Java могут получать доступ к этим адаптерам. Другое преимущество - это отсутствие кодирования, нужно только конфигурирование.

Oracle JDeveloper предлагает поддержку на этапе проектирования для конфигурирования адаптеров и использования их из JEE-приложений и продуктов Oracle Fusion Middleware. Отметим, что другие средства этапа проектирования  - Application Explorer и Oracle Studio - можно использовать с несколькими тиражируемыми приложениями и адаптерами для мейнфреймов.

Применение на практике

Use Case

Данный раздел основан на проекте пользователя, в котором Oracle SOA Suite используется для создания среды SOA. Одно из требований этого проекта заключается в том, что процессы могут быть активированы через получаемые сообщения электронной почты, их преобразования и передачу данному процессу.

В проекте используется следующая модель для определения назначений функциональности и ответственностей сервисным слоям:

Рис. 4: Слои в среде SOA

Как показано на Рис. 4, роль сервисной шины предприятия (ESB) заключается в соединении сервисных слоев и интеграции различных базовых технологий и приложений - и их элементарных сервисов - в среде SOA. На основе этой модели интеграционный сценарий для получения почтовых сообщений и передачи их процессам реализуется через слой ESB. Так как Oracle ESB не обладает стандартной функциональностью для соединений с почтой, то необходим заказной адаптер для входящих сообщений.

Рис. 5: Интеграционный сценарий, рассматриваемый в этой статье

Эта задача разбивается на следующие шаги:

• Разработка, развертывание и тестирование упрощенного JCA ресурс-адаптера, который производит опрос для (обнаружения) почтовых сообщений
• Разработка требуемых артифактов Adapter Framework.
• Использование адаптера от Oracle ESB. Отметим, что хотя в данном случае фокус на Oracle ESB, те же самые шаги используются для Oracle BPEL Process Manager.

Прочитайте и выполните шаги в accompanying setup guide прежде чем продолжать со следующими (ниже) шагами.

Шаг 1: Реализация JCA-интерфейсов

Чтобы разработать ресурс-адаптер, вы должны реализовать несколько Java-интерфейсов. Некоторые из них широкого назначения, а другие предназначены для либо входящих (inbound), либо уходящих (outbound) взаимодействий. Наиболее важными из этих интерфейсов являются:

• javax. resource. spi. ResourceAdapter - это экземпляр ресурс-адаптера, который содержит операции для управления жизненным циклом и установки конечных точек сообщений (message endpoint), таких как старт start(BootStrapContext) и stop()
• javax. resource. cci. Record - определяет полезную нагрузку (payload) или содержание сообщений, обмен которыми происходит между ресурс-адаптером и клиентскими компонентами.
• javax. resource. spi. ActivationSpec - содержит информации о конфигурации, которая нужна для активизации конечной точки ресурс-адаптера.
• javax. resource. spi. work. Work, javax. resource. spi. work. WorkManager - интерфейсы управления жизненного цикла для создания нитей (thread), расписаний (scheduling), pooling и выполнения приложением.
• javax. resource. spi. ManagedConnectionFactory, javax. resource. spi. ManagedConnection - интерфейсы управления соединениями, используемые для создания соединений к EIS. Эти классы поддерживают работу с пулами соединений .

В следующую секцию включены диаграммы, которые иллюстрируют отношения и взаимодействия между JCA-интерфейсами и реализацией нашего заказного ресурс-адаптера.

Применение на практике

Use Case

Мы разработаем простой, не транзакционный ресурс-адаптер для входящих (согласно JCA) сообщений, который производит опрос для обнаружения новых почтовых сообщений и удаляет их после прибытия. Его проектирование показано на следующей диаграмме на UML:

Рис. 6: Диаграмма UML Class Diagram показывает соответствующие JCA-интерфейсы
для "входящих" адаптеров в левой части. В правой части показана реализация требуемых интерфейсов посредством заказного почтового JCA ресурс-адаптера.

Рис. 7: Диаграмма UML Sequence Diagram показывает порядок вызовов для заказного почтового "входящего" (inbound) JCA ресурс-адаптера.

Как объясняется в руководстве по установке (setup guide), вы можете выбирать между следующими средами для развертывания JCA ресурс-адаптера и тестировать его с использованием JMS клиента:

• Oracle JDeveloper 10 g и Oracle WebLogic 9.2 MP3
• Oracle JDeveloper 10 g и Oracle Application Server 10 g
• Oracle JDeveloper 11 g и Oracle WebLogic 10 g Release 3

Данная секция содержит инструкции для всех этих трех сред.

Пример на JDeveloper application workspace - независимо от выбранной среды  - содержит следующие проекты:

• MailResourceAdapter

Содержит реализацию для входящего JCA 1.5 ресурс-адаптера, который производит опросы новых почтовых сообщений. Сообщения же, сгенерированные этим ресурс-адаптером, публикуются любому клиенту, который подписан на него и реализовал интерфейс MessageListener interface так, как он продекларирован в дескрипторах развертывания (deployment descriptors).

Отметим, что вы можете игнорировать пакет nl. approachalliance. otn. jca.soasuite и его содержание в данный момент. Эти классы являются частью артифактов среды Adapter Framework и обсуждаются позже.

• MailResourceAdapterDeployment

Содержит общий (generic) дескриптор развертывания JCA (ra.xml), дескриптор развертывания целевого сервера приложений времени выполнения JCA (weblogic-ra.xml для Oracle WebLogic Server или oc4 j- ra.xml для Oracle Application Server), и профиль развертывания архива (RAR) ресурс-адаптера для данного целевого сервера приложений.

<connector
    xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    version="1.5"               
    xmlns:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd">
  <display-name>Mail JCA Resource Adapter</display-name>
  <vendor-name>Oracle Technology Network</vendor-name>
  <eis-type>Mail Server</eis-type>
  <resourceadapter-version>1.0</resourceadapter-version>
  <resourceadapter>
    <resourceadapter-class>nl.approachalliance.otn.jca.MailResourceAdapter</resourceadapter-class>
    <inbound-resourceadapter>
      <messageadapter>
        <messagelistener>
          <messagelistener-type>javax.resource.cci.MessageListener</messagelistener-type>
          <activationspec>
            <activationspec-class>nl.approachalliance.otn.jca.MailActivationSpec</activationspec-class>
            <required-config-property>
              <config-property-name>host</config-property-name>
            </required-config-property>
            <required-config-property>
              <config-property-name>username</config-property-name>
            </required-config-property>
            <required-config-property>
              <config-property-name>password</config-property-name>
            </required-config-property>
            <required-config-property>
              <config-property-name>provider</config-property-name>
            </required-config-property>
            <required-config-property>
              <config-property-name>pollingInterval</config-property-name>
            </required-config-property>
            <required-config-property>
              <config-property-name>folder</config-property-name>
            </required-config-property>
          </activationspec>
        </messagelistener>
      </messageadapter>
    </inbound-resourceadapter>
  </resourceadapter>

</connector>
  

Наш ресурс-адаптер стартует после успешного развертывания или когда сервер приложений стартует после развертывания этого адаптера.

<weblogic-connector 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.bea.com/ns/weblogic/90/weblogic-ra.xsd"
    xmlns="http://www.bea.com/ns/weblogic/weblogic-connector">
 <jndi-name>jca/MailResourceAdapter</jndi-name> 
 <enable-access-outside-app>true</enable-access-outside-app>

 </weblogic-connector>

• MailResourceAdapterClient

Содержит EJB Message-Driven Bean (MDB), который действует как клиент к JCA ресурс-адаптеру, общий дескриптор развертывания EJB (ejb-jar.xml) и профиль развертывания и дескрипторы развертывания (weblogic-ejb-jar.xml) для целевого сервера приложений времени выполнения. Этот MDB подписывается к нашему ресурс-адаптеру. Для каждой почты, которая опрашивается адаптером метод onMessage() method из этого MDB вызывается.

Как определено соответствием Java-стандартов, клиенты - это EJB 2.1 MDB при использовании Oracle WebLogic Server 9.2 и EJB 3 MDB при использовании Oracle WebLogic Server 10 g R3 и Oracle Application Server 10 g R3.

<ejb-jar  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee  http://java.sun.com/xml/ns/j2ee/ejb-jar_3_0.xsd"
  version="3.0"  xmlns="http://java.sun.com/xml/ns/javaee">

 <enterprise-beans>
  <message-driven>
   <description>EJB 3.0 Message Driven Bean (MDB) that acts as client for 
                                                        the Mail JCA Resource Adapter</description>
   <display-name>MailResourceAdapterClientMDBBean</display-name>
   <ejb-name>MailResourceAdapterClientMDBBean</ejb-name>

   <ejb-class>nl.approachalliance.otn.jca.MailResourceAdapterClientMDBBean</ejb-class>
   <messaging-type>javax.resource.cci.MessageListener</messaging-type>
   <transaction-type>Container</transaction-type>
   <activation-config>

     <activation-config-property>
      <activation-config-property-name>host</activation-config-property-name>
      <activation-config-property-value>localhost</activation-config-property-value>
     </activation-config-property>
     <activation-config-property>

      <activation-config-property-name>username</activation-config-property-name>
      <activation-config-property-value>otn</activation-config-property-value>
     </activation-config-property>
     <activation-config-property>
      <activation-config-property-name>password</activation-config-property-name>

      <activation-config-property-value>welcome1</activation-config-property-value>
     </activation-config-property>
     <activation-config-property>
      <activation-config-property-name>provider</activation-config-property-name>
      <activation-config-property-value>pop3</activation-config-property-value>

     </activation-config-property>
     <activation-config-property>
      <activation-config-property-name>pollingInterval</activation-config-property-name>
      <activation-config-property-value>5</activation-config-property-value>
     </activation-config-property>

     <activation-config-property>
      <activation-config-property-name>folder</activation-config-property-name>
      <activation-config-property-value>INBOX</activation-config-property-value>
     </activation-config-property>
   </activation-config>

  </message-driven>
 </enterprise-beans>
</ejb-jar>

 <weblogic-ejb-jar 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.bea.com/ns/weblogic/weblogic-ejb-jar.xsd"
   xmlns="http://www.bea.com/ns/weblogic/weblogic-ejb-jar">

  <weblogic-enterprise-bean>
   <ejb-name>MailResourceAdapterClientMDBBean</ejb-name>
   <message-driven-descriptor>
    <resource-adapter-jndi-name>jca/MailResourceAdapter</resource-adapter-jndi-name>
   </message-driven-descriptor>

  </weblogic-enterprise-bean>
 </weblogic-ejb-jar>

Перед развертыванием и тестированием нашего JCA ресурс-адаптера убедитесь, что почтовый сервер Apache JAMES стартуется запуском <JAMES home>/bin/run.bat.

Развертывание и тестирование нашего JCA ресурс-адаптера для Oracle WebLogic 9.2 MP3

1. tВ продукте Oracle JDeveloper 10g откройте рабочее пространство приложения JCA ресурс-адаптер из архива проекта (projects zip file). Выберите Open Application из Applications Navigator. Перейдите к JDeveloper_10 g/ Oracle_WebLogic_Server_92/JCA_ResourceAdapter/JCA_ResourceAdapter.jws и выберите Open.
2. Копируйте connector15.jar, orabpel.jar и orabpel-thirdparty.jar из <SOA Suite home>/bpel/lib директории в директорию библиотеки проекта MailResourceAdapter project. Эти JAR-файлы помимо других включают требуемые интерфейсы JCA и XML Record Converter interfaces. Также копируйте connector15. jar в директорию библиотеки проекта MailResourceAdapterClient project.
3. Стартуйте Oracle WebLogic Server 9.2 домен (domain) и сервер, на котором выполняется Oracle SOA Suite, если он еще не стартован.
4. Установите наш заказной ресурс-адаптер в среде Oracle WebLogic Server. Откройте фолдер Resources folder проекта MailResourceAdapterDeployment project в Applications Navigator. Кликните правой клавишей MailResourceAdapter.deploy file и выберите Deploy to RAR file .

Подсоединитесь (Log in) к Oracle WebLogic Server Administration Console - по умолчанию http://localhost:8001/console -   используя" weblogic" как имя пользователя (username) и пароль. Выберите Lock & Edit. Выберите Deployments →Install. Перейдите к директории развертывания (deploy directory) проекта MailResourceAdapterDeployment project, выберите MailResourceAdapter. rar file, и кликните Next. Выберите Install this deployment as an application и кликните Next . Выберите OracleSOAServer в списке серверов и кликните Next. Примите все другие значения по умолчанию.

Выберите Activate Changes для развертывания нашего ресурс-адаптера.

Проверьте состояние приложения MailResourceAdapter в Oracle WebLogic Server Administration Console. Стартуйте это приложение, если состояние "Prepared".

5. Установите клиента в среде Oracle WebLogic Server. Откройт фолдер Resources folder проекта MailResourceAdapterClient project в Applications Navigator . Кликните правой клавишей MailResourceAdapterClient.deploy file и выберите Deploy to JAR file.

Подсоединитесь к Oracle WebLogic Server Administration Console. Выберите Lock & Edit. Выберите Deployments → Install. Перейдите к директории развертывания проекта MailResourceAdapterClient project, выберите MailResourceAdapterClient.jar file и кликните Next . Выберите Install this deployment as an application и кликните Next . Выберите OracleSOAServer в списке серверов и кликните Next. Примите все другие значения по умолчанию.

Выберите Activate Changes для развертывания MDB.

Проверьте состояние приложения MailResourceAdapterClient в Oracle WebLogic Server Administration Console. Стартуйте это приложение, если состояние "Prepared".

6. Подсоединяйтесь к Oracle WebLogic Server Administration Console. Выберите Deployments. Наш ресурс-адаптер и MDB-клиент видимы в таблице развертывания; оба с " State" Active и "Health" OK.

Рис. 8: Oracle WebLogic Server Administration Console показывает ресурс-адаптер и MDB-клиент в таблице развертывания.

7. Тестируйте наш ресурс-адаптер и его клиент, посылая сообщение электронной почты на jca@ localhost, при этом используя почтовый клиент типа Mozilla Thunderbird.
8. Проверьте число сообщений, которые выбраны из очереди (dequeued) клиентским Message- Driven Bean. Подсоединитесь к Oracle WebLogic Server Administration Console и перейдите к Deployments → MailResourceAdapterClient → MailResourceAdapterClientMDBBean (by expanding the MailResourceAdapterClient application) → Monitoring. В таблице Running tab, добавьте колонку " Processed Message Count", если эта колонка еще не показалась в этой таблице. Консоль показывает число обработанных сообщений (должно быть одно такое сообщение).

Рис. 9: Oracle WebLogic Administration Console, показывающая информация мониторинга для MDB клиента.

Развертывание и тестирование JCA ресурс-адаптера для Oracle Application Server 10 g

1. В Oracle JDeveloper 10g, откройте рабочее пространство (workspace) приложения JCA ресурс-адаптер из архивного файда проектов (projects zip file). Выберите Open Application из Applications Navigator . Перейдите к JDeveloper_10g/Oracle_Application_Server_10g/JCA_ResourceAdapter/JCA_ResourceAdapter.jws и выберите Open .
2. Скопируйте connector15.jar, orabpel.jar, и orabpel-thirdparty.jar из <SOA Suite home>/bpel/lib directory в директорию проекта MailResourceAdapter project. Эти JAR-файлы среди многих других включают нужные интерфейсы JCA and XML Record Converter interfaces. Также скопируйте connector15.jar в директорию библиотеки проекта MailResourceAdapterClient project.
3. Стартуйте Oracle Application Server 10g, в среде которого Oracle SOA Suite будет выполняться, если этот сервер еще не запущен.
4. Установите наш заказной ресурс-адаптер в среде Oracle Application Server. Откройте Resources folder проекта MailResourceAdapterDeployment project в Applications Navigator. Кликните правой клавишей MailResourceAdapter. deploy file и выберите Deploy to →(OAS_SOA_Suite_10g   (имя соединения Application Server connection как указано в руководстве).
5. Установите клиент в среде Oracle Application Server. Откройте Resources folder проекта MailResourceAdapterClient project в Applications Navigator . Кликните правой клавишей MailResourceAdapterClient.deploy file и выберите Deploy to → OAS_SOA_Suite_10g . 
6. tТестируйте ресурс-адаптер и его клиент, посылая постовое сообщение на jca@ localhost с использованием почтового клиента типа Mozilla Thunderbird.
7. Проверьте число сообщений, выбранных из очереди клиентом Message- Driven Bean. Подсоединитесь к Oracle Application Server Enterprise Manager и перейдите к Cluster Topology → oc4j_soa → Applications →MailResourceAdapterClient→MailResourceAdapterClient (EJB Module) → MailResourceAdapterClientMDBBean. Консоль покажет число выбранных сообщений (должно быть одно) и значения для активизации ресурс-адаптера (adapter activation spec).

Рис. 10: Enterprise Manager показывает информацию о клиентском MDB.
Консоль показывает значения для активизации в среде JCA (JCA activation spec) и сообщает, что одно сообщение получено.

Развертывание и тестирование JCA ресурс-адаптера для JDeveloper 11 g с Integrated WebLogic Server 10 g R3

1. В Oracle JDeveloper 11g, откройте рабочее пространство приложения JCA ресурс-адаптера из архивного файла проектов. Выберите Open Application из Applications Navigator. Перейдите к JDeveloper_11 g/ JCA_ ResourceAdapter/ JCA_ ResourceAdapter. jws и выберите Open.
2. Копируйте orabpel. jar и orabpel- thirdparty. jar из директории <SOA Suite home>/ bpel/ lib в директорию библиотеки проекта MailResourceAdapter project. Эти JAR-файлы помимо прочего включают требуемые интерфейсы XML Record Converter interfaces. Проверьте, что библиотека WebLogic 10.3 Remote-Client library перечислена в Libraries and Classpath проектов MailResourceAdapter и MailResourceAdapterClient projects. Эта библиотека включает требуемые JCA-интерфейсы.
3. Стартуйте JDeveloper Integrated WebLogic Server, выбирая Run → Start Server Instance.
4. Установите JCA ресурс -адаптер в среде Integrated WebLogic Server. Кликните правой клавишой проект MailResourceAdapterDeployment project в Applications Navigator и выберите Deploy → MailResourceAdapter → to IntegratedWLSConnection.
5. Установите клиент в среде Integrated WebLogic Server. Кликните правой клавишой проект MailResourceAdapterClient project в Applications Navigator и выберите Deploy → MailResourceAdapterClient → to IntegratedWLSConnection.
6. Подсоединитесь к Oracle WebLogic Server Administration Console, по умолчанию используя http://localhost:7101/console "weblogic" как имя пользователя и пароль. Выберите Deployments. Ресурс-адаптер и MDB клиент видимы в таблице развертываний (deployments table); оба с "State" Active и "Health" OK.

Рис. 11: Oracle WebLogic Server Administration Console показывает ресурс-адаптер и MDB клиент в таблице развертываний.

7. Тестируйте ресурс-адаптер и его клиент, посылая почтовое сообщение на jca@ localhost с использованием почтового клиента типа Mozilla Thunderbird.
8. Проверьте число сообщений, выбранных из очереди клиентским MDB. Подсоединяйтесь к Oracle WebLogic Server Administration Console и перейдите к Deployments → MailResourceAdapterClient → MailResourceAdapterClientMDBBean (расширяя приложение MailResourceAdapterClient) → Monitoring. В таблице Running tab, добавьте колонку "Processed Message Count", если эта колонка не показана еще в этой таблице. Консоль показывает число обработанных сообщений (должно быть одно).

Рис. 12: Oracle WebLogic Administration Console показывает информацию мониторинга для MDB клиента.

Итак, вы развернули заказной JCA ресурс-адаптер, развернули JMS-клиент и протестировали этот адаптер, посылая почтовые сообщения и затем получая их в MDB! Продолжим, интегрируя наш адаптер с компонентами Oracle SOA Suite и применяя для этого Adapter Framework.

Шаг 2: Подключение среды Adapter Framework

Oracle Adapter Framework (Adapter SDK) - это легковесная среда (lightweight framework), которая выставляет напоказ ресурс-адаптеры для JCA 1.0 и 1.5 с применением XML и Web-сервисной технологии.

Во время выполнения компоненты SOA Suite вызывают ресурс-адаптеры с использованием вызовов среды Web Service Invocation Framework (WSIF). Среда Adapter Framework транслирует эти WSIF-вызовы в JCA-вызовы в соответствии с контрактом JCA CCI и его API.

Note: WSIF - это Java API-интерфейс, поддерживаемый Apache.   Читайте статью на OTN "Using WSIF for Integration" (Использование WSIF для интеграции), чтобы узнать, как WSIF может влиять на производительность транзакций. WSIF может использоваться вместо чистого SOAP, чтобы обеспечить применение других, более нестандартных, но быстрых протоколов, таких как локальные Java-вызовы или RMI, но при этом определяя компонент стандартным для web-сервисов образом, таким как WSDL. Оцените протокол связывания (binding), который должен использоваться во время выполнения. Это может привести к лучшей производительности.

WSDL хранит информацию, которая необходима клиентским компонентам для вызова адаптера, а также для Adapter Framework, чтобы транслировать вызовы WSIF в соответствующие вызовы JCA адаптера. WSDL содержит специфичные для JCA расширения, чтобы хранить информацию, связанную с адаптером. И наоборот, тот же самый механизм - в противоположном направлении  - используется для входящих JCA взаимодействий.

Oracle JDeveloper предлагает визарды (wizards) в дизайнерах BPEL PM и ESB для определения и генерации содержания адаптерских WSDLs и XML во время проектирования. Adapter Framework также предлагает функциональность для времени проектирования, чтобы извлекать метаданные EIS, включая бизнес-сервисы и объекты.

Применение на практике

Use Case

Мы выполним следующие задачи, чтобы использовать наш заказной адаптер из Oracle ESB через Adapter Framework:

• Создать отображение (mapping) для преобразований между JCA записями и Oracle XML записями. Этот отображение называется Oracle XML Record Converter. Оно состоит из реализаций Java-интерфейсов.
• Создать определение адаптера, которое специфицирует наш ресурс-адаптер, его конфигурацию и реализацию XML Record Converter implementation. Это определение состоит из WSDL-файла с специфичными для JCA расширениями. Для prepackaged адаптеров это обычно делается через визарда JDeveloper.
• Опубликовать все нужные Java-артифакты времени выполнения, такие как ресурс-адаптер и классы XML Record Converter classes, как библиотеку сервера приложений.

XML Record Converter

1. Откройте и просмотрите XML Schema MailAdapter. xsd, который определяет XML payload, используемую в проекте нашей Oracle ESB. Этот файл находится в архивном файле директории проектов Adapter_Framework. Используемый XSD прост и понятен.
2. Откройте и просмотрите реализацию XML Record Converter в Oracle JDeveloper. Эти классы находятся в пакете nl.approachalliance. otn. jca. soasuite проекта MailResourceAdapter. В этом пакете два класса:
   1. MailXMLRecord.java - Класс, представляющий почтовое сообщение. Помимо актуального содержания (actual payload) вы можете также специфицировать вложения (attachments), информацию заголовков (header information), имя записи, приоритет и другие атрибуты..
   2. MailRecordElement.java - Класс, представляющий payload почтового сообщения как DOM-источник. Другие возможные источники - это SAX- и Stream-источники. Этот класс также содержит методы convenience для получения темы сообщения из адресов и других атрибутов.
   3. MailXMLRecordConverter.java - Класс, содержащий логику преобразования экземпляра MailRecord в экземпляр MailXMLRecord и наоборот.

WSDL

Adapter Framework требует, чтобы стандартный WSDL был обогащен специфичной для JCA- и XML Record Converter информацией для того, чтобы обеспечить соединение к JCA ресурс-адаптеру во время выполнения и преобразование JCA записей в XML.

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

Рис. 13: Стандартный WSDL, обогащенный специфичной для Adapter Framework и JCA информацией.

WSDL для нашего заказного ресурс-адаптера показан в листинге 5.

<definitions  name="MailAdapter"             
       targetNamespace="http://www.approachalliance.nl/otn/adapter/mail"                 
       xmlns="http://schemas.xmlsoap.org/wsdl/"             
       xmlns:jca="http://xmlns.oracle.com/pcbpel/wsdl/jca/"             
       xmlns:tns="http://www.approachalliance.nl/otn/adapter/mail"             
       xmlns:pc="http://xmlns.oracle.com/pcbpel/"             
       xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"             
       xmlns:adapter="http://www.approachalliance.nl/otn/adapter/mail">

     <types>
       <schema xmlns="http://www.w3.org/2001/XMLSchema">
         <import namespace=http://www.approachalliance.nl/otn/adapter/mail  schemaLocation="MailAdapter.xsd"/>
       </schema>
     </types>

     <message name="Read_msg">
       <part name="Mail" element="adapter:Mail"/>
     </message>
     <portType name="Read_ptt">

       <operation name="Read">
        <input message="tns:Read_msg"/>
       </operation>
     </portType>
     <binding name="Read_binding"  type="tns:Read_ptt">

       <pc:inbound_binding  XMLRecordConverterCallout="nl.approachalliance.otn.soasuite.adapter.MailXMLRecordConverter"/>
       <operation name="Read">
        <jca:operation 
              ActivationSpec="nl.approachalliance.otn.jca.MailActivationSpec"
             host="localhost" 
             username="jca"

             password="welcome1" 
             provider="pop3"
             pollingInterval="5"
             folder="INBOX">
        </jca:operation>

       </operation>
     </binding>
     <service name="MailAdapter">
       <port name="Read_pt"  binding="tns:Read_binding">

        <jca:address  ResourceAdapterClassName="nl.approachalliance.otn.jca.MailResourceAdapter"/>
       </port>
     </service>
     <plt:partnerLinkType name="Read_plt">
       <plt:role name="Read_role">

        <plt:portType name="tns:Read_ptt"/>
       </plt:role>
     </plt:partnerLinkType>
</definitions>
  

Библиотека публикования (Publish library)

Чтобы продукты SOA Suite использовали наш заказной адаптер во время выполнения l, этот адаптер должен быть опубликован в среде сервера приложений, в которой и исполняется SOA Suite.

Выполните шаг 3, если вы запускаете SOA Suite на Oracle WebLogic Server 9.2. Выполните шаг 4, если вы запускаете SOA Suite на Oracle Application Server 10 g .

3. Публикуйте артифакты заказного адаптера в среде Oracle WebLogic Server 9.2:
   1. tУберите клиентский MDB, который мы использовали в предыдущей секции. Подсоединитесь (Log in) к Oracle WebLogic Server Administration Console и перейдите к SOADomain → Deployments →Applications. Кликните Lock & Edit для модификации, добавления или уничтожения элементов (items) в этом домене. Выберите приложение MailResourceAdapterClient application и кликните Delete. Выберите Yes и кликните Activate Changes.
   2. Публикуйте эту библиотеку. Копируйте MailResourceAdapter. jar из директории MailResourceAdapter/ deploy directory в директорию <BEA Home>/user_projects/domains/SOADomain/lib directory.
   3. Перестартуйте Oracle WebLogic Server.

4. Публикуйте артифакты заказного адаптера в среде Oracle Application Server 10 g :
   1. Уберите клиентский MDB, который мы использовали в предыдущей секции. Подсоединйтесь к Oracle Application Server Enterprise Manager и переходите к Cluster Topology → oc4j_soa →Applications. Выберите приложение MailResourceAdapterClient application и кликните Undeploy .
   2. Публикуйте эту библиотеку. В Oracle Application Server Enterprise Manager перейдите к разделяемой (shared) библиотеке Oracle BPEL shared library через выбор Cluster Topology → oc4j_soa → Administration → Shared Libraries → oracle.bpel.common → Edit (в секции Archives section).
   3. Добавьте JAR-файл из первого шага, выбирая Add и затем MailResourceAdapter. jar из директории MailResourceAdapter/ deploy directory.
   4. Выберите OK и перестартуйте Oracle Application Server.

Теперь, создав требуемые артифакты Adapter Framework, мы можем начать использование нашего заказного адаптера в сценарии интеграции.

Шаг 3: Построить поток сервисной шины ( Build the Enterprise Service Bus Flow )

Сервисная шина облегчает реализацию сервисов более низкого уровня в рамках SOA и EDA. Она основана (желательно) на открытых стандартах (XPath, XSLT, SOAP, JMS, JCA и так далее). Эти шины (ESBs) особенно хорошо подходят для виртуализации, маршрутизации (routing) и преобразования данных, тем самым отделяя эти проблемы от этапов проектирования, реализации и выполнения бизнес-логики и процессов. На этих этапах из стека продуктов Oracle задействуются инструменты класса BPA, BPM и BPEL. В нашем случае нам сначала нужны адаптер, преобразования и маршрутизация, а только потом бизнес- и процессная логика. Поэтому наш интеграционный сценарий реализуется как проект Oracle ESB project, Хотя те же самые шаги применяются и к Oracle BPEL Process Manager.

Use Case

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

1. В продукте Oracle JDeveloper, создайте рабочее пространство нового приложения для размещения вашего ESB-приложения. Кликните правой клавишой по Applications в Applications Navigator. Выберите New Application… и введите ESB_CustomAdapter как имя приложения. Примите значения по умолчанию и кликните OK для создания приложения. Выберите Cancel в диалоговом окне Create Project.

Рис. 14: Создание нового приложения в Oracle JDeveloper

2. Applications Navigator, кликните правой клавишей только что созданное новое приложение и выберите New Project…. Выберите General →Projects→ESB Project из диалогового окна New Gallery. Введите ESB_CustomAdapter как имя проекта, примите все другие значения по умолчанию и кликните OK. Oracle JDeveloper создаст новый проект ESB, содержащий файлы jpr и esb. Файл esb file, названный ESB_ CustomAdapter. esb, автоматически открывается в ESB Designer.

Рис. 15: Создание нового проекта ESB в Oracle JDeveloper

Следующие шаги включают структурирование сервисов в вашем проекте ESB. С этой целью используются системные и сервисные группы. Системы - это обязательные организационные единицы высокого уровня, а сервисные группы - это опциональные суборганизационные единицы. Это означает, что сервис - это либо часть другой сервисной группы, либо он прямо принадлежит некоторой системе.

3. Кликните иконку Create System/Group в верху ESB Designer . Это приведет к открытию диалогового окна Create ESB System или Service Group. Выберите System, введите "OTN" как имя (описания есть опция). Кликните OK для создания нового системного определения ESB.

Рис. 16: Опция Create System/ Service Group в ESB Designer продукта Oracle JDeveloper
Рис. 17: Создание ESB System "OTN" в Oracle JDeveloper

4. Еще раз откройте диалоговое окно Create ESB System or Service Group . В этот раз выберите Service Group. Будет показана дополнительная опция, которая позволит вам выбрать систему, частью которой будет новая сервисная группа. Если эта система еще не определена как OTN, сделайте это, кликая по flashlight иконке. Это откроет ESB Service Group Browser.
5. Выберите OTN для системы, созданной на предыдущем шаге и кликните OK. Вернитесь к диалоговому окну Create ESB System or Service Group, введите CustomAdapter как имя (описание есть опция), и кликните OK для создания новой сервисной группы.

Рис. 18: ESB Service Group Browser в Oracle JDeveloper

Рис. 19: Создание сервисной группы " CustomAdapter" в Oracle JDeveloper как часть системы "OTN"

Теперь мы можем приступить к определению нашего заказного адаптера!

6. Копируем MailAdapter. wsdl и   MailAdapter. xsd (размещенные в директории ESB в архивном файле (zip file) проектов) в корневую директорию данного проекта ESB. Это определения адаптера и содержание сообщений как описано в секции Adapter Framework.
7. Создайте заказной адаптер, который будет опрашивать новые почтовые сообщения. Убедитесь, что ESB Designer открыт. Из Component Palette справа, выберите ESB Services и перетащите Custom Adapter на окно ESB Designer. Это откроет диалоговое окно Create Adapter Service.

Рис. 20: Создание заказного адаптера

Введите Receive_Mail как имя сервиса (описание опционально).   Убедитесь, что OTN. CustomAdapter выбран как содержащий System/Group. Если он еще не выбран, используйте flashlight иконку для открытия браузера ESB Systems/Groups browser и выберите OTN →CustomAdapter.

8. Кликните Browse WSDL Files From Local File System... и выберите MailAdapter.wsdl файл . Отметим, что корректный тип порта Read_ ptt как предварительно определенный в WSDL  уже обеспечен. Кликните OK для создания заказного адаптера.

Рис. 21: Создание заказного адаптера

Сервис маршрутизации (routing service) для этого файлового адаптера входящих сообщений, названный Receive_Mail_RS, автоматически добавлен к данному проекту, когда визард этого файлового адаптера завершен. Этот адаптер предоставляет возможности маршрутизации и преобразования.

Рис. 22: ESB Designer после создания сервиса почтового адаптера входящих сообщений

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

9. Создайте файловый адаптер для выходящих сообщений, который будет опрашивать новые Acme invoice файлы. Убедитесь, что ESB Designer открыт. Из Component Palette справа выберите Adapter Services и перетащите File Adapter на окно ESB Designer window. Это приведет к открытию диалогового окна Create File Adapter Service dialog box.

Рис. 23: Создание файлового адаптера

Введите Publish_Mail как имя сервиса и опционально добавьте описание. Убедитесь, что OTN.CustomAdapter выбран как содержащая (сервисную группу) System/Group. Если он еще не выбран, используйте flashlight икону для открытия браузера ESB Systems/Groups и выберите OTN →CustomAdapter.

10. Кликните иконку Configure adapter service wsdl, рядом с WSDL File, чтобы открыть визард Adapter Configuration Wizard и продолжайте с конфигурацией сервиса адартера.

Рис. 24: Шаг 2 визард File Adapter Configuration Wizard

Рис. 25: Шаг 3 визард File Adapter Configuration Wizard

В данном визарде используйте следующие установки (settings):

1. Шаг 1: Примите значения по умолчанию.
2. Шаг 2: Operation Type: Write File.
3. Шаг 3: Operation Name: Publish_Mail.
4. Шаг 4: Directory Names заданы как : Physical Path.
5. Шаг 5: Directory for Outgoing Files (physical path): существующая директория на машине, на которой ESB выполняется, например C:/ temp.
6. Шаг 6: File Naming Convention: mail_%yyMMddHHmmssSS%.xml.
7. Шаг 7: Писать в новый файл, когда существующий соответствует одному из этих условий - Number of Messages Equals: 1. 
8. Шаг 8: Кликните browse и выберите Project Schema Files → MailAdapter.xsd →Mail. Отметим, что это та же схема, которая использовалась заказным адартером.

Рис. 26: ESB Designer после создания сервиса файлового адаптера для уходящих сообщений

Теперь нам нужно только соединить наш заказной почтовый адаптер для входящих сообщений к файловому адаптеру для уходящих сообщений. Как ранее отмечалось, Oracle JDeveloper автоматически создал сервис маршрутизации для нашего заказного адаптера для входящих сообщений. Однако, этот сервис маршрутизации не содержит никакой логики маршрутизации или преобразований. Давайте создадим необходимую функциональность для соединения заказного адаптера для входящих сообщений с файловым адаптером для уходящих.

11. Откройте Receive_Mail_RS сервис маршрутизации двойным кликом по нему в ESB Designer. Этот сервис включает единственную операцию, Read, без правил маршрутизации. (Отметим, что опция Invocable from an external service выбрана по умолчанию. Это означает, что во время развертывания ESB проекта некоторый Web-сервис будет создан, который при исполнении вызывает этот сервис маршрутизации. Эта особенность может быть использована для тестирования. Если вам не нужно, чтобы сервис маршрутизации внешне вызывался, откажитесь от выбора опции Invocable from an external service option.
12. Добавьте правило маршрутизации, кликнув по green + icon справа от операции Receive_Mail. Диалоговое окно Browse Target Service Operation откроется .

Рис. 27: Сервис маршрутизации без правил маршрутизации для операции Read

13. Выберите сервис Publish_Mail файлового адаптера, который мы создали ранее, как цель.

Рис. 28: Выбор сервиса Publish_Mail файлового адаптера для уходящих сообщений как целевого сервиса

Окно Routing Service показывает, что вставка (insert) синхронно вызывается после того, как почтовое сообщение получено заказным почтовым адаптером.

Рис. 29: Сервис маршрутизации, включающий правило маршрутизации для операции Read

Вы должны также создать правило преобразования, так как XML-формат входящих файлов inbound invoice files отличается от XML-формата, с которым работает адаптер базы данных.

14. Кликни по иконке XSL mapping рядом с <<Transformation Map>> для создания файла преобразования (XSL). В этом диалоговом окне выберите Create New Mapper File, примите имя по умолчанию Mail_ To_ Mail. xsl, и кликните OK. Это откроет инструмент XSLT Mapper. Вы увидите XML-структуру почтового сообщения на обоих сторонах both-hand sides этого интструмента.

Рис. 30: Инструмент XSLT mapper в Oracle JDeveloper

XSLT mapper позволит вам визуально определять отображения (mappings) входных элементов в выходные посредством операций drag-and- drop. Этот инструмент также предоставляет полную (auto- complete) функциональность для входных и выходных элементов с похожими именами.  

15. Проверьте эту полную функциональность, перетаскивая элемент imp1: Mail слева на элемент imp1: Mail справа. После этого появится диалоговое окно Auto Map Preferences.

Рис. 31: Входные и выходные XML-файлы для авто-отображения (auto-mapping) с использованием инструмента XSLT mapper в Oracle JDeveloper

Оставьте значения по умолчанию этого инструмента неизменными и кликните OK. Все элементы отображены. Результирующее отображение должно выглядеть примерно так:

Рис. 32: Окончательное отображение Final mapping

16. Сохраните все файлы в ESB проекте, кликнув Save All.

Проект завершен и готов к развертыванию на ESB сервере and taken for a spin! Приступим к развертыванию и тестированию потока ESB (ESB flow) и его заказному адаптеру. Эти шаги одни и те же, как для Oracle ESB в среде Oracle WebLogic 9.2, так и для Oracle ESB в среде Oracle Application Server 10g.

Развертывание и тестирование ESB проекта

1. Стартуйте почтовый сервер Apache JAMES, если он еще не запущен.
2. В Oracle JDeveloper 10g либо откройте ESB проект, созданный на предыдущем шаге, либо ESB проект из архивного файла проектов.
3. Разверните ESB проект в среде Oracle Application Server, кликая правой клавишей проект в Applications ( Navigator и выбирая Register with ESB. Oracle JDeveloper сообщит вам, что OTN system, CustomAdapter service group и адаптеры, и сервисы маршрутизации созданы на этом сервере.

Рис. 33: Регистрация ESB проекта с Oracle ESB

Рис. 34: Регистрация успешно завершена

4. Откройте ESB console в окне браузера для просмотра зарегистрированного ESB потока. Адрес ESB console URL is http:// host: port/ esb . Например, http:// localhost:9700/ esb для ESB в среде Oracle WebLogic Server 9.2 и http:// localhost:80/ esb для ESB в среде Oracle Application Server 10 g.

Рис. 35: Oracle ESB Console

В обзоре Services overview, спуститесь (drill down) до просмотра OTN system, сервисной группы CustomAdapter и сервисов, которые вы только что создали и развернули.

Проверьте установки (settings) - такие как виртуальный хост (virtual host) и порт системы OTN system и если нужно, откорректируйте их для соответствия конфигурации вашей среды.

5. Инициируйте и тестируйте поток ESB, послав почтовое сообщение к jca@localhost с использованием почтового клиента типа Mozilla Thunderbird.

В результате это почтовое сообщение публикуется как XML-файл к директории, определенной в конфигурации файлового адаптера для уходящих сообщений.

И просмотрите весь завершенный экземпляр (completed instance) в ESB console.

Рис. 36 Успешно завершенный экземпляр ESB, использующий заказной JCA ресурс-адаптер для получения входящих почтовых сообщений.

Поздравляем, вы спроектировали, реализовали, внедрили и протестировали интеграционный сценарий из реальной жизни с применением своего заказного адаптера для электронной почты!

Стратегия Oracle по развитию порфолио продуктов Service Bus

На момент написания этой статьи корпорация Oracle предлагала две шины сервисов в своем продуктовом портфолио: Oracle Enterprise Service Bus и Oracle Service Bus (продукт, ранее известный как BEA AquaLogic Service). Последняя шина включает набор адаптеров собственной разработки и использует свою среду, Transport SDK, для создания заказных адаптеров. Обе шины будут позднее объединены.

Oracle Service Bus будет основой стратегии развития Oracle в области сервисных шин и будет обогащена такими функциями Oracle ESB, как Domain- Value Maps (DMV), поддержка XSLT, среды JCA и заказного адаптера. Хотя текущая версия OSB (10g Release 3 на момент написания этой статьи) еще не поддерживает заказных JCA ресурс-адаптеров, Oracle вскоре реализует соединения со всеми внешними средами в своей будущей SOA платформе. Это означает :

• Поддержка для адаптеров и среды JCA
• Консолидация перекрывающихся функций, таких как файловый транспорт в Service Bus и файловый адаптер Enterprise Service Bus, и разработка лучшей в своем классе единой опции для любой целевой системы

Текущее предложение адаптеров Oracle Enterprise Service Bus и Oracle Service Bus можно посмотреть в следующей таблице. Адаптеры сгруппированы по типам.

Читайте еще о стратегии развития Oracle для продукта Service Bus по адресу Statement of Direction (SOD).

Заключение

Хотя Oracle Fusion Middleware поставляется с несколькими адапетерами, эти адаптеры не всегда будут достаточны во всех интеграционных сценариях.

Узнайте об адаптерах независимых поставщиков прежде, чем приступить к построению своего. Важно уяснить, что вам понадобится знание, по меньшей мере, трех различных сред (frameworks) и того, как они взаимодействуют, чтобы создать и использовать заказной адаптер: JCA, Adapter Framework и продукт, в котором будет использоваться этот адаптер. Это особенно верно в части нефункциональных требований, таких как масштабируемость, высокая готовность, безопасность  и поддержка глобальных транзакций, что может оказаться непростой задачей.

Эти требования нужно разрешить в целом перед построением вашего адаптера.