Розробка агента IBM Lotus Domino з підтримкою JMS

1. Пропонована архітектура
2. Малюнок 1. Діаграма розгортання архітектури
3. огляд статті
4. Налаштування WebSphere MQ
5. Малюнок 2. Налаштування менеджера черг
6. Налаштування JNDI
7. Малюнок 3. Пакети JNDI supportPac
8. Малюнок 4. Оновлення CLASSPATH в JMSAdmin.bat
9. Створення адмініструються об'єктів JMS
10. Таблиця 1. Послідовність команд
11. Малюнок 5. Конфігурація JNDI
12. Малюнок 6. Черги в WebSphere MQ
13. Малюнок 7. Приклад програми Lotus Domino
14. Малюнок 8. Структурна схема Java-агента
15. Малюнок 9. Додавання JAR-файлів в Java-агент
16. Таблиця 2. JAR-файли JMS-продажу WebSphere MQ
17. код
18. Лістинг 1. Загальний код
19. Лістинг 2. Виробник повідомлень
20. Малюнок 10. Повідомлення в черзі
21. Малюнок 11. Повідомлення в WebSphere MQ
22. Лістінг 3. Споживач Повідомлень
23. Малюнок 12. Інформація про повідомленні в консолі Java
24. Малюнок 13. Повідомлення, збережені у вигляді документів Domino
25. Подякою
26. Ресурси для скачування

У багатьох організаціях в існуючих програмах IBM Lotus Domino є великий обсяг інформації і даних, необхідних іншим додаткам. У статті показується, як в IBM Lotus Domino Designer розробити Java-агент, підготовлений до запуску на сервері Lotus Domino. У цьому агента для відправки повідомлень JMS-провайдера і отримання від нього відповідних повідомлень використовується API Java Messaging Systems (JMS) 1.1, а також API Java Naming and Directory Interface (JNDI). Як провайдера повідомлень в статті застосовується IBM WebSphere MQ V6, однак за рахунок використання JMS 1.1 наш код дозволяє додаткам Lotus Domino підключатися до будь-якої корпоративної сервісної шини (enterprise service bus - ESB), що підтримує JMS. (Код тестувався на Lotus Domino V8, WebSphere MQ V6 і JMS 1.1 API, проте він також повинен працювати з Lotus Domino V5 і JMS 1.0 і пізніших версіях).

Стаття адресована програмістам Lotus Domino, бажаючим організувати взаємодію з системами обміну повідомленнями, скориставшись підтримкою Java API, яку надає Lotus Domino. Передбачається, що читач знайомий з мовою програмування Java і моделлю програмування Lotus Domino.

Пропонована архітектура

Перш ніж докладно розглянути наше рішення, ознайомимося з ним в загальних рисах. На малюнку 1 представлена ​​діаграма розгортання на мові Unified Modeling Language (UML), з якої стає зрозуміло, як працює приклад програми. Як видно, для роботи програми потрібні два окремих фізичних сервера: сервер Lotus Domino V8 і сервер WebSphere MQ V6. Звичайно ж, можна запустити додаток, розмістивши його на одному сервері, однак більш правдоподібним і наочним сценарієм є застосування розподіленої мережевої конфігурації. Крім того, з малюнка 1 видно, що сервер WebSphere MQ надає підтримку як JNDI-провайдера, так і JMS-провайдера без необхідності використовувати додаткове ПО.

Малюнок 1. Діаграма розгортання архітектури

Чому використовується саме така архітектура?

Очевидно, що існує безліч способів отримання даних з Lotus Domino і передачі їх іншим додаткам, так навіщо використовувати обмін повідомленнями, а точніше кажучи, JMS? Обмін повідомленнями здійснюється по асинхронному каналу зв'язку, що дозволяє Lotus Domino і будь-якого JMS-провайдера обмінюватися даними в режимі слабкого зв'язку (тобто, виробник і споживач даних можуть не знати один про одного). Крім того, при використанні JMS API наш Java-код дозволить Lotus Domino взаємодіяти з будь-яким JMS-провайдером, а також підключатися до безлічі корпоративних сервісних шин.

огляд статті

