Notes Client Java UI API 概要

Notes Client Java UI API の概要とその利用方法について、主要な API を中心に解説します

IBM Lotus Notes (以下 Notes) は、バージョン 8 からアプリケーションの基盤としてEclipse フレームワークが採用されたことにより、スタンダード版においては、Eclipse プラグイン形式のアプリケーションを実行できるようになりました (スタンダード版とベーシック版の違いについてはサポート技術情報を参照してください)。これにより、従来の Notes アプリケーション開発では実現が難しかった、表現力豊かな UI を持つ操作性に優れたアプリケーションを Java を用いて開発することが可能となり、数多くの開発者の支持を得ることに成功しました。一方で、せっかく Java を使った UI の開発が可能になったにも関わらず、フロントエンドにおける Notes クライアントとの連携を Java で実現するための方法が提供されていなかったことに対して不満の声が寄せられていたのも事実です。その解決策として、Notes 8.5.1 では、新たに Notes Client Java UI API の提供を開始しました。本稿では、Notes Client Java UI API の概要とその利用方法について、主要な API を中心に具体的な例を示しながら解説します。

林田 憲昌 , ソフトウェアエンジニア, Lotus Notes クライアント, IBM

林田 憲昌はソフトウェア開発研究所の Lotus 開発部門に所属するソフトウェアエンジニアで、現在は主に Lotus Notes クライアントの開発に携わっています。リモートデバッグするとテンションがあがります。



小柳 ちか子 (gecko@jp.ibm.com), ソフトウェアエンジニア, Lotus Notes クライアント, IBM  

小柳 ちか子はソフトウェア開発研究所の Lotus 開発部門に所属するソフトウェアエンジニアで、現在は主に Lotus Notes クライアントの開発に携わっています。最近は毎日デバッグを楽しんでいます。



2009年 12月 11日

はじめに

1989年に最初のバージョンが出荷されてから今年で20周年を迎える Lotus Notes/Domino (以下 Notes/Domino) は、そのリリース当初から優れたアプリケーション開発環境を兼ね備えていました。そのフレームワークは非常に強力かつ柔軟なものであり、開発者やパワーユーザーはNotes/Domino 上で動作するアプリケーションの開発やカスタマイズを容易に行うことができました。その結果、Notes/Domino は数多くのビジネスパートナーや開発者の支持を得ることに成功し、これが現在のように広く普及する一因となりました。このため、IBM Lotus はアプリケーション開発環境の充足を図ることが重要であると考え、その機能を拡張したり、より洗練されたものにすることに積極的に取り組み続けています。それと同時に、時代の要望に応じて、サポートするプログラミング言語や開発手法も拡大させてきました。現在では、Notes/Domino 独自の言語である LotusScript や式言語に加えて、C/C++、Java、JavaEE、Webサービス、JavaScript などといったスタンダードな技術を用いて Notes アプリケーションを開発することができるようになっています。さらに、Lotus Notes 8 からはアプリケーションの基盤として Eclipse フレームワークが採用されたことにより、Eclipse プラグイン形式のアプリケーションをスタンダード版 Lotus Notes クライアント内で実行できるようになりました。これにより、従来の Notes アプリケーション開発では実現が難しかった、表現力豊かな UI を持つ操作性に優れたアプリケーションを Java を用いて開発することが可能となりました。また、Eclipse が持つ高い拡張性を利用することで、ツールバーやメニュー、サイドバーアプリケーションの追加といった Notes クライアント自身の拡張を行うこともできるようになりました。このような変化は、従来からの Notes/Domino アプリケーション開発者の幅広い支持を集めると同時に、新たな Java 開発者の関心を引くことにも成功し、開発者コミュニティの拡大へとつながっています。一方で、せっかく Java を使った UI の開発が可能になったにも関わらず、フロントエンドにおける Notes クライアントとの連携を Java で実現するための方法が提供されていなかったことに対して不満の声が寄せられていたのも事実です。具体的には、LotusScript のフロントエンドクラスとして提供されている、UI コンテキストの取得や Notes クライアントの操作のための API と同等の Java API が提供されることを望む声が数多く寄せられていました。そこで、Notes 8.5.1 では、フロントエンドにおけるアプリケーション間の連携を Java で行うための API を Notes Client Java UI API として提供開始しました。本稿では、Notes Client Java UI API の概要とその利用方法について、主要な API を中心に具体的な例を示しながら解説します。なお、本稿で用いるサンプルは、Eclipse 3.4.2、Lotus Expeditor Toolkit 6.2.1 および Notes 8.5.1 を使って開発を行っています。


