2011/12/20

Web Storage APIを別空間から使ってみる - HTML5 Adv




12月20日のHTML5 Advent Calendar担当の@shoitoです。

今回は、以前にも本ブログで軽く紹介したことがある、Web Storage APIをFlash側と共有する簡単な方法について紹介します。業務でHTML5(File APIやWeb Storage, Application Cache...)以外にも、Flash/Flexもまだ現役で使用中(主にメンテ)なので、その両方に関係するネタを扱うことにしました。

ページの一部にFlashが埋め込まれているようなページで、HTML部分とFlash部分の共有ストレージ領域を設けられないかと思って、Web Storage APIに今回白羽の矢が立ちました。

多くのブラウザで利用できるAPIであることが大事ですので、Web Storage APIについて確認してみると、IE6, 7以外のほとんどのブラウザで使えることがわかります。

イメージ的には下記のようになりますが、Web Storage APIはもちろんJavaScript APIなので、ページ内のJavaScriptから簡単に扱えます。しかし、Flash側からWeb Storageのストレージ領域にアクセスするAPIがありません。そこでActionScriptでWeb Storage APIを実装します。青の矢印部分。

まず、ActionScriptのAPIを実装するために、W3Cで公開されているWeb Storage API仕様を確認すると、引数、戻り値の方は基本的にvoidかDOMStringなので扱いやすそうです。
Web Storage API自体シンプルなので、メソッドの数も多くはありません。なお、Local StorageとSession Storageはインターフェースは同じで、スコープが違うだけです。

次に、実装に用いるflash.external.ExternalInterfaceクラスのリファレンスに目を通すと下記のように説明されています。
ActionScript から、HTML ページに対して次のことを実行できます。
  • 任意の JavaScript 関数を呼び出す 
  • 引数の数を名前と共に渡す 
  • ブール(Boolean)、数値(Number)、ストリング(String)などの各種データ型を渡す 
  • JavaScript 関数からの戻り値を受け取る 
HTML ページの JavaScript から、次のことを実行できます。
  • ActionScript 関数を呼び出す
  • 標準の関数呼び出しの表記法を使用して、引数を渡す
  • JavaScript 関数に値を戻す
注目すべき点を太字にしましたが、ExternalInterfaceを利用することで、ActionScriptからJavaScript APIを利用できることが分かります。下記のようなイメージになります。

これに着目して、実装したActionScript APIが下記になります。
package com.google.code.as3webstorage {
    import flash.external.ExternalInterface;

    public class LocalStorage {
        public static function length():uint {
            return ExternalInterface.call("function() { return localStorage.length; }");
        }

        public static function key(index:uint):* {
            return ExternalInterface.call("localStorage.key", index);
        }

        public static function getItem(key:String):* {
            return ExternalInterface.call("localStorage.getItem", key);
        }

        public static function setItem(key:String, data:*):void {
            ExternalInterface.call("localStorage.setItem", key, data);
        }

        public static function removeItem(key:String):void {
            ExternalInterface.call("localStorage.removeItem", key);
        }

        public static function clear():void {
            ExternalInterface.call("localStorage.clear");
        }
       
        public static function available():Boolean {
            return ExternalInterface.available && ExternalInterface.call("function() { return typeof localStorage != 'undefined'; }");
        }
       
        public static function addStorageEventListener(func:Function, useCapture:Boolean = false):void {
            ExternalInterface.call("as3webstorage.assignSwf", ExternalInterface.objectID);
            ExternalInterface.addCallback("callbackToAs", func);
            ExternalInterface.call("as3webstorage.addStorageEventListener", "callbackToAs", useCapture);
        }
    }
}
ActionScriptに見慣れていない方には分かりにくいと思います。
どういうことをしているかと言うと、getItem()やsetItem()など各メソッドの中で、JavaScriptによるWeb Storage API実装を呼ぶようにしています(ラップしているだけ)。
call()メソッドの第一引数にJavaScriptコードの文字列表現、第二引数に各Web Storage APIに渡す引数を指定しています。こうすることで、ExternalInterfaceを通して、JavaScript <---> ActionScript連携が実現できます。しかし、これだけだとWeb Storage APIのStorageイベントを扱うことができません。