Кроки, наведені в нашій статті, відповідають послідовності операцій при створенні прикладу програми. Ось ці операції:

1. Налаштування WebSphere MQ.
   Так як стаття присвячена підключенню Lotus Domino до JMS-провайдера, необхідно встановити і налаштувати JMS-провайдер. Ми використовуємо WebSphere MQ V6, так як він підтримує JMS 1.1 і є популярним сполучною ПО, орієнтованим на обмін повідомленнями (Message Oriented Middleware - MOM). Оскільки для JMS потрібно JNDI-провайдер, ми також використовуємо WebSphere MQ. Для нього потрібно встановити пакет підтримки supportPac, а потім створити адмініструються об'єкти JNDI, пов'язані з базовими сутностями MQ.
2. Налаштування Lotus Domino.
   Для демонстрації концепції взаємодії Lotus Domino і JMS ми розробили простий додаток з формами, уявленнями і Java-агентами. У цьому розділі ми розглядаємо основи цієї програми Lotus Notes і процес створення Java-агента в Lotus Domino Designer. На закінчення ми обговоримо Java-код і то, як він працює.
3. Запуск прикладів.
   Щоб продемонструвати код в роботі, ми запустимо агент, який буде відправляти повідомлення WebSphere MQ, а потім це повідомлення буде показано в тому вигляді, в якому воно відображається в WebSphere MQ. Потім ми запустимо інший агент, який доставляє повідомлення назад з WebSphere MQ в Lotus Domino, продемонструвавши тим самим, що ми змогли реалізувати підтримку виробника і споживача повідомлень. Нарешті, ми відкриємо доставлені повідомлення в клієнті Lotus Notes у вигляді документа Notes, в якому відображається тіло повідомлення.

Налаштування WebSphere MQ

WebSphere MQ V6 підтримує JMS 1.1. Це означає, що WebSphere MQ V6 може працювати в якості провайдера JMS 1.1. Пам'ятайте, що JMS - це всього лише специфікація API; система обміну повідомленнями працює за рахунок конкретної реалізації цієї специфікації JMS.

Щоб JMS-клієнти могли підключатися до WebSphere MQ, необхідно створити і налаштувати менеджер черг. Менеджер черг задає процеси середовища виконання, що забезпечують можливості JMS в JMS-клієнтів. У WebSphere MQ є оснований на Eclipse адміністративний клієнт, який може допомогти в цьому процесі.

1. Запустіть WebSphere MQ Explorer, вибравши Start - All Programs - IBM Websphere MQ - Websphere MQ Explorer.
2. Виберіть папку Queue Manager в навігаторі WebSphere MQ Explorer, а потім клацніть правою кнопкою миші і виберіть New - Queue Manager.
3. У який з'явився майстра введіть в якості імені менеджера черг Domino.QMGR. Відзначте галочкою опцію "Make this the default queue manager". Введіть SYSTEM.DEAD.LETTER.QUEUE в поле Dead letter queue. В інших полях залиште пропоновані за замовчуванням, а потім натисніть Finish, як показано на малюнку 2.
   

   Малюнок 2. Налаштування менеджера черг

   

На даний момент ми створили менеджер черг, здатний зберігати повідомлення в Websphere MQ, але JMS-клієнтам також необхідний JNDI-провайдер.

Налаштування JNDI

JNDI - це всього лише специфікація, тому для її реалізації потрібно провайдер. Цю реалізацію може забезпечити IBM WebSphere MQ V6 з допомогою supportPac ME01, якому в свою чергу потрібно supportPac MS0B (див. Розділ " ресурси "). Ці пакети supportPac легко встановити: розпакуйте їх і скопіюйте JAR-файли в каталог <MQ_Install> \ Java \ lib. На малюнку 3 показані витягнуті з архіву і скопійовані в каталог <MQ_Install> \ Java \ lib JAR-файли, а саме , mqcontext.jar і com.ibm.mq.pcf-6.0.3.jar.

При використанні WebSphere MQ в якості JNDI-провайдера відпадає необхідність в окремому JNDI-провайдера, перетворюючої адмініструються об'єкти JMS в фізичні черзі Websphere MQ - цю можливість забезпечує supportPac ME01.