Notes Client Java UI API の利用方法

まず、事前準備として、Notes クライアント上で動作する Eclipse プラグインを開発するための環境を構築する必要があります。セットアップ方法の詳細については InfoCenter の 「Running Notes from the Eclipse IDE」 を参照してください。開発環境が Windows または Linux の場合には、Lotus Expeditor Toolkit を使って簡単にセットアップすることもできます。詳細については 「Using IBM Lotus Expeditor Toolkit 6.2.1 with IBM Lotus Notes 8.5.1」 を参照してください。

Notes Client Java UI API は、プラグインプロジェクト内のマニフェストファイル (MANIFEST.MF) を開いて「Dependencies」 タブを選択し、「Required Plug-ins」 に 「com.ibm.notes.java.ui」 プラグインを追加することで利用可能になります (図1) 。また、Notes Client Java UI API の中には、従来から提供されている Notes/Domino のバックエンドサービスにアクセスするための Java/CORBA クラスを引数や戻り値として使用しているメソッドも存在します。そのようなメソッドを利用する場合には 「com.ibm.notes.java.api」 プラグインも 「Required Plug-ins」 として追加する必要があります。

図 1. API のプラグインを Required Plug-ins として追加
API のプラグインを Required Plug-ins として追加

NotesSessionJob

com.ibm.notes.java.api.util.NotesSessionJob は Eclipse の API である org.eclipse.core.runtime.jobs.Job を拡張したものであり、リモートサービスへのアクセスや複雑な計算などの時間がかかる処理を実行する際に、UI が固まってしまうのを防ぐために別スレッドで処理を行うことを可能にするものです (Jobの詳細については「On the Job: The Eclipse Jobs API」を参照してください)。さらに、NotesSessionJob が実行される際に呼ばれる NotesSessionJob#runInNotesThread メソッド内で lotus.domino.Session のインスタンスを取得することができ、この Session を介して Notes/Domino のバックエンドサービスにアクセスすることも可能になります (リスト1)。つまり、NotesSessionJob は Eclipse ベースの UI コンポーネントと Notes/Domino のバックエンドサービスをつなぐブリッジの役割を果たすと考えることもできます。パフォーマンスやセキュリティの観点から、Eclipse プラグインアプリケーション内でNotes/Domino のバックエンドサービスにアクセスする際には NotesSessionJob を使用することをお勧めします。

リスト 1. NotesSessionJob クラスの使用例
NotesSessionJob job = new NotesSessionJob("sampleJob") {
   protected IStatus runInNotesThread(Session session, IProgressMonitor monitor) 
         throws NotesException {
      Database db = session.getCurrentDatabase();
      DocumentCollection dc = db.getAllDocuments();
      Document doc = dc.getFirstDocument();
      while (doc != null) {
         …
         …
      }
      …
      …
      return Status.OK_STATUS;
   }
};
job.schedule();

Prompt

com.ibm.notes.java.ui.prompt.Prompt は Notes クライアントが使用している様々なタイプのダイアログボックスを Java から呼び出す際に用いるクラスです。利用したいダイアログボックスのタイプを引数に指定して Prompt#prompt メソッドを呼び出すか、各タイプごとに用意されている専用メソッドを使用することで特定のダイアログボックスを開くことができます。例えば、図2のように、 Notes アプリケーションを選択する際に使われているダイアログボックスを Eclipse プラグインアプリケーションから呼び出す場合には、タイプに PROMPT_CHOOSEDATABASE を指定したPrompt#prompt メソッドか (例. Prompt.prompt(Prompt.PROMPT_CHOOSEDATABASE, "", "",null, null))、Prompt#ChooseDatabase メソッドを使います。このダイアログボックス上でユーザーが選択した Notes アプリケーションの情報は戻り値として取得することができるので、その情報を用いて選択されたアプリケーションにバックエンドでアクセスするといった連携を行うことも可能です (リスト2)。