そこで、addStorageEventListener()用のコールバックをJavaScript側に実装します。
(function() {
    if (this.as3webstorage) return;
   
    var as3webstorage = this.as3webstorage = {
        swf: null,
       
        assignSwf: function(swfId) {
            this.swf = document.all ? window[swfId] : document[swfId];
        },

        addStorageEventListener: function(callback, useCapture) {
            window.addEventListener("storage", function(event) {
                var returnObject = {
                    "key": event.key,
                    "oldValue": event.oldValue,
                    "newValue": event.newValue,
                    "uri": event.uri,
                    "source": undefined,
                    "storageArea": undefined
                };

                as3webstorage.toNativeFunc(as3webstorage.swf, callback).apply(null, [returnObject]);
            }, useCapture);
        },
       
        toNativeFunc: function(obj, functionName) {
            return function() {
                var parameters = [];
                for(var i = 0; i < arguments.length; i++) {
                    parameters[i] = "_" + i;
                }
               
                return Function(
                    parameters.join(','),
                    'this["' + functionName + '"](' + parameters.join(',') + ')'
                ).apply(obj, arguments);
            };
        }
    };
})();
サンプルを作ったので下記で試せます。
http://dl.dropbox.com/u/227786/code/flex/as3webstorage/as3localstorage.html
本当にWeb Storageが使われているかはデベロッパーツールなどを使って確認してください。

ExternalInterfaceでJavaScript <---> ActionScript間のデータ交換はXML形式で行われるので、オブジェクトによってはデシリアライズできないものもあります。
そのため、シンプルなインターフェースなら今回のように実装することが可能なのですが、Indexed Database APIのような複雑なものだと難しそうです。

あ、これって誰得?ActionScriptの話が多くない?という感じで終わってすいません。
HTML5 Advent Calendar 2011はまだ続きますのでお楽しみに。

関連記事
Flash + HTML 5 : Offline Flash Apps using DataStore API
http://blog.flexgeek.in/2010/05/flash-html-5-offline-flash-apps-using-datastore-api/ 
HTML5 Web Storage APIをFlash/Flexから使う - as3webstorage
http://blog.air-life.net/2010/06/as3webstorage.html 
HTML5 Geolocation APIをFlash/Flexから使う - as3geolocation
http://blog.air-life.net/2010/06/as3geolocation.html

2011/12/15

JIRA 5.0、REST APIとREST API Browser

JIRA Advent Calendarの12/15担当 @shoito です。

今回は、フライング気味にJIRA 5.0(12/15時点ではRC2)のREST APIとREST API Browser(RAB)について紹介します。
12/14担当の@showyouさんとREST APIネタで被っている気がしますが気にしませんw

みなさんはJIRAプラグインやJIRA連携ツールはご存知でしょうか?
初耳という方はどんなものがあるのかAtlassian Plugin Exchangeをご覧ください。
https://plugins.atlassian.com/plugin/home
Atlassian Plugin Exchange
JIRAプラグイン
JIRA以外にも、Confluence, FishEye, Bamboo, Crowd, CrucibleなどAtlassian製品のプラグインが1000以上あり、JIRAだけでも12/15時点で、395のプラグイン(または連携ツール)が公開されています。
Atlassian製品のGreenHopperやBonfireもJIRAプラグイン(+ブラウザ拡張)ですので、Atlassian Plugin Exchangeで見つけることができます。

JIRA連携ツール
JIRAはAPIを公開してくれているので、他のツールと連携させることが可能です。
SOAP、XML-RPC、REST APIと受け口は設けられていて、連携元の構成に合わせて選択できますが、今回はREST APIに焦点を絞って話を進めます。
ちなみに、連携ツールとしてはEclipseやVisualStudioなどのIDEと連携するAtlassian Connectorが私は思い浮かびます。

REST APIを試す準備
JIRA 5.0のREST APIを試すためには、まずAtlassian SDKをインストールします。
Mac OS X環境でHomebrewを使っていれば、下記のコマンドでインストールできます。
$ brew install atlassian-plugin-sdk
他の環境の方はAtlassian Developersからダウンロードし、PATH変数の設定などを行います。
この辺はInstalling the Atlassian Plugin SDKが参考になります。

次に、JIRAプラグイン/連携ツール開発用のJIRAを立ち上げるために、プロジェクトを作ります。
JIRA 5にするのかい?4にするのかい?と聞かれるので、JIRA 5を使うように1を選択しましょう。
$atlas-create-jira-plugin