Малюнок 3. Пакети JNDI supportPac

JMSAdmin - це інтерактивний інструмент, підготовлений до запуску з командного рядка; він входить до складу WebSphere MQ і дозволяє створювати адмініструються об'єкти JNDI в JNDI-провайдера (в нашому випадку - в WebSphere MQ). Щоб за допомогою інструменту JMSAdmin можна було створювати JNDI-об'єкти в WebSphere MQ, необхідно змінити CLASSPATH, включивши в нього пакети supportPac. Відкрийте командний файл (C: \ Program Files \ IBM \ Websphere MQ \ Java \ bin \ JMSAdmin.bat) в текстовому редакторі і додайте посилання на JAR-файли в змінну середовища CLASSPATH, як показано на малюнку 4.

set CLASSPATH =% CLASSPATH%; C: \ Program Files \ IBM \ Websphere MQ \ Java \ lib \ mqcontext.jar;
C: \ Program Files \ IBM \ Websphere MQ \ Java \ lib \ com.ibm.mq.pcf.jar

Малюнок 4. Оновлення CLASSPATH в JMSAdmin.bat

Після додавання в файл запуску JMSAdmin інформації про пакети supportPac можна виконувати підключення до JNDI-провайдеру для створення адмініструються об'єктів JMS. Це досягається установкою властивостей з'єднання для інструменту JMSAdmin в його файлі конфігурації (JMSAdmin.config).

# Параметри конфігурації JNDI для використання WebSphere MQ в якості JNDI-провайдера
INITIAL_CONTEXT_FACTORY = com.ibm.mq.jms.context.WMQInitialContextFactory
PROVIDER_URL = localhost: 1 414 / SYSTEM.DEF.SVRCONN

Оскільки інструмент JMSAdmin запускається з сервера WebSphere MQ, параметр PROVIDER_URL повинен мати значення localhost. Як показано на малюнку 1, Java-агент Lotus Domino віддалено підключається до JNDI-провайдеру і таким чином використовує ім'я DNS віддаленого сервера, а не локального хоста.

Тепер можна запустити інструмент JMSAdmin з командного рядка:

C: \ Program Files \ IBM \ Websphere MQ \ Java \ bin \ JMSAdmin.bat

Створення адмініструються об'єктів JMS

У специфікації JMS для створення JMS-адресатів (черг і тим) використовується ConnectionFactory. Тому перший адмініструється об'єкт JNDI, який потрібно створити, - це ConnectionFactory. З інструменту JMSAdmin виконайте наступну команду (хоча JMSAdmin підтримує роботу з скриптами, в нашій статті ми будемо використовувати діалоговий режим):

def cf (JMS_ConnectionFactory) qmgr (Domino.QMGR) tran (client) chan (SYSTEM.DEF.SVRCONN)
host (bpte-demo-8.austin.ibm.com) port (1414)

Таблиця 1. Послідовність команд

Ключове слово Опис def Define - визначає нові адмініструються об'єкти JNDI. cf ConnectionFactory - JMS 1.1 може за допомогою ConnectionFactory створювати черги або теми. qmgr Queue Manager - визначає, де ConnectionFactory розміщує свої черги або теми. tran Transport - в якості транспорту WebSphere MQ може використовувати клієнт або зв'язок. У нашій статті ми задіємо режим клієнта, так як нами застосовується легкий віддалений клієнт. chan Channel - у клієнтів повинен бути канал, що прослуховує сервер WebSphere MQ, до якого вони можуть підключитися, щоб отримати доступ до менеджера черг і його ресурсів. host Host - оскільки ми використовуємо режим клієнта, потрібно вказати DNS-ім'я сервера, на якому знаходиться менеджер черг. port Port - оскільки ми використовуємо режим клієнта, потрібно вказати номер порту TCP / IP, на якому прослуховуються з'єднання.

Потім створимо чергу, містить повідомлення, як показано на малюнку 5.

def q (JMS_QUEUE) qmgr (Domino.QMGR)