図 2. Eclipse プラグインアプリケーションから Notes のアプリケーション選択ダイアログボックスを開いた例
Eclipse プラグインアプリケーションから Notes のアプリケーション選択ダイアログボックスを開いた例
リスト 2. Prompt クラスの使用例
// アプリケーション選択ダイアログボックスを開く。
// 選択されたアプリケーションの情報は NotesDatabaseData のインスタンスとして取得できる。
final NotesDatabaseData dbData = Prompt.ChooseDatabase ();
if(dbData != null) {
   NotesSessionJob job = new NotesSessionJob("sampleJob"){
      protected IStatus runInNotesThread(Session session, IProgressMonitor monitor) 
            throws NotesException {
         // ユーザーが選択したアプリケーションにバックエンドでアクセスする
         Database db = session.getDatabase(dbData.getServer(), dbData.getFilePath());
         …
         …
         return Status.OK_STATUS;
      }
   };
   job.schedule();
}

この他にも、リストから値を選択するためのダイアログボックス (図3) やパスワードを入力するためのダイアログボックス (図4) といった、Notes ユーザーにとって馴染みの深いダイアログボックスを利用することができるので、Prompt クラスを使うことによって、Notes クライアントとの親和性が高い UI をもつ Eclipse プラグインアプリケーションを効率的に開発することが可能になります。

図 3. Eclipse プラグインアプリケーションから Notes の選択リストダイアログボックスを開いた例
Eclipse プラグインアプリケーションから Notes の選択リストダイアログボックスを開いた例
図 4. Eclipse プラグインアプリケーションから Notes のパスワード入力ダイアログボックスを開いた例
Eclipse プラグインアプリケーションから Notes のパスワード入力ダイアログボックスを開いた例

NotesUIWorkspace

com.ibm.notes.java.ui.NotesUIWorkspace は Notes クライアント上に表示されているワークスペースに相当するものです。この NotesUIWorkspace を介して、表示中のドキュメントやビューの情報を取得したり、新規文書作成フォームをワークスペース上に表示したりすることができます。

