Интеграция данных IBM Lotus Notes в боковую и инструментальную панель Lotus Notes V8

Новая архитектура IBM Lotus Notes V8 обеспечивает множество новых способов расширения и настройки пользовательского интерфейса и поведения программы с помощью плагинов Eclipse. В статье описывается, как осуществлять доступ к контенту Lotus Notes и создавать его при помощи этой новой модели.

Брайан Леонард, разработчик Lotus Notes Client, IBM

Брайан Леонард (Brian Leonard) - разработчик клиента Lotus Notes Client. При создании IBM Lotus Notes V8 он работал над функциями поиска, доставки электронной почты, отложенной загрузки изображений, проверки орфографии, а также занимался расширяемостью. Ему бы хотелось быть повыше ростом, но никогда не удавалось найти нужную точку расширения.



29.01.2008

В недавней статье, "Расширение боковой и инструментальной панелей IBM Lotus Notes V8", мы рассматривали расширение пользовательского интерфейса IBM Lotus Notes V8 путём добавления компонентов к боковой и инструментальной панели клиента. В частности, мы добавили приложения SideNote и QuickNote, решающие задачу хранения и управления текстовыми фрагментами. Созданные нами плагины служат хорошими примерами размещения собственных компонентов на этих панелях.

Если вы используете SideNote и QuickNote, можно рассматривать их как два дополнительных хранилища важной для вас информации. При использовании же журнала Lotus Notes вы можете и не оценить преимущества размещения всей вашей информации в журнале.

При создании собственного компонента можно столкнуться с подобным препятствием. Без какого-либо взаимодействия с уже имеющимися данными и системами сделать можно немногое. К счастью, модель программирования Lotus Notes предлагает широкий набор способов взаимодействия с используемыми вами системами. Например, любую систему, предлагающую Web-сервисы, можно легко интегрировать практически любым необходимым способом. С приложением, предоставляющим Java-интерфейс или библиотеку, возможно, будет работать еще проще.

В IBM Lotus Notes для взаимодействия с базами данных и документами Lotus Notes имеется библиотека Notes.jar. В статье объясняется, как использовать эту библиотеку и другие методики для расширения функциональности ваших новых компонентов.

Установка

Прежде всего, требуется установить бета-версию Lotus Notes V8.

Затем необходимо установить Eclipse, который можно загрузить бесплатно. Потом нужно настроить Eclipse для работы со средой Lotus Notes. При выполнении следующих шагов предполагается, что вы установили Notes в заданный по умолчанию каталог C:\Program Files\IBM\Lotus\Notes, а каталог данных расположен по адресу C:\Program Files\IBM\Lotus\Notes\Data. Если ваша среда слегка отличается, в обоих случаях используйте собственные пути к каталогам.

Запустите Eclipse IDE и задайте целевую платформу, выполнив следующие операции:

  1. Выберите Window - Preferences.
  2. Разверните Plug-in Development.
  3. Выберите Target Platform.
  4. В поле Location введите или укажите адрес C:\Program Files\IBM\Lotus\notes\framework\eclipse.
  5. Нажмите кнопку Reload, а затем - OK.

Далее мы создаём дополнительную установленную JRE:

  1. Выберите Window - Preferences.
  2. Разверните Java.
  3. Выберите Installed JREs.
  4. Нажмите Add.
  5. В качестве имени JRE введите Notes JRE.
  6. В качестве домашнего каталога JRE введите или укажите C:\Program Files\IBM\Lotus\notes\framework\rcp\eclipse\plugins\com.ibm.rcp.j2se.win32.<номер версии>.
    Для Lotus Notes Beta 3 это значение таково: com.ibm.rcp.j2se.win32.x86_1.5.0.SR4-200705170110
    (ПРИМЕЧАНИЕ: JAR-файлы будут помещены в нижней части диалогового окна.)

Далее мы создаём новую конфигурацию выполнения. Для этого выполним следующие операции:

  1. Выберите Run - Run, а затем - Eclipse Application.
  2. Правой кнопкой мыши выберите New.
  3. Введите какое-нибудь имя (например, Notes).
  4. В разделе Program to Run выберите Run a product, а затем - com.ibm.notes.branding.notes.
  5. В Runtime JRE выберите Notes JRE.
  6. На вкладке Arguments введите в текстовое поле Program arguments следующую информацию:
    -personality com.ibm.rcp.platform.personality
    -product com.ibm.notes.branding.notes
    -debug
    -console

