>> Visual Web Pack のほかのドキュメント

AJAX 進捗バーコンポーネント

目次 -  アプリケーションの設定 -  セッション Bean の変更 -  確定進捗バーの作成 -  進捗バーへのコードの追加 -  その他の可能な操作 #1:不確定進捗バーの追加 -  その他の可能な操作 #2:失敗したタスクのシュミレート -  その他の可能な操作 #3:進捗バーのスタイルの変更

このチュートリアルでは、次のテクノロジとリソースを使用します。

JavaServer Faces コンポーネント / Java EE プラットフォーム	Java EE 5* の場合、1.2 J2EE 1.4 の場合、1.1
Travel データベース	任意
BluePrints AJAX コンポーネントライブラリ	必須

* このチュートリアルの公開時点で Java EE 5 をサポートしていたのは Sun Java System Application Server だけです。

このチュートリアルは、Sun Java System Application Server PE 9.0 Update Release 1 と Tomcat 5.5.17 を使用することを想定しています。別のサーバーを使用している場合は、「リリースノート」と「FAQ」(または「日本語 FAQ」) で既知の問題やその回避策を確認してください。サポートされているサーバーと Java EE プラットフォームについては、「リリースノート」を参照してください。

アプリケーションの設定

1. AJAX コンポーネントの最新版をダウンロードおよびインポートします (まだ行なっていない場合)。
2. SimpleTask.java と pb.js をダウンロードして、ファイルシステムに保存します。

3. 新しいビジュアル Web アプリケーションプロジェクトを「ProgressBarExample」という名前で作成します。

   ProgressBarExample の初期ページがビジュアルデザイナーで開きます。

4. 次のようにして、プロジェクトに SimpleTask.java を追加します。

   1. メインメニューから「ファイル」>「既存項目を追加」>「Java ソース」を選択します。SimpleTask.java を保存したディレクトリに移動します。ファイルを選択し、「追加」をクリックします。

   2. 「プロジェクト」ウィンドウで、「ソースパッケージ」>「progressbarexample」を展開します。「SimpleTask.java」ノードをダブルクリックして、Java エディタでファイルを開きます。

      ファイルの先頭に、次のパッケージ文が追加されます。

      package progressbarexample;

5. 次のようにして、pb.js JavaScript ファイルをプロジェクトに追加します。

   1. 「ファイル」>「既存項目を追加」>「その他 (すべてのファイル)」を選択します。pb.js に移動して選択し、「追加」をクリックします。
   2. 「プロジェクト」ウィンドウで、pb.js を「ソースパッケージ」>「progressbarexample」から「Web ページ」>「resources」にドラッグします。

セッション Bean の変更

1. ビジュアルデザイナーで Page1 を開きます。

2. 「アウトライン」ウィンドウで SessionBean1 を右クリックして、「追加」>「プロパティー」を選択します。

   注: ポップアップメニューを最初に開いたときに「追加」メニューがアクティブになっていない場合は、メニューを閉じて「SessionBean1」ノードをもう一度右クリックすると、「追加」サブメニューがアクティブになります。

3. 「新規プロパティーパターン」ダイアログで、次の図に示すように、「名前」に「taskMap」、「型」に「HashMap」(「名前」と「型」フィールドは大文字と小文字を区別)、「モード」に「読み取り専用」を設定します。「了解」をクリックします。

   図 1:「新規プロパティーパターン」ダイアログ

4. 「SessionBean1」ノードを右クリックし、ポップアップメニューから「Java ソースを編集」を選択します。

   HashMap クラスが見つからないことを示すエラー注釈がコードに表示されます。

5. SessionBean1.java の任意の場所を右クリックしてポップアップメニューから「インポートを修正」を選択し、次のインポート文を自動的に追加します。

   import java.util.HashMap;

