Во многих организациях в существующих приложениях 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.

Предлагаемая архитектура

Поделиться...

	Разместить на Digg
	Разместить на del.icio.us
	Разместить на Slashdot!

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

Почему используется именно такая архитектура?

Очевидно, что существует множество способов извлечения данных из 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.

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

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

Поскольку инструмент 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)

Затем создадим очередь, содержащую сообщение, как показано на рисунке 5.

Эта команда создаёт очередь WebSphere MQ, которая также сохраняется как администрируемый объект JNDI. Имейте в виду, что в JNDI имеется функция использования псевдонимов (alias capability), дающая возможность изменить атрибуты нижележащей очереди или темы, не меняя код клиента. На самом деле можно вообще переместить очередь на другой JMS-провайдер, и код клиента при этом изменять не потребуется.

Обычно нелишне бывает проверить, что команда сработала, как ожидалось. Для этого просто выполните в JMSAdmin следующую команду:

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

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

В начало

Создание кода Lotus Domino

Для демонстрации нашей идеи мы создали простое приложение Lotus Domino V8 с помощью Lotus Domino Designer V8. В приложении имеется простая форма (см. рисунок 7) для контактной информации и ещё одна форма для хранения доставленных JMS-сообщений. Кроме того, мы создали два представления, в которых отображаются соответственно контакты и доставленные сообщения. См. файл с кодом JMSDemo.zip в разделе "Загрузка" этой статьи.

В начало

Создание 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.

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

В таблице 2 описывается каждый необходимый JAR-файл.

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

В начало

Код

Взглянем теперь на код и разберёмся, за что отвечает каждая часть. В листинге 1 показан общий код, одинаковый как для провайдера, так и для потребителя сообщений. Обратите внимание, что нумерация строк в коде - сквозная, и код листингов 2 и 3 следует за общим кодом из листинга 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).

                

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).

Если дважды щелкнуть по одному из сообщений, выводится диалоговое окно Properties, в котором показано сообщение в том виде, в каком оно отображается в WebSphere MQ (см. рисунок 11).

На данный момент мы успешно сохранили целый документ Lotus Domino как XML в очереди WebSphere MQ. И в нашем коде отсутствуют характерные для WebSphere MQ классы, имеется только JMS-код, который так же легко отправляет это сообщение в WebSphere Enterprise Service Bus.

Чтобы продемонстрировать, что можно также получать сообщения от WebSphere MQ через JMS, мы создали ещё один агент для потребления сообщений. Как и код производителя, этот код не знает, какой используется JMS-провайдер – он просто умеет "разговаривать" на JMS. Код потребителя показан в листинге 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.

Кроме того, если открыть представление JMS_Imported, можно увидеть документы, созданные в ходе выполнения кода потребителя JMS. Открыв документ, вы увидите доставленный XML-текст (см. рисунок 13).

В начало

Заключение

В нашей статье мы показали, как отправлять сообщения из Lotus Domino JMS-провайдеру, а также получать сообщения. В результате мы получил простой и экономичный способ совместного применения Lotus Domino и корпоративной сервисной шины. В качестве провайдера сообщений мы использовали WebSphere MQ, однако наш код работает с любым JMS-провайдером.

В начало

Благодарности

Выражаем особую благодарность Бобу Балабану и Бобби Вулфу за рецензирование данной статьи.

В начало

Загрузка

Информация о методах загрузки

Ресурсы

Научиться

• Оригинал статьи: Developing an IBM Lotus Domino agent with JMS (EN).
  
  
• Прочтите руководство developerWorks: Интеграция Domino и WebSphere MQ (EN).
  
  
• Прочтите статью developerWorks: Запуск отдельного Java-приложения на WebSphere MQ V6.0 (EN).
  
  
• Прочтите статью developerWorks: Безопасность JMS-транспорта, часть 1: Использование WebSphere MQ для обеспечения безопасного JMS-транспорта для WebSphere Application Server (EN).
  
  
• Получите дополнительную информацию по ME01: WebSphere MQ – Initial Context Factory (EN).
  
  

Получить продукты и технологии

• Загрузите ME01 supportPac (EN).
  
  

Обсудить

• Примите участие в обсуждении материала на форуме.
  
  

Об авторе

Оценить эту статью

Комментарии

В начало

Содержание

• Предлагаемая архитектура
• Настройка WebSphere MQ
• Настройка JNDI
• Создание администрируемых объектов JMS
• Создание кода Lotus Domino
• Создание Java-агентов
• Код
• Заключение
• Благодарности
• Загрузка
• Ресурсы
• Об авторе
• Комментарии