Ця команда створює чергу WebSphere MQ, яка також зберігається як адмініструється об'єкт JNDI. Майте на увазі, що в JNDI є функція використання псевдонімів (alias capability), що дає можливість змінити атрибути нижележащей черзі або теми, не змінюючи код клієнта. Насправді можна взагалі перемістити чергу на інший JMS-провайдер, і код клієнта при цьому змінювати не буде потрібно.

Малюнок 5. Конфігурація JNDI

Зазвичай не зайве буває перевірити, що команда спрацювала, як очікувалося. Для цього просто виконайте в JMSAdmin наступну команду:

display ctx

Команда відобразить JNDI-контекст, в який ви внесли додавання.

Тепер JMS-провайдер налаштований, як і JNDI-провайдер. Можна переходити до коду JMS-клієнта, що підключається до цих провайдерам, щоб знаходити адресатів JMS і відправляти їм повідомлення. Також майте на увазі, що нам не довелося створювати черги за допомогою WebSphere MQ Explorer; черги і JNDI-суті створювалися одночасно за допомогою інструмента JMSAdmin. Див. Малюнок 6.

Малюнок 6. Черги в WebSphere MQ

Створення коду Lotus Domino

Для демонстрації нашої ідеї ми створили простий додаток Lotus Domino V8 з допомогою Lotus Domino Designer V8. У додатку є проста форма (див. Малюнок 7) для контактної інформації та ще одна форма для зберігання доставлених JMS-повідомлень. Крім того, ми створили два подання, в яких відображаються відповідно контакти і доставлені повідомлення. Див. Файл з кодом JMSDemo.zip в розділі " Завантаження "Цієї статті.

Малюнок 7. Приклад програми Lotus Domino

Створення Java-агентів

До складу прикладу додатки також входять два Java-агента: JMS_PUT і JMS_GET. Обидва агента запускаються з меню Agent, що викликається користувачем. (Можливо, ви захочете запускати їх іншим способом; в Lotus Domino є безліч добре документованих можливостей). JMS_PUT відправляє повідомлення JMS-провайдера через клієнт Lotus Notes для всіх документів, обраних в поданні Employees. Агент JMS_GET також запускається з клієнта Lotus Notes, але не вимагає вибору будь-яких документів. Цей агент насправді шукає повідомлення в JMS-провайдера. Для кожного знайденого повідомлення він створює документ Lotus Domino, в якому одне поле призначене для ідентифікатора JMS-повідомлення, а інше - для тіла JMS-повідомлення. Для конвертації документа employee в XML-документ в нашому прикладі використовується клас DxlExporter, що надається Lotus Domino. XML-документ використовується в якості тіла JMS-повідомлення.

1. Для створення Java-агента в Lotus Domino Designer просто розгорніть папку Shared Code в демонстраційному JMS-додатку.
2. Виберіть в цій папці пункт Agents, щоб побачити всіх агентів, а також кнопку для створення нових агентів.
3. Натисніть на кнопку New Agent для створення Java-агента (або відкриття існуючого коду з файлу JMSDemo.zip).

При створенні Java-агента в Lotus Domino Designer інтегроване середовище розробки згенерує для вас структурну схему, як показано на малюнку 8.

Малюнок 8. Структурна схема Java-агента

Перед отриманням коду необхідно додати класи реалізації JMS-провайдера і API до агента. Пам'ятайте, що JMS - це всього лише специфікація, яка забезпечує набір інтерфейсів, що реалізуються JMS-провайдерами. Так як в якості провайдера ми використовуємо WebSphere MQ, ми повинні включити в наш агент JAR-файли WebSphere MQ. Відкривши Java-агент, як показано на малюнку 9, натисніть на кнопку Edit Project для відкриття діалогового вікна (рисунок 9), в якому можна додати в агент JAR-файли. (У нашій статті ми для простоти додаємо JAR-файли в агент, але цілком можливо, що вам буде потрібно скопіювати ці JAR-файли на ваш сервер Lotus Domino і додати посилання на них в файл Notes.ini сервера в змінну JavaUserClasses).

Малюнок 9. Додавання JAR-файлів в Java-агент

У таблиці 2 описується кожен необхідний JAR-файл.