6. SessionBean1.init メソッドに次のコードの行 (太字部分) を追加します。

   コード例 1:SessionBean1 プロパティー

   public void init() { // Perform initializations inherited from our superclass super.init(); // Perform application initialization that must complete // *before* managed components are initialized // TODO - add your own initialiation code here Managed Component Initialization // Perform application initialization that must complete // *after* managed components are initialized // TODO - add your own initialization code here taskMap = new HashMap(); taskMap.put("progressBar1", new SimpleTask("progressBar1", 241, 100, false)); }

   
   HashMap を構成し、HashMap に 新しい SimpleTask インスタンスを追加することによって、このコードは taskMap プロパティーを生成します。

確定進捗バーの作成

タスクの実行中に進捗のパーセンテージが判定できる場合に、確定進捗バーを使用します。この節では、1 つの確定進捗バーと 2 つのボタンを含むページをデザインします。最初のボタンは、進捗バーに関連付けられたタスクを開始、一時停止、および再開し、2 番目のボタンはタスクを停止します。ページは次の図のようになります。

図 2:進捗ページのデザイン

1. 「プロジェクト」ウィンドウで、「ProgressBarExample」>「コンポーネントライブラリ」ノードを右クリックし、ポップアップメニューから「コンポーネントライブラリを追加」を選択します。「BluePrints AJAX コンポーネント」を選択し、「コンポーネントライブラリを追加」をクリックします。

   コンポーネントライブラリがプロジェクトにコピーされ、コンポーネントが「パレット」に追加されます。
2. ビジュアルデザイナーで Page1 を開きます。

3. 「パレット」の「BluePrints AJAX Components」セクションを開き、ページに「進捗バー (Progress Bar)」コンポーネントをドラッグします。このチュートリアルでは、デフォルトの「id」プロパティー「progressBar1」を使用します。

   注: 進捗バーは、前述の図 2 のように表示されるはずです。進捗バーが正しく表示されない場合は、ビジュアルデザイナー内を右クリックし、ポップアップメニューから「再表示」を選択します。
4. 「パレット」の「レイアウト」セクションから、「グリッドパネル」コンポーネントを進捗バーの右にドラッグします。
5. グリッドパネルの「id」プロパティーを「controlPanel」に設定し、「columns」プロパティーを「2」に設定します。

6. 「パレット」の「基本」セクションから、「ボタン」コンポーネントを 2 つ、グリッドパネル上にドラッグします。

   ボタンコンポーネントをドロップしたとき、グリッドパネルコンポーネントのアウトラインが青い実線になっていることを確認します。

7. 最初のボタンに次のプロパティーを設定します。

   プロパティー	値
   id	variableControl
   テキスト	Start
   onClick	handleVariableControlOnClick(this, 'form1:progressBar1', false)

   
   handleVariableControlOnClick 関数は、ユーザーがボタンをクリックしたときに JavaScript 呼び出しを行なって、進捗バーを開始、一時停止、または再開します。

8. 2 番目のボタンに次のプロパティーを設定します。

   プロパティー	値
   id	stopControl
   テキスト	Cancel
   onClick	handleStopControlOnClick('form1:variableControl', 'form1:progressBar1')

   
   handleStopControlOnClick 関数は JavaScript を呼び出して、進捗バーを停止します。

9. 「アウトライン」ウィンドウで、form1 を選択します。「プロパティー」ウィンドウで、フォームの「onSubmit」プロパティーを「return handleFormOnSubmit()」に設定します。

   この JavaScript 関数は、ユーザーが 2 つのボタンのいずれかをクリックしたときに、ページの送信を拒否します。

10. 「パレット」の「拡張」セクションから「スクリプト」コンポーネントをページにドラッグします。

    「アウトライン」ウィンドウの「Page 1」セクションに script1 が表示されます。この不可視コンポーネントは生成後の HTML マークアップでスクリプト要素を宣言します。
11. 「プロパティー」ウィンドウで、スクリプトの「url」プロパティーを「/resources/pb.js」に設定します。このプロパティーの先頭には、スラッシュ(/) が必要です。

進捗バーへのコードの追加

この節では、プロジェクトの Java コードに 4 つのメソッドを追加します。これらのメソッドは次のアクションを実行し、「進捗バー」コンポーネントの「イベント」プロパティーになります。

• AJAX 要求で示されたタスクを開始または再開
• AJAX 要求で示されたタスクを一時停止
• AJAX 要求で示されたタスクを停止
• AJAX 要求を送信した進捗バーのコンポーネント id (progressBar1 など) を抽出

1. Java エディタで Page1 を開き、destroy() メソッドのあとに次のコード (太字部分) を追加します。

   コード例 2:追加の進捗バーメソッド

   public void destroy() { } /** * AJAX 要求で示されたタスクを開始または再開する。 */ public void startOrResumeTask(FacesContext context) { String taskId = getTaskIdFromAJAXRequest(context); SimpleTask task = (SimpleTask)getSessionBean1().getTaskMap().get(taskId); Map paramMap = context.getExternalContext().getRequestParameterMap(); String doomed = (String)paramMap.get("doomed"); task.start(Boolean.parseBoolean(doomed)); } /** * AJAX 要求で示されたタスクを一時停止する。 */ public void pauseTask(FacesContext context) { String taskId = getTaskIdFromAJAXRequest(context); SimpleTask task = (SimpleTask)getSessionBean1().getTaskMap().get(taskId); task.pause(); } /** * AJAX 要求で示されたタスクを停止する。 */ public void stopTask(FacesContext context) { String taskId = getTaskIdFromAJAXRequest(context); SimpleTask task = (SimpleTask)getSessionBean1().getTaskMap().get(taskId); task.cancel(); } /** * AJAX 要求を送信を送信した進捗バーのコンポーネント id * ("progressBar1" など) を抽出する。 */ private String getTaskIdFromAJAXRequest(FacesContext context) { Map paramMap = context.getExternalContext().getRequestParameterMap(); String progressBarClientId = (String)paramMap.get("bpui_progressbar_clientId"); if (progressBarClientId == null) { throw new NullPointerException(); } //最後のコロン以降の部分を取得する int lastColon = progressBarClientId.lastIndexOf(NamingContainer.SEPARATOR_CHAR); if (lastColon == -1) { return progressBarClientId; } String taskId = progressBarClientId.substring(lastColon + 1); return taskId; }

   
   進捗バーが AJAX 要求をサーバーに送るときは、進捗バーのクライアント ID が bpui_progressbar_clientId 要求パラメータに含まれます。タスクを開始、一時停止、再開、または停止する AJAX 要求は、アプリケーションのページ Bean の startOrResumeTaskメソッド、pauseTask メソッド、または stopTask メソッドを呼び出します。これらのメソッドは getTaskIdFromAJAXRequest メソッドを呼び出します。このメソッドは bpui_progressbar_clientId 要求パラメータから、コンポーネント id (progressBar1 など) を抽出します。メソッドはコンポーネント id を使用して taskMap から SimpleTask インスタンスを取得し、そのタスクの start、pause、または cancel メソッドを呼び出します。

2. Page1 のソースコード内で右クリックし、ポップアップメニューから「インポートを修正」を選択します。

   IDE は次のインポート文を追加し、クラスがないために起きるエラーを修正します。

   import java.util.Map;
import javax.faces.component.NamingContainer;
import javax.faces.context.FacesContext;

3. Page1 の「デザイン」ビューに戻り、「進捗バー」コンポーネントに次のプロパティーを設定します。

   プロパティー	値
   stopOperation	stopTask()
   resumeOperation	startOrResumeTask()
   startOperation	startOrResumeTask()
   pauseOperation	pauseTask()
   onComplete	function() {handleProgressBarOnComplete('form1:variableControl');}

   
   

   以前にも説明したように、handleVariableControlOnClick および handleStopControlOnClick 機能は、ユーザーがボタンをクリックしたときに、進捗バーの開始、一時停止、再開、または停止の呼び出しを行います。進捗バーでこのようなクライアント側のスクリプトの呼び出しを行うとき、AJAX 要求がサーバに送信されます。その結果、「startOperation」、「pauseOperation」、「resumeOperation」、または「stopOperation」プロパティーに指定したメソッドが呼び出されます。

   handleProgressBarOnComplete 関数は、ユーザーがタスクを再開する場合に備えて、最初のボタンのテキストを「Start」に変更します。

   注: 場合によっては、IDE によって余分な startOrResumeTask メソッドがコードに追加され、コードをコンパイルできなくなることがあります。エラーを解消するには、この余分なメソッドを削除してください。

4. Page1 の「JSP」ビューを開き、次に太字で表示されている progressBar1 の「interval」、「percentage」、「failed」、および「percentageText」の各プロパティーを追加します。

   コード例 3:progressBar1 のプロパティー

   <bp:progressBar binding="#{Page1.progressBar1}" id="progressBar1" interval="#{SessionBean1.taskMap.progressBar1.interval}" percentage="#{SessionBean1.taskMap.progressBar1.percentage}" failed="#{SessionBean1.taskMap.progressBar1.failed}" percentageText="#{SessionBean1.taskMap.progressBar1.percentageText}" onComplete="function() ... resumeOperation=...

   
   進捗バーのこれらのプロパティーは、taskMap で progressBar1 に入力した、SimpleTask インスタンスの対応するプロパティーにバインドされます。プロパティーエディタに制限があるため、このコードは直接 JSP ソースに追加します。

5. アプリケーションを構築し、実行します。「Start」ボタンを押してタスクを開始します。

   操作が進捗するに従って進捗バーが塗りつぶされ、進捗のパーセンテージ (たとえば 25%) を示すテキストメッセージが継続的に更新されます。「Start」ボタンは「Pause」に変わります。
6. 「Pause」ボタン (「Resume」に変わる) および「Cancel」ボタンをクリックして、このアプリケーションについてさらに学習します。

その他の可能な操作 #1:不確定進捗バーの追加

この節では不確定進捗バーを追加します。この進捗バーは、バーを塗りつぶして進捗のパーセンテージを示すのではなく、タスクが進行中であることを動きで示します。不確定進捗バーは、タスクの実行中に進捗量を確定できない場合に、フィードバックを行うのに適しています。この節では、次の図のようなページを構築します。

図 3:不確定進捗バーの追加

1. Page1 のデザインビューを開きます。「進捗バー」コンポーネントと「グリッドパネル」コンポーネントをコピーして、そのコピーを元のコンポーネントの下にペーストします。

   注: チュートリアルのこの節では、これらのコンポーネントに、デフォルトの「id」プロパティー「progressBar2」、「controlPanel1」、「variableControl1」、および「stopControl1」を使用します。

2. 新しい「進捗バー」コンポーネントを選択し、「onComplete」プロパティーを変更して、「variableControl1」を指し示すようにします。

   function() {handleProgressBarOnComplete('form1:variableControl1');}

3. 新しい「Start」ボタンを選択し、「onClick」プロパティーを変更して「progressBar2」を指し示すようにします。

   handleVariableControlOnClick(this, 'form1:progressBar2', false)

4. 新しい「Cancel」ボタンを選択し、「onClick」プロパティーを変更して「variableControl1」と「progressBar2」を指し示すようにします。

   handleStopControlOnClick('form1:variableControl1', 'form1:progressBar2')

5. Page1 の JSP ビューを開きます。</h:panelGrid> 行のあとにある、progressBar2 のコードを探します。progressBar2 の 4 つのプロパティー (太字部分) を変更して、progressBar2 を参照するようにします。

   コード例 4:progressBar2 のプロパティー

   </h:panelGrid> <bp:progressBar binding="#{Page1.progressBar2}" failed="#{SessionBean1.taskMap.progressBar2.failed}" id="progressBar2" interval="#{SessionBean1.taskMap.progressBar2.interval}" onComplete="function() ... percentage="#{SessionBean1.taskMap.progressBar2.percentage}" percentageText="#{SessionBean1.taskMap.progressBar2.percentageText}" resumeOperation=...

    
   スペースに制約があるため、前述のコードのいくつかは 2 行に分かれています。

6. 「SessionBean1.java」ファイルを開き、SessionBean1.init メソッドに次の行を追加します。

   taskMap.put("progressBar2", new SimpleTask("progressBar2", 241, 100, true));

   このコードによって、新しい SimpleTask インスタンスが taskMap に追加されます。2 番目の進捗バーはこのタスクを監視します。SimpleTask コンストラクタへ渡されるパラメータ true は、タスクが不確定であることを確立します。

7. プロジェクトを構築し、実行します。この節で追加した「Start」ボタンをクリックし、不確定タスクを開始します。

   タスクが完了するまで、小さい長方形が左から右へ動き、「(time remaining unknown)」というテキストメッセージが表示されます

8. 「Pause」ボタン、「Resume」ボタン、および「Cancel」ボタンをクリックして、このアプリケーションについてさらに学習します。次の図で、動作中の 2 つの進捗バーを表示します。

   図 4:動作中の進捗バー

その他の可能な操作 #2:失敗したタスクのシュミレート

1. Page1 のデザインビューを開きます。

2. variableControl ボタン (最初の「Start」ボタン) の「onClick」プロパティーを変更して、「false」ではなく「true」が使用されるようにします。

   handleVariableControlOnClick(this, 'form1:progressBar1', true)

   このコードによって、doomed と呼ばれる要求パラメータが、true の値を持つ AJAX 要求に送信されます。ページ Bean の startOrResumeTask メソッドがこのパラメータを取得し、引数として SimpleTask の start メソッドに渡します。

3. variableControl1 ボタン (2 番目の「Start」ボタン) の「onClick」プロパティーを変更して、「false」の代わりに「true」を使用します。

   handleVariableControlOnClick(this, 'form1:progressBar2', true)

4. progressBar1 の「onFail」プロパティーを次のように設定します。

   function() {handleProgressBarOnFail('form1:variableControl');}

   handleProgressBarOnFail 関数は、タスクが失敗すると、ユーザーがタスクを再開する場合のために、最初のボタンのテキストを「Start」に変更します。

5. progressBar2 の「onFail」プロパティーを次のように設定します。

   function() {handleProgressBarOnFail('form1:variableControl1');}

6. プロジェクトを構築し、実行します。

   今回は最初の進捗バーが 25% のところで失敗します。2 番目の進捗バーも失敗しますが、タスクが不確定のため、テキストメッセージにパーセンテージは表示されません。

その他の可能な操作 #3:進捗バーのスタイルの変更

1. ｢プロジェクト｣ウィンドウからこのスタイルシートを開くには、｢ProgressBarExample｣>｢Web ページ｣>｢resources｣>｢stylesheet.css｣ノードをダブルクリックします。

2. 進捗バーの色とフォントを変更する、次の太字で示されたコードを追加して、ファイルを保存します。

   コード例 5:進捗バーの色を設定するスタイルシートのコード

   .bpui_progressbar_portionComplete { background:blue !important; } .bpui_progressbar_portionRemaining { background:lightgrey !important; } .bpui_progressbar_percentageText { color:blue; font-size:14px; font-weight:bold; } .bpui_progressbar_barArea { height:9px !important; }

3. Page1 の「デザイン」ビューを開き、次の図に示される進捗バーの変更を確認します。

   図 5:スタイル化された進捗バー

まとめ

「進捗バー」コンポーネントの主な特徴を次に示します。

• 進捗バーは、確定および不確定のユースケースの両方をサポートします。進捗バーは、-1のパーセンテージを不確定であると解釈します。
• 進捗バーは、ページ Bean のメソッドにバインド可能な startOperation、pauseOperation、resumeOperation、および stopOperation の各イベントを介して、開始、一時停止、再開、および停止の機能をサポートします。
• 進捗バーはバインド可能な boolean 型の「failed」プロパティーで、タスクの失敗をサポートします。
• 進捗バーは、「onComplete」や「onFail」を含む、いくつかの詳細プロパティーを介してカスタムスクリプトをサポートします。カスタム JavaScript を .js ファイルに統合して、ファイルを参照する「スクリプト」コンポーネントを含めることができます。
• 進捗バーはカスタムスタイルをサポートします。

次に、このチュートリアルに説明されている「進捗バー」コンポーネントを使用するヒントを挙げます。

• セッションスコープ内のタスクオブジェクトのマップを保持し、各タスクを異なる進捗バーで監視します。
• 別のスレッドで、時間のかかるタスクをサポートします。モデルとして SimpleTask.java を使用して、特定のタスクを表すクラスを記述できます。SimpleTask.java はスレッドへの参照を保持し、タスクを開始 (または再開)、一時停止、またはキャンセルするメソッドを伝達し、ポーリングインターバル、パーセンテージ、テキスト、およびタスクが失敗したかどうかを示すプロパティーを持っています。

関連項目:

• AJAX およびその他のコンポーネントのダウンロードとインポート
• AJAX マップビューアコンポーネントの使用