initial commit

1 files changed, 255 insertions, 0 deletions

diff --git a/files/ja/monitoring_downloads/index.html b/files/ja/monitoring_downloads/index.html
new file mode 100644
index 0000000000..2fbf6f1f45
--- /dev/null
+++ b/files/ja/monitoring_downloads/index.html
@@ -0,0 +1,255 @@
+---
+title: Monitoring downloads
+slug: Monitoring_downloads
+tags:
+  - Download Manager
+  - Firefox 3
+translation_of: Archive/Mozilla/Monitoring_downloads
+---
+<p>
+Firefox 3 では、ダウンロード状況の監視がかつてなく簡単になりました。これまでのバージョンの Firefox でも実装は可能でしたが、ひとつのオブザーバを一度に登録することしかできませんでした。Firefox 3 では、ダウンロードの監視にいくつでもリスナーを利用できる新しい API が導入されました。
+</p><p>この記事では、Firefox 3 のダウンロードマネージャを利用してダウンロードを監視する方法を実演します。また、親切なおまけとして、<a href="ja/Storage">Storage</a> API を利用してデータベースに <a class="external" href="http://www.sqlite.org/">sqlite</a> コマンドを発行する方法も実演します。その結果は、[ツール] メニューの [Download log] を選択することで開けるウィンドウ上で見ることができます。このウィンドウでは、サンプル用の拡張機能をインストールしてから行われたすべてのダウンロードが一覧表示されます。一覧には、ファイル名、ダウンロード開始時刻と終了時刻、ダウンロード速度、ダウンロード状況が表示されます。ファイルの取得元 URL を示すツールチップも含まれています。
+</p><p><a class="external" href="http://developer.mozilla.org/samples/extension-samples/DownloadLogger.zip">完全なサンプルをダウンロード</a>
+</p>
+<h3 id=".E3.82.BB.E3.83.83.E3.83.88.E3.82.A2.E3.83.83.E3.83.97" name=".E3.82.BB.E3.83.83.E3.83.88.E3.82.A2.E3.83.83.E3.83.97">セットアップ</h3>
+<p>拡張機能の読み込みが完了すると、すぐにいくつかの処理が行われます。具体的には、ダウンロードマネージャの <code><a href="ja/NsIDownloadManager">nsIDownloadManager</a></code> インタフェースのインスタンスを取得し、データを保存するためのデータベースを作成するのに、これらの処理が必要となります。
+</p>
+<pre class="eval"> onLoad: function() {
+   // 初期化コード
+   this.initialized = true;
+   this.strings = document.getElementById("downloadlogger-strings");
+
+   this.dlMgr = Components.classes["@mozilla.org/download-manager;1"]
+                          .getService(Components.interfaces.nsIDownloadManager);
+
+   this.dlMgr.addListener(downloadlogger);
+
+   // データベースを開き、そのファイルをプロファイルディレクトリに保存します
+
+   this.dbFile = Components.classes["@mozilla.org/file/directory_service;1"]
+                    .getService(Components.interfaces.nsIProperties)
+                    .get("ProfD", Components.interfaces.nsIFile);
+   this.dbFile.append("downloadlogger.sqlite");
+
+   // ストレージサービスへのアクセスを取得し、データベースを開きます
+
+   this.storageService = Components.classes["@mozilla.org/storage/service;1"]
+                       .getService(Components.interfaces.mozIStorageService);
+
+   var dbConn = this.storageService.openDatabase(this.dbFile);
+
+   // テーブルを作成します。既に存在する場合は失敗しますが、気にしません。
+
+   dbConn.executeSimpleSQL("CREATE TABLE items (source TEXT, size INTEGER," +
+                           " startTime INTEGER, endTime INTEGER," +
+                           " speed REAL, status INTEGER)");
+   dbConn.close();
+ },
+</pre>
+<p>これは非常に簡単な例です。ダウンロードマネージャのインスタンスは、後で再利用できるよう <code>downloadlogger</code> オブジェクトのメンバー変数にキャッシュされ、<code>addListener()</code> メソッドが呼び出されてダウンロード状況の監視が開始されます。データベースファイルが開かれ、sqlite の <code>CREATE TABLE</code> コマンドが実行されてテーブルが作成されます。
+</p><p>最後に、データベースが閉じられます。
+</p>
+<div class="note"><b>注意:</b> <code><a href="ja/MozIStorageConnection">mozIStorageConnection</a></code> の <code>close()</code> メソッドは Firefox 3 Alpha 8 で追加されました。Firefox の以前のバージョンでは、データベースを明示的に閉じる方法がありません。その代わり、ガベージコレクタが接続オブジェクトを破棄したときに閉じられます。</div>
+<h3 id=".E3.83.80.E3.82.A6.E3.83.B3.E3.83.AD.E3.83.BC.E3.83.89.E7.8A.B6.E6.B3.81.E5.A4.89.E6.9B.B4.E6.99.82.E3.81.AE.E5.87.A6.E7.90.86" name=".E3.83.80.E3.82.A6.E3.83.B3.E3.83.AD.E3.83.BC.E3.83.89.E7.8A.B6.E6.B3.81.E5.A4.89.E6.9B.B4.E6.99.82.E3.81.AE.E5.87.A6.E7.90.86">ダウンロード状況変更時の処理</h3>
+<p>上記のコードが実行されたら、ダウンロードの状況が変わるたびに <code>onDownloadStateChange()</code> メソッドが呼び出されます。これは <code><a href="ja/NsIDownloadProgressListener">nsIDownloadProgressListener</a></code> インタフェースの一部です。
+</p><p>この部分のコードは以下のようになります:
+</p>
+<pre class="eval"> onDownloadStateChange: function(aState, aDownload) {
+   var statement;
+
+   switch(aDownload.state) {
+     case Components.interfaces.nsIDownloadManager.DOWNLOAD_DOWNLOADING:
+
+       // 開始されたダウンロードのために新しい列を追加します。各列には取得元 URI、
+       // サイズ、開始時刻が含まれます。終了時刻とダウンロード速度は、まだ分からないため、
+       // 初めはいずれも 0 に設定します。
+
+       // 状況は、ダウンロードマネージャから提供されるものと同じ、状況を示す値になります。
+
+       var dbConn = this.storageService.openDatabase(this.dbFile);
+       statement = dbConn.createStatement("REPLACE INTO items VALUES " +
+                                          "(?1, ?2, ?3, 0, 0.0, 0)");
+
+       statement.bindStringParameter(0, aDownload.source.spec);
+       statement.bindInt64Parameter(1, aDownload.size);
+       statement.bindInt64Parameter(2, aDownload.startTime);
+       statement.execute();
+       statement.reset();
+       dbConn.close();
+       break;
+
+     // ダウンロードの完了 (失敗もしくは成功) を記録します
+
+     case Components.interfaces.nsIDownloadManager.DOWNLOAD_FINISHED:
+     case Components.interfaces.nsIDownloadManager.DOWNLOAD_FAILED:
+     case Components.interfaces.nsIDownloadManager.DOWNLOAD_CANCELED:
+       this.logTransferCompleted(aDownload);
+       break;
+   }
+ },
+</pre>
+<p>ここで 4 つの進捗状況に注目してみましょう。<code>aDownload.state</code> フィールドで示されるダウンロード状況が <code>Components.interfaces.nsIDownloadManager.DOWNLOAD_DOWNLOADING</code> の場合、ファイルのダウンロードが開始されています。<code>aDownload</code> オブジェクトは <code><a href="ja/NsIDownload">nsIDownload</a></code> オブジェクトです。
+</p><p>その場合、新しいファイルのために、データベースを開いて <code>REPLACE INTO</code> sqlite コマンドを作成することで、データベースに新しい列を作成します。最初の 3 列は、ダウンロードオブジェクトから提供された、取得元 URI、ファイルサイズ、開始時刻フィールドの値に設定されます。残りの列の情報は、この時点では分からないため、ゼロに設定されます。
+</p><p>ダウンロードの進捗状況が、ダウンロードが完了、キャンセル、あるいは失敗したことを示した場合、<code>logTransferCompleted</code> ルーチンを呼び出して、その進捗状況の変更を示すようログを更新します。この部分のコードは以下のようになります。
+</p>
+<pre class="eval"> logTransferCompleted: function(aDownload) {
+     var endTime = new Date();                // 現在時刻が終了時刻になります
+
+     // REPLACE sqlite コマンドを発行して記録を更新します。同じ取得元 URI と開始時刻の
+     // 記録を見つけたら、その記録内の終了時刻、サイズ、速度のエントリーを更新します。
+     // 取得元 URI と開始時刻の両方が一致することを確認することで、同じファイルについて
+     // 複数ダウンロードがあっても、それぞれに記録を取ることができます。
+
+     var dbConn = this.storageService.openDatabase(this.dbFile);
+     var statement = dbConn.createStatement("UPDATE items SET size=?1, " +
+         "endTime=?2, speed=?3, status=?4 WHERE source=?5 and startTime=?6");
+     statement.bindInt64Parameter(0, aDownload.size);
+     statement.bindInt64Parameter(1, endTime.getTime());
+     statement.bindDoubleParameter(2, aDownload.speed);
+     statement.bindInt32Parameter(3, aDownload.state);
+     statement.bindStringParameter(4, aDownload.source.spec);
+     statement.bindInt64Parameter(5, aDownload.startTime);
+     statement.execute();
+     statement.reset();
+     dbConn.close();
+ },
+</pre>
+<p>ここでは単純に、データベースを開いて、<code>UPDATE</code> sqlite コマンドを作成、実行することで、完了したダウンロードと取得元 URI と開始時刻が一致するダウンロード項目を検索し、その情報を更新しています。同じ URI と開始時刻の記録を探すことで、ユーザが同じファイルを何度ダウンロードした場合も、正しく処理を行うことができます。
+</p>
+<h3 id=".E3.83.80.E3.82.A6.E3.83.B3.E3.83.AD.E3.83.BC.E3.83.89.E3.83.AD.E3.82.B0.E3.81.AE.E8.A1.A8.E7.A4.BA" name=".E3.83.80.E3.82.A6.E3.83.B3.E3.83.AD.E3.83.BC.E3.83.89.E3.83.AD.E3.82.B0.E3.81.AE.E8.A1.A8.E7.A4.BA">ダウンロードログの表示</h3>
+<p>ダウンロードログウィンドウのコードは、<code>downloadlogger_dlwindow</code> と呼ばれるオブジェクトの中で完結しています。これはシンプルな例なので、1 回限りのログウィンドウとなっており、それ以降のログの変更は監視していません。ウィンドウが開かれた時点でのダウンロードの状況を単純に表示するだけです。
+</p><p>つまり、ここでの処理はすべて load イベントハンドラだけで行うことができます。コードは以下の通りです。
+</p>
+<pre class="eval"> onLoad: function() {
+   // データベースを開きます
+
+   this.dbFile = Components.classes["@mozilla.org/file/directory_service;1"]
+                    .getService(Components.interfaces.nsIProperties)
+                    .get("ProfD", Components.interfaces.nsIFile);
+   this.dbFile.append("downloadlogger.sqlite");
+
+   // ストレージサービスへのアクセスを取得し、データベースを開きます
+
+   this.storageService = Components.classes["@mozilla.org/storage/service;1"]
+                       .getService(Components.interfaces.mozIStorageService);
+
+   var dbConn = this.storageService.openDatabase(this.dbFile);
+
+   var loglist = document.getElementById("loglist");
+
+   var statement = dbConn.createStatement("SELECT * FROM items");   // テーブル内のすべての項目を取得します
+   try {
+     while (statement.executeStep()) {
+       var row = document.createElement('listitem');
+
+       // 列にセルを追加します
+
+       var cell = document.createElement('listcell');
+       var sourceStr = statement.getString(0);
+       row.setAttribute("tooltiptext", sourceStr);
+       sourceStr = sourceStr.slice(sourceStr.lastIndexOf("/")+1, sourceStr.length);
+       cell.setAttribute("label", sourceStr);   // 取得元
+       row.appendChild(cell);
+
+       cell = document.createElement('listcell');
+       cell.setAttribute("label", (statement.getInt64(1) / 1024).toFixed(1) + "KB");    // サイズ
+       cell.setAttribute("style", "text-align:right");
+       row.appendChild(cell);
+
+       var theDate = new Date(statement.getInt64(2) / 1000);        // 開始時刻
+       cell = document.createElement('listcell');
+       var dateStr = theDate.toLocaleString();
+       cell.setAttribute("label", dateStr);
+       row.appendChild(cell);
+
+       theDate = new Date(statement.getInt64(3));            // 終了時刻
+       cell = document.createElement('listcell');
+       dateStr = theDate.toLocaleString();
+       cell.setAttribute("label", dateStr);
+       row.appendChild(cell);
+
+       var speed = statement.getDouble(4) / 1024.0;
+       cell = document.createElement('listcell');
+       cell.setAttribute("label", speed.toFixed(1) + "KB/sec");
+       cell.setAttribute("style", "text-align:right");
+       row.appendChild(cell);
+
+       var status = statement.getInt32(5);
+       var style = "color:black";
+       cell = document.createElement('listcell');
+
+       var statusStr;
+
+       switch(status) {
+         case 0:
+           statusStr = "Downloading";
+           break;
+         case 1:
+           statusStr = "Complete";
+           style = "color:green";
+           break;
+         case 2:
+           statusStr = "Failed";
+           style = "color:red";
+           break;
+         case 3:
+           statusStr = "Canceled";
+           style = "color:purple";
+           break;
+         case 4:
+           statusStr = "Paused";
+           style = "color:blue";
+           break;
+         case 5:
+           statusStr = "Queued";
+           style = "color:teal";
+           break;
+         case 6:
+           statusStr = "Blocked";
+           style = "color:white background-color:red";
+           break;
+         case 7:
+           statusStr = "Scanning";
+           style = "color:silver";
+           break;
+         default:
+           statusStr = "Unknown";
+           break;
+       }
+       cell.setAttribute("label", statusStr);
+       cell.setAttribute("style", style);
+       row.appendChild(cell);
+
+       loglist.appendChild(row);
+     }
+   } finally {
+     statement.reset();
+     dbConn = null;
+   }
+ }
+</pre>
+<p>このコードは至ってシンプルです。初めに、ログ情報が含まれる sqlite データベースを開いた後、<code>SELECT</code> SQL 構文を作成し、データベースからすべてのエントリーを取得します。
+</p><p>複数の結果を繰り返し処理するために、<code><a href="ja/MozIStorageStatement">mozIStorageStatement</a></code> オブジェクトの <code>executeStep()</code> メソッドを呼び出す <code>while</code> ループを使っています。このメソッドが呼び出されるたびに、結果から 1 つの列が取得されます。
+</p><p>その後、リスト列オブジェクトが作成され、検索結果の各エントリーが取得されて適切なリストセルに挿入されます。
+</p><p>上記のコードからいくつか興味深い点を取り上げてみましょう。
+</p>
+<ul><li> <code><a href="ja/MozIStorageStatement">mozIStorageStatement</a></code> は、<code>getString()</code>、<code>getDouble()</code>、<code>getInt64()</code> といった、検索結果を取得するためのデータ取得ルーチンをいくつか持っています。これらのメソッドは、取得したい値を持つ列のゼロベースのインデックス番号をパラメータとして取ります。
+</li><li> 開始時刻は、その値から JavaScript <code>Date</code> オブジェクトを作成する前に、1000 で割られていることに注意してください。これは、データベースに保存されている時間の精度を、JavaScript で使用される値に変換するためです。
+</li><li> 数値の列を右寄せするために、適切なセルの <code>style</code> 属性に <code>text-align:right</code> を設定しています。
+</li></ul>
+<h3 id=".E8.AA.AD.E8.80.85.E3.81.B8.E3.81.AE.E8.AA.B2.E9.A1.8C" name=".E8.AA.AD.E8.80.85.E3.81.B8.E3.81.AE.E8.AA.B2.E9.A1.8C">読者への課題</h3>
+<p>この拡張機能を改良するためにできる、一見して分かることがいくつかあります。ダウンロードマネージャやストレージ API の使い方を学んでいるなら、以下のようなことを、練習のために調べてみると良いでしょう。
+</p>
+<ul><li> 早速、ダウンロードログウィンドウで、ウィンドウが開かれたときに静的なリストを生成する代わりに、動的に更新するためのコードを追加してみましょう。
+</li></ul>
+<ul><li> 他にもデータを追加してみましょう。すべてのダウンロードの平均ダウンロード速度は？ ダウンロードに最適なパフォーマンスを得られる時間帯はいつでしょう？
+</li></ul>
+<ul><li> アイテムをログから削除したり、ダウンロードが完了したアイテムをすべて削除するボタンを追加してみましょう。
+</li></ul>
+<ul><li> 検索機能を追加してみましょう。
+</li></ul>
+<h3 id=".E9.96.A2.E9.80.A3.E8.B3.87.E6.96.99" name=".E9.96.A2.E9.80.A3.E8.B3.87.E6.96.99">関連資料</h3>
+<p><a href="ja/Storage">Storage</a>, <code><a href="ja/NsIDownloadManager">nsIDownloadManager</a></code>, <code><a href="ja/NsIDownload">nsIDownload</a></code>, <code><a href="ja/NsIDownloadProgressListener">nsIDownloadProgressListener</a></code>
+</p>
+<div class="noinclude">
+</div>