A new plugin structure is required for JIRA 5 plugins due to significant changes in the APIs.
Create a plugin for?
1) Shiny new JIRA 5
2) Regular 'ol JIRA 4 (or earlier)
mavenプロジェクトのgroupIdやartifactIdなどの入力を求められるので、適当に入力します。
Define value for groupId: : com.github.astah
Define value for artifactId: : jira-connector
Define value for version:  1.0-SNAPSHOT: :
Define value for package:  com.github.astah: : com.github.astah.connector.jira
Confirm properties configuration:
groupId: com.github.astah
artifactId: jira-connector
version: 1.0-SNAPSHOT
package: com.github.astah.connector.jira
このままの状態で、atlas-run コマンドを実行してJIRAを起動すると5.0-beta1で起動してしまうので、pom.xmlのjira.versionを最新バージョンに変更します。
REST APIは5.0 finalに向けてどんどん追加されていっていたので、beta1のままだと扱えないAPIがあるためです。
[before]
<jira.version>5.0-beta1</jira.version>
[after]
<jira.version>5.0-rc2</jira.version>
pom.xmlを編集し終えたら、atlas-run コマンドを実行します。
$ atlas-run
JIRAの実行に必要なライブラリが大量にmavenリポジトリからダウンロードされ、私の家の貧弱な回線では30分程度時間がかかったので、この間にランチやディナーにでも行ってください。

さぁ、これでJIRAのREST APIを試す環境はできましたが、このままではプロジェクトも課題もadmin以外のユーザーも存在しないので、適当なプロジェクトを作って、課題を幾つか登録しておくことをお勧めします。
(準備でここまで...)

REST API
REST APIを使うことでプロジェクト、ユーザー、課題の検索や操作などが行えます。
では、JIRA REST API Tutorials を見ながら幾つか試してみましょう。

下記の例では、初期状態で登録されているadminユーザー、パスワードadminでREST APIを読んでいます。
  • 課題JAC-1の詳細をJSON形式で取得
  • JIRAにあるプロジェクトの一覧をJSON形式で取得
  • adminユーザーにアサインされている課題の一覧をJSON形式で取得
というように、これは一例ですがこれまでもREST APIを試すことが出来ました。
しかし、curlコマンドやREST ConsoleよりもJIRAに特化して試しやすいツールがAtlassian SDK 3.6.2から登場しました。それがREST API Browserです。

REST API Browser(RAB)
Atlassian SDKに含まれるJIRAプラグイン。各種REST APIをブラウザ上から試すことができます。
何が便利かというと、まず各APIのパラメーターをイチイチ調べなくて良くなりました。
各APIを試すためのフォームが設けられていて、そこにパラメーターの入力フィールドもあるため、このAPIのパラメーターはprojectIdと何を指定するんだっけ?issueId?fieldsだっけ?ということがなくなりました。
レスポンスのJSONも当たり前のように整形されていてステキです。

まず上部から試したいAPIを選択します。
ここでは、11番目くらいにあるAtlassian JIRA - Plugins - REST Plugin (/rest/api/2)を試しましょう。

次に、adminユーザーにアサインされている課題の一覧を取得してみます。
/search を選択し、jql フォームに assignee=admin と入力し、Executeボタンを押下します。
するとスクリーンショットにあるように、リクエスト、レスポンスヘッダ、レスポンスボディが確認できます。

ちなみに、選択できるカテゴリを数えてみたら34ありました。スゴいなー。
Applinks Product Plugin
Atlassian Developer Toolbox
Atlassian Embedded Crowd - Administration Plugin
Atlassian JIRA - Plugins - Admin Quick Navigation
Atlassian JIRA - Plugins - Common AppLinks Based Issue Link Plugin
Atlassian JIRA - Plugins - Confluence Link
Atlassian JIRA - Plugins - Gadgets Plugin
….
まとめ
準備のため長い前置きとREST APIとREST API Browserについて紹介しました。
REST API Browserの登場のおかげで、連携ツールの開発が進めやすくなったと思います。
是非、来年(?)正式リリース予定のJIRA 5.0のREST APIで遊んでみてください。

注意
atlas-runで起動したJIRAでは、JIRA_HOMEがtarget/jira/home ディレクトリに設定されているため、atlas-cleanコマンド(mvn clean)を実行するとキレイさっぱりと消えてしまいます。
そもそも開発用ですので、適宜データをExportしておくか、消えるのを覚悟しておいてください。

次の担当は @literaliceさんです。お楽しみに!
JIRA Advent Calendar (#jiraadvent) ではあと10人(9人?)の書き手が不足しているようなので、JIRAを既に使いこなしている方もまだまだこれからという方も立候補してみてはいかがでしょう。

最後に
REST API周りでは @kompiroさんとの会話で気づいたことや存在を教えてもらったことが含まれています。@kompiroさん、ありがとうございます。