Введите следующие аргументы в текстовое поле VM arguments:
-Drcp.home=${notes.install}\framework
-Drcp.data=notes.data\workspace
-Drcp.install.config=user
-Dosgi.install.area=${notes.install}\framework\eclipse
-Dcom.ibm.pvc.osgiagent.core.logfileloc=${notes.install}\framework\rcp
-Dcom.ibm.pvc.webcontainer.port=0
-Declipse.pluginCustomization=${notes.install}\framework\rcp\plugin_customization.ini
-Declipse.registry.nulltoken=true
-Djava.protocol.handler.pkgs=com.ibm.net.ssl.www.protocol
-Djava.util.logging.config.class=com.ibm.rcp.core.internal.logger.boot.LoggerConfig
-Dosgi.hook.configurators.exclude=org.eclipse.core.runtime.internal.adaptor.EclipseLogHook
-Dosgi.framework.extensions=com.ibm.rcp.core.logger.frameworkhook
-Xbootclasspath/a:${notes.install}\framework\rcp\eclipse\plugins\${rcp.base}\rcpbootcp.jar;

Далее, для завершения конфигурации выполнения, выполним следующие операции:

  1. Нажмите Variables.
  2. Нажмите Edit Variables.
  3. Нажмите New.
  4. Введите в качестве имени notes.install.
  5. Введите в качестве значения путь установки Notes, а затем нажмите OK. В пути не должно быть пробелов. Например, если путь установки - C:\Program Files\Lotus\Notes, значение notes.install должно быть следующим:
    C:\PROGRA~1\IBM\Lotus\Notes.
  6. Повторите шаги с 1 по 3.
  7. Введите в качестве имени notes.data.
  8. Введите в качестве значения путь к вашему каталогу данных, а затем нажмите OK. Например, можно использовать путь по умолчанию:
    C:\PROGRA~1\IBM\Lotus\Notes\Data.
  9. Повторите шаги с 1 по 3.
  10. Введите в качестве имени rcp.base.
  11. Введите версию имени папки плагина com.ibm.rcp.base, а затем нажмите OK. Для этого перейдите по следующему адресу: <место установки notes>\framework\rcp\eclipse\plugins. Там расположена папка со следующим именем: com.ibm.rcp.base_6.1.1.<дата>.
    Например, в Lotus Notes Beta 3 это значение будет таким:
    com.ibm.rcp.base_6.1.1.200705170110
  12. Нажмите OK, а затем - Cancel. Появится диалоговое окно Select Variable (если для выбора переменной нажать OK, переменная будет добавлена в точке вставки).

Чтобы включить функции безопасности Notes из IDE, необходимо раскомментировать две строки. В файле <место установки notes>\framework\shared\eclipse\plugins\com.ibm.notes.branding_3.0.0.<номер версии>\notes_plugin_customization.ini раскомментируйте две следующие строки, удалив начальный символ #: com.ibm.rcp.security.auth/loginEnabled=true
com.ibm.rcp.security.auth/loginConfigName=NOTES

Теперь выберите Run/Debug для запуска Lotus Notes.

Наконец, загрузите код, приведённый в этой статье, и распакуйте его в новую папку. Чтобы импортировать его в Eclipse, необходимо импортировать существующие проекты.

  1. Выберите File - Import.
  2. Выберите General - Existing Projects into Workplace, а затем нажмите Next.
  3. Выберите папку, в которую вы распаковали код, и нажмите OK.
  4. Нажмите Finish для завершения процесса импорта.

SideNote

Приложение SideNote находится на боковой панели Lotus Notes и представляет собой область для быстрого ввода и сохранения текста. Из предыдущей статьи, Расширение боковой и инструментальной панелей IBM Lotus Notes V8, вы узнали, как можно добавлять пункты меню к компонентам боковой панели при помощи точек расширения Eclipse. В частности, мы добавили к SideNote пункты Save as file и Load from file, как показано на рисунке 1.

Рисунок 1. SideNote и пункты меню
SideNote и пункты меню