単純に新規文書作成フォームを開くだけであれば、Notes URL (例. notes://modulation/mail/nhayashi.nsf/Message?OpenForm) を利用することも可能ですが、フォームを開く前にデフォルト値をセットしておきたいという場合には Notes Client Java UI API を使用する必要があります。例えば、図5のような宛先 (SendTo) とサブジェクト (Subject) フィールドにデフォルト値がセットされたメール作成フォームを表示させたい場合には、lotus.domino.Document のインスタンスに各フィールドの値をセットしたものを引数として NotesUIWorkspace#composeDocument メソッドを呼び出します (リスト3)。

リスト 3. デフォルト値をセットして新規文書作成フォームを開くプログラムの例
NotesSessionJob job = new NotesSessionJob("composeDocumentJob"){
   protected IStatus runInNotesThread(Session session, IProgressMonitor monitor) 
         throws NotesException {
      Database db = session.getDatabase("modulation/NotesDev", "mail\\nhayashida");

      Document doc = db.createDocument();
      // 「SendTo」と「Subject」フィールドにデフォルト値をセット
      doc.appendItemValue("SendTo", "Norimasa Hayashida/NotesDev");
      doc.appendItemValue("Subject", "Hello World");

      NotesUIWorkspace uiWorkspace = new NotesUIWorkspace();
      // フォームをワークスペース上に開く   
      uiWorkspace.composeDocument(doc);

      return Status.OK_STATUS;
   }
};
job.schedule();
図 5. リスト3のプログラムによって表示された新規メール作成フォーム。「To」 と 「Subject」 にデフォルト値がセットされている
リスト3のプログラムによって表示された新規メール作成フォーム。「To」 と 「Subject」 にデフォルト値がセットされている

また、エージェントを NotesUIWokspace から呼び出すこともできます。これにより、Java だけでは実装が難しい処理を LotusScript や式言語などを使ってエージェントとして実装し、Java から呼び出すといったことが可能になります。リスト4は、標準のメールテンプレートにおいてプリファレンス画面を開く際に使われている 「(Preferences)」 エージェント (図6) を Notes Client Java UI API を使って呼び出すプログラムです。エージェントが実装されている Notes アプリケーションの情報とエージェント名を元に com.ibm.notes.java.api.data.NotesAgentData クラスのインスタンスを生成し、それを引数として NotesUIWorkspace#runAgent メソッドを呼び出しています。この時、2番目の引数として渡すのがコールバックオブジェクトとなる com.ibm.notes.java.ui.callbacks.NotesDocumentDataCallback のインスタンスで、エージェントの実行が完了すると NotesDocumentDataCallback#done メソッドが呼ばれます。これにより、エージェントによる処理が完了したタイミングで別のロジックを走らせるといったことが可能になります。リスト4のサンプルプログラムを実行すると、図7のように Notes のメールとカレンダーのプリファレンスダイアログが開き、このダイアログを閉じたタイミングで done メソッドが呼ばれます。

リスト 4. Notes Client Java UI API を使ってエージェントを呼び出すプログラムの例
NotesSessionJob job = new NotesSessionJob("composeDocumentJob"){
   protected IStatus runInNotesThread(Session session, IProgressMonitor monitor) 
         throws NotesException {
      // エージェントが実装されている Notes アプリケーションの情報とエージェント名から NotesAgentData のインスタンスを生成
      Database db = session.getDatabase("modulation/NotesDev", "mail\\nhayashida");
      NotesDatabaseData dbData = new NotesDatabaseData(db);
      NotesAgentData agentData = new NotesAgentData(dbData, "(Preferences)"); 
      
      NotesUIWorkspace uiWorkspace = new NotesUIWorkspace();
      // コールバックオブジェクト
      NotesDocumentDataCallback callback = new NotesDocumentDataCallback() {
         // エージェントの実行完了時に呼ばれる
         public void done(NotesDocumentDataEvent event) {
            System.out.println("DONE");
         }
      };
      // エージェントの実行
      uiWorkspace.runAgent(agentData, callback, true);

      return Status.OK_STATUS;
   }
};
job.schedule();
図 6. 標準メールテンプレートに実装されている (Preferences) エージェント
標準メールテンプレートに実装されている (Preferences) エージェント
図 7. (Preferences) エージェントを Eclipse プラグインアプリケーションから呼び出し、プリファレンスダイアログを表示させた例
(Preferences) エージェントを Eclipse プラグインアプリケーションから呼び出し、プリファレンスダイアログを表示させた例

NotesUIDocument、NotesUIField

com.ibm.notes.java.ui.documents.NotesUIDocument は現在ワークスペース上に表示されているドキュメントに相当するもので、前述のように、NotesUIWorkspace を介してその情報を取得することができます。また、表示されているドキュメント内の各フィールドに相当するのが com.ibm.notes.java.ui.documents.NotesUIField で、NotesUIDocument のインスタンスから取得することができます。これらの API を用いることで、表示されているドキュメントとフィールドの情報をすべて取得することができます。ここで、Eclipse の API である org.eclipse.ui.ISelectionListener を利用すれば、ワークスペース上に表示されている内容が切り替わる際にイベントを受け取ることができるので、Notes クライアント上にドキュメントが表示されたタイミングでその内容を NotesUIWorksplace#getCurrentDocument メソッドおよび NotesUIDocument#getFields メソッドを使って取得し、様々な処理を行うといったアプリケーションを開発することが可能になります (リスト5)。図8は、Notes のワークスペース上にドキュメントが表示された際に、そのドキュメント内のフィールド一覧を取得してリストアップするサンプルアプリケーションです。

リスト 5. ワークスペース上に表示されている内容が切り替わった際に、表示されているドキュメントの内容を取得するプログラムの例
PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService()
     .addSelectionListener(new ISelectionListener() {
        // ワークスペース上に表示されている内容が切り替わった際に呼ばれる
        public void selectionChanged(IWorkbenchPart workbenchPart, ISelection selection) {
           NotesUIWorkspace uiWorkspace = new NotesUIWorkspace();
           // 現在表示されているドキュメントを取得。
           // ドキュメント以外のものが表示されている場合には戻り値は null となる。
           NotesUIDocument uiDocument = uiWorkspace.getCurrentDocument();
           if(uiDocument != null && uiDocument instanceof NotesUIDocument) {
              // 現在表示されているドキュメント内の全フィールドを取得
              NotesUIField[] uiFields = uiDocument.getFields();
              …
              …
           }
        }
     });
図 8. ワークスペース上に表示されているドキュメントの全フィールド情報をリストアップするサイドバーアプリケーション
ワークスペース上に表示されているドキュメントの全フィールド情報をリストアップするサイドバーアプリケーション

また、NotesUIDocument や NotesUIField を用いることで、単に表示中のドキュメントの内容を取得することができるだけでなく、ドキュメントを編集モードにする、フォーカスが当たっているフィールドの情報を取得する、フォーカスを別のフィールドに移動させる、カーソルの位置にテキストを挿入するなどといった、 UI コンテキストに応じた情報の取得やドキュメントの編集を行うことも可能です。例えば、NotesUIDocument#getField(String name) メソッドを使って特定の名前を持つフィールドに相当する NotesUIField を取得し、そのインスタンスに対して NotesUIField#setText メソッドで値をセットすることで、UI 上に表示されているフィールドの内容を書き換えることができます。この方法を用いて先ほどのサイドバーアプリケーションを改良したのが図9で、サイドバーアプリケーションのリスト上で値を変更すると、表示されている Notes ドキュメントの内容も更新されます。このように、Notes Client Java UI API を用いることで、Eclipse プラグインアプリケーションから Notes クライアントの UI に対して操作を行うことができるようになります。

図 9. サイドバーアプリケーションのリスト上での変更内容を Notes ドキュメントにも反映
サイドバーアプリケーションのリスト上での変更内容を Notes ドキュメントにも反映

クリックして大きなイメージを見る

図 9. サイドバーアプリケーションのリスト上での変更内容を Notes ドキュメントにも反映

サイドバーアプリケーションのリスト上での変更内容を Notes ドキュメントにも反映

DocumentFieldListener

com.ibm.notes.java.ui.listeners.DocumentFieldListener は、現在表示されているドキュメント上においてフォーカスされているフィールドが変更された際に発生するイベントを受け取るためのイベントリスナーです。NotesUIDocument のインスタンスに NotesUIDocument#addFieldListener メソッドを使ってこのリスナーを追加することでイベントの通知を受け取ることができるようになります。イベントが発生すると DocumentFieldListener#fieldChanged メソッドが呼ばれ、現在フォーカスが当たっているフィールドとイベント発生前にフォーカスが当たっていたフィールドの情報を com.ibm.notes.java.ui.events.DocumentFieldChangeEvent のインスタンスとして取得することができます (リスト6)。これらの API を使って先ほどのサイドバーアプリケーションをさらに改良したのが図10です。Notes ドキュメント上でフォーカスされているフィールドが変更された際に、イベント発生前にフォーカスが当たっていたフィールドの値が変更されたかどうかをチェックし、値が変更されている場合にはサイドバーアプリケーションのリストの値も更新しハイライトするといった連携を行っています。

リスト 6. DocumentFieldListener を使ってフォーカスされているフィールドが変更された際にイベントを受け取るプログラムの例
NotesUIWorkspace uiWorkspace = new NotesUIWorkspace();
NotesUIDocument uiDocument = uiWorkspace.getCurrentDocument();
uiDocument.addFieldListener(new DocumentFieldListener()){
   public void fieldChanged(DocumentFieldChangeEvent event) {
      // イベント発生前にフォーカスが当たっていたフィールドの情報を取得
      NotesUIField oldField = event.getOldField();
      // 現在フォーカスが当たっているフィールドの情報を取得
      NotesUIField newField = event.getNewField();
      …
      …
   }
});
図 10. Notes ドキュメント上でフォーカスの位置が変更された際にイベントを受け取り、サイドバーアプリケーションのリストの内容を更新
Notes ドキュメント上でフォーカスの位置が変更された際にイベントを受け取り、サイドバーアプリケーションのリストの内容を更新