Таблиця 2. JAR-файли JMS-продажу WebSphere MQ

Файл Опис com.ibm.mqjms.jar Надає класи реалізації MQ JMS com.ibm.mq.jar Надає класи реалізації MQ com.ibm.mq.pcf.jar Надає MQ-класи для PCF connector.jar Надає API J2EE-коннектора dhbcore. jar Потрібен для WebSphere MQ fscontext.jar Надає реалізацію JNDI файлової системи jms.jar Надає класи інтерфейсу JMS jndi.jar Надає класи інтерфейсу JNDI jta.jar Надає реалізацію JTA mqcontext.jar Надає MQ класи реалізації JNDI

Ці JAR-файли були скопійовані з каталогу установки WebSphere MQ в каталог C: \ Program Files \ IBM \ Websphere MQ \ Java \ lib.

код

Погляньмо тепер на код і розберемося, за що відповідає кожна частина. У лістингу 1 показаний загальний код, однаковий як для провайдера, так і для споживача повідомлень. Зверніть увагу, що нумерація рядків в коді - наскрізна, і код лістингів 2 і 3 слід за загальним кодом з лістингу 1.

Лістинг 1. Загальний код

1 lotus.domino.Session notesSession = getSession (); 2 AgentContext agentContext = notesSession.getAgentContext (); 3 Database db = agentContext.getCurrentDatabase (); 4 Hashtable env = new Hashtable (); 5 env.put (Context.INITIAL_CONTEXT_FACTORY, "com.ibm.mq.jms.context.WMQInitialContextFactory"); 6 env.put (Context.PROVIDER_URL, "bpte-demo-8.austin.ibm.com:1414/SYSTEM.DEF.SVRCONN"); 7 javax.naming.InitialContext ctx = new InitialContext (env); 8 javax.jms.ConnectionFactory qcf = (ConnectionFactory) ctx.lookup ( "JMS_ConnectionFactory"); 9 javax.jms.Connection jmsCon = qcf.createConnection (); 10 jmsCon.start (); 11 javax.jms.Session jmsSess = jmsCon.createSession (true, javax.jms.Session.AUTO_ACKNOWLEDGE); 12 javax.jms.Destination jmsDest = (Destination) ctx.lookup ( "JMS_QUEUE");

Рядки 1, 2 і 3 просто отримують контекст для агента Lotus Domino і бази даних, в якій запущений агент. У рядках 4, 5 і 6 задаються властивості JNDI, що дозволяють цим кодом агента підключатися до JNDI-провайдеру, а саме WebSphere MQ V6, запущеного віддалено. Після створення екземпляра JNDI InitialContext можна з його допомогою знайти JMS ConnectionFactory, що показано в рядку 8. Це значення має відповідати імені адміністрованого об'єкта JMS, який був створений за допомогою інструменту JMSAdmin. Потім запускається з'єднання і створюється сеанс JMS. Тепер ми готові виявити JMS-адресат і почати виробництво або споживання повідомлень. У рядку 12 ми бачимо розміщення JMS-адресата шляхом виконанням пошуку по JNDI-імені JMS_QUEUE. (Для цього застосовується інструмент JMSAdmin, як показано на малюнку 6).

У лістингу 2 показаний код виробника JMS, що створює JMS-повідомлення та його відправку віддаленого JMS-провайдеру. Так як цей агент застосовується до документів, обраним в поданні, в рядку 16 ми отримуємо колекцію цих документів. Потім ми виконуємо цикл, конвертуючи кожен документ Lotus Domino з цієї колекції в XML-документ, який можна записати в JMS як простий текст (рядок 19).

Лістинг 2. Виробник повідомлень

13 MessageProducer jmsProducer = jmsSess.createProducer (jmsDest); 14 TextMessage jmsMsg = jmsSess.createTextMessage (); // конвертуємо документ Domino в XML-фрагмент 15 DxlExporter xmlGen = notesSession.createDxlExporter (); // отримуємо від агента колекцію обраних документів 16 DocumentCollection dc = agentContext.getUnprocessedDocuments (); 17 Document doc = dc.getFirstDocument (); 18 while (doc! = Null) {// записуємо вміст документа в JMS-адресат 19 jmsMsg.setText (xmlGen.exportDxl (doc)); 20 jmsProducer.send (jmsMsg); 21 jmsSess.commit (); 22 doc = dc.getNextDocument (); }