Пункт меню Email

После того, как вы напечатали в SideNote какой-то текст, может потребоваться отправить его по электронной почте. Для выполнения этой задачи добавьте пункт меню, как показано на рисунке 2.

Рисунок 2. Пункт меню Email It!
Пункт меню Email It!

Выполнить это можно при помощи API операционной системы, а не через API Lotus Notes. В частности, при операции отправки почты для создания нового сообщения используется протокол mailto URL.

Тем не менее, спецификация подобных ссылок также предусматривает передачу ещё нескольких порций данных. В частности, при операции отправки почты используется возможность указывать тело сообщения. Можно также исключить получателя, поэтому ваша ссылка будет выглядеть примерно так: mailto:?body=Отсюда+можно+отправлять+электронную+почту.

Поскольку в Lotus Notes этот протокол реализован, подобная ссылка корректно создаёт новое сообщение с заданным телом. Всё, что нужно сделать - запустить ссылку.

Как и в предыдущей статье, мы реализуем точку расширения org.eclipse.ui.viewActions для добавления новых пунктов к этому меню. Как показано на рисунке 3, для точки расширения viewActions необходимо ввести нижеуказанные значения в следующие поля:

  • class: com.ibm.lotuslabs.sidenote.email.EmailSideNote
  • enablesFor: *
  • id: com.ibm.lotuslabs.sidenote.email.EmailSideNote
  • label: Email it!
  • menubarPath: additions
  • tooltip: Email this SideNote
Рисунок 3. Plugin.xml и точки расширения
Plugin.xml и точки расширения

Таким образом, плагин com.ibm.lotuslabs.sidenote.email указывает на класс EmailSideNote, который, в соответствии с соглашением, должен реализовать интерфейс IViewActionDelegate. Метод run этого класса возвращает текст и запускает ссылку для создания сообщения.


Пункт меню Save to Journal

Другой плагин, com.ibm.lotuslabs.sidenote.journal, добавляет пункт меню для сохранения содержимого SideNote в журнале пользователя. Этот новый пункт меню показан на рисунке 4.

Рисунок 4. Пункт меню Save to Journal
Пункт меню Save to Journal

Можно увидеть, что снова используется та же схема. Plugin.xml содержит информацию о точках расширения и указывает на класс JournalSideNote. Метод run показан в листинге 1.

Листинг 1. Метод run JournalSideNote
 	private SideNoteViewPart part;
	
	// сохраняем
	public void run(IAction arg0) {
		if(part!=null) {
			String text = part.getText();
			if(text==null)
				text="";
			JournalEntry.createJournalEntry(null, text);
		}
	}

Как можно видеть, всю работу здесь выполняет класс под названием JournalEntry. Это - helper-класс из плагина com.ibm.lotuslabs.notes.pim, обрабатывающий все взаимодействия с Lotus Notes при помощи библиотеки Notes.jar.


Взаимодействие с данными Lotus Notes

С появлением этой новой Java-среды библиотека Notes.jar стала играть важную роль в интеграции данных клиента. Было выпущено несколько версий этой библиотеки, и теперь она входит в состав плагина com.ibm.notes.java.api из IBM Lotus Notes V8.

ПРИМЕЧАНИЕ: официальная поддержка этого плагина в бета-версии Lotus Notes V8 пока отсутствует, однако в настоящий момент его можно использовать как Tech Preview.

Плагин занимается многими сложными вопросами, связанными с работой с этой библиотекой, в том числе безопасностью и установкой системных переменных. Всё, что нужно сделать - добавить com.ibm.notes.java.api к зависимостям в файле MANIFEST.MF вашего плагина.

Кроме того, в com.ibm.notes.java.api имеется класс NotesJob, значительно облегчающий использование библиотеки Notes.jar. Класс NotesJob синхронизирует доступ к потоками Lotus Notes и используется аналогично классу UIJob, синхронизирующему обращения к дисплею в Eclipse. Класс NotesJob показан в листинге 2.

Листинг 2. Пример NotesJob
NotesJob job = new NotesJob("Job description") {
protected IStatus runInNotesThread(IProgressMonitor mon) {
		Session session = NotesPlatform.getInstance().getSession();
		// ваш код notes.jar
		return Status.OK_STATUS;
	}
};
job.schedule();