クリックして大きなイメージを見る

図 10. Notes ドキュメント上でフォーカスの位置が変更された際にイベントを受け取り、サイドバーアプリケーションのリストの内容を更新

Notes ドキュメント上でフォーカスの位置が変更された際にイベントを受け取り、サイドバーアプリケーションのリストの内容を更新

従来のバックエンドクラスだけでは、Notes アプリケーション上に保存されたドキュメントの内容しか取得することができませんでしたが、NotesUIDocument や NotesUIField を利用することで、UI 上に表示されている編集中の値を取得することができるようになります。さらに、DocumentFieldListener を組み合わせれば、ユーザーがどのフィールドに対して操作を行い、それによってどのように値が変化したのかといったことを確認することができるようなります。これにより、例えば、フォーカスが移動した際にフィールドの値を検証し、問題があればユーザーに通知するといった入力補助機能を実装することも可能です。フィールドのフォーカス変更時のイベント以外にも、NotesUIDocument#addEditListener および NotesUIDocument#addModifiedListener メソッドを用いることで、ドキュメントが編集モードになった際や保存された際に発生するイベントを取得することができるようになります。これらのリスナーにより、ユーザーの操作やドキュメントの状態に応じた処理を行うことが可能となり、フロントエンドにおける Notes クライアントとの連携度が高い Eclipse プラグインアプリケーションの開発を実現することができます。