Після запуску агента можна переконатися, що повідомлення дійшли до WebSphere MQ, за допомогою WebSphere MQ Explorer. У WebSphere MQ Explorer виберіть папку Queues, щоб побачити всі черги цього менеджера черг, а потім правою кнопкою миші натисніть на JMS_Queue і виберіть Browse Messages, щоб побачити повідомлення в черзі.

В результаті буде виведено повідомлення за кожним документом, обраному під час запуску агента JMS_PUT (див. Малюнок 10).

Малюнок 10. Повідомлення в черзі

Якщо двічі клацнути по одному з повідомлень, виводиться діалогове вікно Properties, в якому показано повідомлення в тому вигляді, в якому воно відображається в WebSphere MQ (див. Малюнок 11).

Малюнок 11. Повідомлення в WebSphere MQ

На даний момент ми успішно зберегли цілий документ Lotus Domino як XML в черзі WebSphere MQ. І в нашому коді відсутні характерні для WebSphere MQ класи, є тільки JMS-код, який так само легко відправляє це повідомлення у WebSphere Enterprise Service Bus.

Щоб продемонструвати, що можна також отримувати повідомлення від WebSphere MQ через JMS, ми створили ще один агент для споживання повідомлень. Як і код виробника, цей код не знає, який використовується JMS-провайдер - він просто вміє "розмовляти" на JMS. Код споживача показаний в лістингу 3.

Лістінг 3. Споживач Повідомлень

13 MessageConsumer jmsConsumer = jmsSess.createConsumer (jmsDest); 14 Message jmsIncoming = null; 15 do {// Споживач буде чекати 1 секунду (1000 мілісекунд) между Опитування 16 jmsIncoming = jmsConsumer.receive (1000); 17 if (jmsIncoming instanceof TextMessage) {18 System.out.println ( "\ n" + "Got message:" + ((TextMessage) jmsIncoming) .getText ()); 19 Document doc = db.createDocument (); 20 doc.replaceItemValue ( "Form", "JMS_Imported"); 21 doc.replaceItemValue ( "JMS_MsgID", jmsIncoming.getJMSMessageID ()); 22 doc.replaceItemValue ( "JMS_Message", ((TextMessage) jmsIncoming) .getText ()); 23 doc.save (true, true); 24} 25 jmsSess.commit (); 26} while (jmsIncoming! = Null);

Важліва відмінність коду споживача Полягає в тому, что споживач повинен чекати и слухати ПОВІДОМЛЕННЯ, як показано в рядку 16. При отріманні ПОВІДОМЛЕННЯ ми створюємо новий документ Lotus Domino для Збереження JMS-повідомлення в базі Даних Lotus Domino (рядки 19-23). З метою налагодження ми виводимо інформацію про повідомленні на консоль Java, яку можна викликати, вибравши Tools - Show Java Debug Console в Lotus Domino Designer, як показано на малюнку 12.

Малюнок 12. Інформація про повідомленні в консолі Java

Крім того, якщо відкрити уявлення JMS_Imported, можна побачити документи, створені в ході виконання коду споживача JMS. Відкривши документ, ви побачите доставлений XML-текст (див. Малюнок 13).

Малюнок 13. Повідомлення, збережені у вигляді документів Domino

Висновок

У нашій статті ми показали, як відправляти повідомлення з Lotus Domino JMS-провайдера, а також отримувати повідомлення. В результаті ми отримав простий і економічний спосіб спільного застосування Lotus Domino і корпоративної сервісної шини. Як провайдера повідомлень ми використовували WebSphere MQ, проте наш код працює з будь-яким JMS-провайдером.

Подякою

Висловлюємо особливу подяку Бобу Балабана і Боббі Вулфу за рецензування даної статті.

Ресурси для скачування

Схожі тими

Підпішіть мене на ПОВІДОМЛЕННЯ до коментарів