Как только ваш код будет запущен в методе NotesJob.runinNotesThread, можно использовать классы и объекты Notes.jar в соответствии с документацией по Lotus Notes и методическим указаниям по его применению. В общем, классы Notes.jar очень похожи на классы LotusScript. Например, существуют классы, представляющие базы данных, представления и документы. Внутри этих компонентов находятся классы, представляющие образующие их фрагменты. Например, в документах можно получить доступ к значениям полей и отдельным абзацам в расширенном тексте (rich text). Более подробная информация содержится в IBM Lotus Domino Designer Help.

Ещё одна операция, которая может оказаться полезной, - присвоение переменной BSAFE_ALLOW_REPARENT значения 1 в файле Notes.ini. Сделав это, вы сможете получать доступ к серверным классам без многократного ввода пароля. При включении этого параметра диалоговое окно для входа в систему, периодически появляющееся по умолчанию, выводиться не будет. Обычно доступ к файлу ID Lotus Notes осуществляется по необходимости (lazy access), и окно входа в систему не отображается до тех пор, пока какой-либо функции не потребуется к нему доступ. Включение этого параметра позволяет процессу Lotus Notes V8 Eclipse/Java и процессу рабочей станции Lotus Notes лучше координировать доступ к файлу ID. В результате диалоговое окно для входа в систему не появляется без необходимости, и безопасность от этого не страдает.

Приложения

Плагин com.ibm.lotuslabs.notes.pim зависит от com.ibm.notes.java.api, что позволяет воспользоваться возможностями Notes.jar по работе с приложениями Mail, Calendar, Contacts и Journal и находящимися внутри них документами.

Класс Applications обеспечивает возможность запускать и выполнять код Notes.jar в этих приложениях. Каждому приложению присваивается ID, статически определяемый в классе, как показано в листинге 3.

Листинг 3. Типы приложений
public final static int APP_MAIL = 1;
	public final static int APP_CALENDAR = 2;
	public final static int APP_TODO = 3;
	public final static int APP_CONTACTS = 4;
	public final static int APP_JOURNAL = 5;

Чтобы запустить одно из этих приложений для конкретного пользователя, необходимо передать соответствующий ID методу launch: Applications.launch(Applications.APP_JOURNAL);

Этот класс также обеспечивает возможность выполнения кода в любой из этих баз данных при помощи метода execute. Мы создаём новый IDatabaseRunnable, определяющий код, который мы хотим вызвать. Этот интерфейс обеспечивает один метод: public void run(Session session, Database database);

При помощи данной сессии (session), базы данных (database) и API Notes.jar этот код выполняется полностью инкапсулировано. Вызывающий оператор беспокоится лишь о коде, а не об упомянутых ранее инициализации, зависимостях или NotesJobs. Пример приведён в листинге 4.

Листинг 4. Выполнение кода в базе данных
IDatabaseRunnable run = new IDatabaseRunnable() {
public void run(Session session, Database db) throws NotesException {
	Document doc = db.createDocument();
// задаём поля для создания задачи
	doc.save();
	doc.recycle();
}
};
// планируем создание
Applications.execute(Applications.APP_TODO, "Create task", run);

Взаимодействие с журналом

В этой схеме журнал немного сложнее других приложений, поскольку у него нет общеизвестного URL. Ознакомившись с внутренним классом DatabaseUtil, можно понять, что URL определены и для почты, и для списка контактов пользователя. Они используются для запуска или открытия базы данных. Но для журнала это не так, поэтому первым делом следует определить, какую же базу данных пользователь будет считать своим журналом.

Как вы, возможно, знаете, журнал можно запустить с домашней страницы Lotus Notes, как показано на рисунке 5.

Рисунок 5. Домашняя страница Lotus Notes
Домашняя страница Lotus Notes

При первом нажатии на кнопку Personal Journal вы увидите диалоговое окно, показанное на рисунке 6. В нём спрашивается, если ли у вас журнал. Если нет, имеется возможность создать новый. Если же журнал уже существует, можно сообщить Lotus Notes, где он находится, нажав кнопку Select Personal Journal.

Рисунок 6. Выбор личного журнала
Выбор личного журнала