まとめ

本稿では、Notes Client Java UI API の概要とその利用方法について、主要な API を中心に具体的な例を示しながら説明しました。Notes Client Java UI API を用いることで、他の Notes アプリケーションや Notes クライアント自身との連携をフロントエンドで行うことができるようになり、より Notes クライアントとの親和性が高い Eclipse プラグインアプリケーションの開発が可能になります。本稿で紹介した以外にも様々なクラスやメソッドが提供されていますので、Javadoc も併せて参照してください。また、本稿で用いたサンプルプログラムもダウンロード可能ですので、開発の足がかりとして利用してみてください。


ダウンロード

内容ファイル名サイズ
サンプルコードcom.ibm.notes.java.ui.api.sample.zip73KB

参考文献

コメント

developerWorks: サイン・イン

必須フィールドは(*)で示されます。


IBM ID が必要ですか?
IBM IDをお忘れですか?


パスワードをお忘れですか?
パスワードの変更

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


お客様が developerWorks に初めてサインインすると、お客様のプロフィールが作成されます。会社名を非表示とする選択を行わない限り、プロフィール内の情報(名前、国/地域や会社名)は公開され、投稿するコンテンツと一緒に表示されますが、いつでもこれらの情報を更新できます。

送信されたすべての情報は安全です。

ディスプレイ・ネームを選択してください



developerWorks に初めてサインインするとプロフィールが作成されますので、その際にディスプレイ・ネームを選択する必要があります。ディスプレイ・ネームは、お客様が developerWorks に投稿するコンテンツと一緒に表示されます。

ディスプレイ・ネームは、3文字から31文字の範囲で指定し、かつ developerWorks コミュニティーでユニークである必要があります。また、プライバシー上の理由でお客様の電子メール・アドレスは使用しないでください。

必須フィールドは(*)で示されます。

3文字から31文字の範囲で指定し

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


送信されたすべての情報は安全です。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Lotus
ArticleID=451803
ArticleTitle=Notes Client Java UI API 概要
publish-date=12112009