Плагин com.ibm.lotuslabs.pim основан на механизме определения местонахождения пользовательского журнала. В частности, он знает, что эти данные хранятся в документе профиля HPSettings в базе данных bookmark.nsf. Как только он обнаружит этот документ, он получает информацию, что сервер и база данных журнала сохранены в полях JServer и JDatabase, соответственно. Такой поиск выполняется методом getJournalDatabase в классе JournalUtil при первой попытке доступа.

Из-за такой схемы работы данный метод может и не найти базу данных журнала; это возможный побочный эффект при попытке выполнить код в вашем журнале. В этом случае класс JournalUtil вызывает окно открытия файла, в котором пользователь может выбрать локальный журнал, как показано на рисунке 7.

Рисунок 7. Диалоговое окно выбора базы данных журнала
Диалоговое окно выбора базы данных журнала

Поиск базы данных должен осуществляться в запланированном потоке NotesJob. Поскольку этот поток работает в фоновом режиме, запустить файловый браузер невозможно. Для обзора вызывается метод executeJournalUI, запускающий новую задачу UIJob. Предполагая, что пользователь вызывает файл журнала, код возвращается к новой NotesJob для обновления документа профиля закладки и выполнения кода, который собирался выполнить вызывающий оператор. Вызывающий оператор задействовал такой многопоточный режим, передавая объект IDatabaseRunnable, а не запрашивая объект Database.

После того, как мы узнаем путь к базе данных, легко открыть приложение для выполнения переданного кода. При необходимости запустить журнал в методе launchJournal используется объект IDatabaseRunnable. Сделать это можно, запросив у базы данных её URL и запустив этот URL; см. листинг 5.

Листинг 5. Запуск журнала
	public static void launchJournal(final String description, final String append) {
		executeJournalThread(description, new IDatabaseRunnable() {
			public void run(Session session, Database database) throws NotesException {
				String server = database.getServer();
				String repId = database.getReplicaID();
				if(repId!=null) {
					if(server==null)
						server = "";
					String url = "notes://"+server+"/"+repId;
					if(append!=null) {
						url += append;
					}
					DatabaseUtil.launchUrl(url, description);
				}
			}
			
		});
	}

Класс JournalEntry, вызываемый операцией SideNote, использует эти механизмы для сохранения нового документа. Метод createJournalEntry вызывает метод execute с необходимым IDatabaseRunnable. Выполняемому коду необходимо лишь создать новый документ со всеми необходимыми полями, чтобы сделать его полнофункциональным документом журнала. Этот код показан в классе createJournalDocument.


Стратегии взаимодействия с Lotus Notes

Вы, возможно, обнаружили некую систему. Библиотека Notes.jar очень удобна при работе с данными внутри баз данных. Как вы увидели, плагин com.ibm.lotuslabs.notes.pim иллюстрирует использование этой библиотеки для чтения данных из документов и создания новых документов.

Тем не менее, у этой модели существует ограничение - операции в оперативной памяти. Обратите внимание, что когда мы хотим создать новое почтовое сообщение, мы не вызываем Notes.jar, а запускаем URL. Наша цель выполняется, а именно, создаётся новый документ без его сохранения. Аналогично, класс JournalEntry также позволяет запустить новую запись с помощью тех же механизмов запуска URL для отображения самого журнала. Ограничение состоит в том, что этот URL не может заполнять поля нового документа журнала.

Есть несколько способов решения этой проблемы. Первый способ - создать документ с помощью Notes.jar и сохранить его, если это имеет смысл в вашем приложении. Затем можно запросить его URL и запустить его. Недостатком данного метода является то, что если автоматический ввод данных по каким-либо причинам будет неполным, вы рискуете оставить в вашей базе данных незаконченные документы.

Второй способ сильно зависит от самого приложения; для базы данных и форм требуется создать специальный способ связи. Например, можно организовать взаимодействие через временный файл с заранее заданным именем. Java-код осуществляет запись в этот файл, а затем запускает новую форму. Форма находит этот временный файл, считывает его, заполняет его данными по мере необходимости и удаляет. Можно представить себе несколько вариантов подобного взаимодействия.

Ещё одна возможность - создать собственный пользовательский интерфейс с помощью SWT, Standard Widget Toolkit, и использовать Notes.jar для загрузки и сохранения значений в базе данных. Пример JournalNote из пакета com.ibm.lotuslabs.notes.pim.ui аналогичен примеру, приведённому на рисунке 8.

Рисунок 8. SWT JournalNote
SWT JournalNote

Код для этого примера показан в листинге 6.

Листинг 6. Создание JournalNote
public static void showJournalNote(final Composite parent, 
final String url) {
IDatabaseRunnable run = new IDatabaseRunnable() {
	public void run(Session session, Database database) throws NotesException {
		Document doc = (Document) session.resolve(url);
		final Map map = JournalNote.createValueMap(doc);
		parent.getShell().getDisplay().asyncExec(new Runnable() {
			public void run() {
				JournalNote note = new JournalNote(parent,map);
});	
		};

		// выполнение
		Applications.execute(Applications.APP_JOURNAL, "Opening journal document", run);
	}
}

Панель инструментов Journal

Вы, возможно, заметили, что в объединяющем коде мы использовали не все методы. Большая его часть была создана для поддержки панели инструментов для частых пользователей журнала, как показано на рисунке 9. Эта панель инструментов, добавляемая плагином com.ibm.lotuslabs.journal.ui, позволяет пользователю запускать журнал, создавать новую пустую запись в режиме редактирования и быстро заполнять её.

Рисунок 9. Панель инструментов Journal
Панель инструментов Journal

Код, отвечающий за запуск пользовательского журнала - это уже знакомый вам метод Applications.launch. Передав ID для журнала, URL запускается и отображает базу данных. Подобным образом кнопка New вызывает метод JournalEntry.launchNewEntry, выводящий соответствующую форму.

Концепция QuickNote была описана в предыдущей статье, "Расширение боковой и инструментальной панелей IBM Lotus Notes V8". Панель инструментов журнала использует тот же самый код, но вместо сохранения содержимого в текстовый документ с помощью класса JournalEntry создаётся новый документ журнала. Преимущество данной функции в том, что пользователь может записать информацию очень быстро. Кроме того, по сравнению с QuickNote, при записи этих данных не создаётся нового хранилища информации.


Заключение

Интеграция данных Lotus Notes делает вашу работу ещё интереснее. До сих пор мы применяли данную методику для простых операций, однако её можно использовать и для создания любых компонентов на ваш вкус. Такими компонентами могут быть даже целые экземпляры IViewPart, которые могут существовать самостоятельно, на боковой панели, или же являться частью составного приложения.

Этих простых примеров использования библиотеки Notes.jar и других методик в IBM Lotus Notes V8 должно быть достаточно, чтобы помочь вам в процессе создания собственных компонентов.


Загрузка

ОписаниеИмяРазмер
Образец кодаnotes_data.zip26 KB

Ресурсы

Научиться

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

Обсудить

Комментарии

developerWorks: Войти

Обязательные поля отмечены звездочкой (*).


Нужен IBM ID?
Забыли Ваш IBM ID?


Забыли Ваш пароль?
Изменить пароль

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Профиль создается, когда вы первый раз заходите в developerWorks. Информация в вашем профиле (имя, страна / регион, название компании) отображается для всех пользователей и будет сопровождать любой опубликованный вами контент пока вы специально не укажите скрыть название вашей компании. Вы можете обновить ваш IBM аккаунт в любое время.

Вся введенная информация защищена.

Выберите имя, которое будет отображаться на экране



При первом входе в developerWorks для Вас будет создан профиль и Вам нужно будет выбрать Отображаемое имя. Оно будет выводиться рядом с контентом, опубликованным Вами в developerWorks.

Отображаемое имя должно иметь длину от 3 символов до 31 символа. Ваше Имя в системе должно быть уникальным. В качестве имени по соображениям приватности нельзя использовать контактный e-mail.

Обязательные поля отмечены звездочкой (*).

(Отображаемое имя должно иметь длину от 3 символов до 31 символа.)

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Вся введенная информация защищена.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=40
Zone=Lotus
ArticleID=284778
ArticleTitle=Интеграция данных IBM Lotus Notes в боковую и инструментальную панель Lotus Notes V8
publish-date=01292008