OpenSocial 1.1 Inter-Gadget Communicationを日本語訳してみた
OpenSocial 1.1が公開されました！
http://blog.opensocial.org/2010/11/opensocial-11-published.html
目玉はInter-Gadget Communication、つまりガジェット間通信です。それ以外はほとんど変更はなさそう。
元々OpenSocial 0.8にはpubsub featureという機能がありましたが、これはOpenSocial 0.9で捨てられ、OpenSocial 1.1で仕様を変えて復活しました。
1.1のガジェット間通信はOpenAjax Allianceという別団体が策定したOpenAjax Hubという仕様をベースにしています。
で、読んでみたんですけど、よくわからないんで、勢い余って翻訳してみました。
でも、よくわかりません(T^T)
ポイントはメタデータのところかな？
たぶんこれがあると、ガジェット間通信のインターフェースがわかるので、複数のガジェットを後からつなぐという機能をコンテナに実装することができるようになる。
あーどこかで聞いた話だ。これ。
http://www.beacon-it.co.jp/forum2010/demo.html の下から２番目の動画。
「infoScoop Factory "ガジェットをつなぎ、情報をつなぐ" 〜Gadget Integrator〜」
僕とは違う部署で作ってるんだけど、infoScoop の有償版についてるツールです。
OpenSocial 1.1に則ればこれが簡単に作れるんだな。
あとは、OpenSocial 0.8のpubsubだと垂れ流しだから悪意のあるガジェットが他のガジェットがpublishした情報を取得できちゃうんだけど、OpenAjax Hubだとその辺をブロックできるようになっているはず。
なんだけど、その辺の記述が見当たらない。onSecurityAlertってあるからあるはずなんだけど。
英語は全然できないので、いろいろ間違っていると思います。間違いはコメント欄で指摘してもらえるとうれしいです。途中翻訳を放棄しているところもありますw
原文はこちら→OpenSocial Core Gadget Specification 1.1 - C.10 Inter-Gadget Eventing
↓日本語訳はここから下です。↓
C.10 ガジェット間イベント
OpenSocialのガジェット間イベントメカニズム はpub/subとして知られていました。それはトピック上のメッセージ配信により二つのガジェット間通信をゆるやかに可能にしていました。 OpenSocial APIの定義はOpenAjax Allianceの策定したOpenAjax Hub 2.0（OA Hub）仕様をベースにしています。この機能の追加により、3つのエリアにAPIが追加されます。クライアント上でイベントの配信・購読を管理するイベン トハ ブ、ガジェットにpublish/subscribeメソッド、新しいコンテナとツールによって使用されるメタデータの記述です。OpenSocialで 提供されるAPIの用語はOA Hubに合わせます。
pub/subはクライアント-ハブ間のメッセージを通 して処理されます。これはOpenAjax仕様に定められています。一つのガジェットインスタンスごとに一つのハブクライアントがあり、ガジェットがロー ドされると、クライアントはハブに「接続された（connected）」状態になります。ガジェット内でpub/subを使用する一般的なパターンは以下 の通りです。
- （オプション） ガジェットのハブクライアントインスタンスの設定でデフォルト設定を上書きます。
- publishまたはsubscribeメ ソッドを呼びます。
OpenAjax Hubの全ての機能はOpenSocial内で使用可能です。ハブによって提供される機能の全てを理解するには、OpenAjaxのWebサイトのドキュ メントと仕様を参照してください。
ガジェット間通信の利用するために、ガジェットの各イン スタンスはハブに接続するクライアントを必要とします。クライアントの完全な仕様はOpenAjax Allianceのドキュメントで確認することができます。詳しくはOpenAjax Hub Client sectionをご参照ください。pub/subの一般的なパターンでは、ガジェットはトピックに乗せたメッセージを配信（publish）し、他のガジェット（送信が ジェットでもよい）が送信された情報を受け取るトピックを購読（subscribe）します。加えて、OpenAjax Allianceはpub/subを活用したガジェットの開発ガイドラインとして使用するべきベストプラクティスを定めています。詳しくはOpenAjax Hub 2.0 Specification Best Practicesをご覧ください。
C.10.1 ガジェット間イベントをサポートするためのコンテナ要件
OpenAjax Hubクライアントを適切に設定するには、コンテナはガ ジェットにPubSubフィーチャーが追加された場合に、そ のガジェットに対して以下の初期化ステップを提供しなければなりません。このセクションで記述される動作はHubClientインスタンスをセットアップ するために単純なガジェットは何もする必要がないことを保証します。しかし、ガジェットがデフォルトパラメータと動作を必要に応じて上書きすることは許可 します。
- デフォルト値をセットします。
- onLoadハンドラーを登録します。
- onLoadハンドラーはHubClient を作成し、HubClient.connectを呼び出します。
C.10.2 トピック
publishとsubscribeメソッドおよびメタ データの記述も、「ト ピック」を利用します。「トピック」は文字列でなければならず、OpenAjax Hubで定められたネーミングルールに従わなければなりません。以下の箇条書きはOA Hub仕様に記述された内容の要約です。
- ワイルドカードの使用方法： 一つのトークンに対するワイルドカードは「*」、複数のトークンに対するワイルドカードは「**」です。
- ユニコードと特殊文字の考慮： 開発者は制御文字、空白、引用符、句読文字をトピック名にしようすべきではありません。
- 逆DNSのトピック名： 他のコンポーネントとのトピック名の衝突を回避するため、全てのト ピック名は、org.openajax.registerLibarayのようなインターネットドメインを逆順にした文字列 で始めることを推奨します。加えて、トピック名の逆DNS名前空間とOpenSocialデータモデルの拡張を定義する際に使用する接頭辞のパターンは論 理的な相関関係があるべきです。拡張モデルの詳細はOpenSocial Specification [OpenSocial -Specification]をご覧ください。
- 詳 しくはOpenAjax Hub 2.0 Specification Topic Namesをご覧ください。
C.10.2.1 トピック名前空間の予約語
OpenSocialはOpenSocial仕様で使用 するため、逆DNS名前空間「org.opensocial」および全ての派生形を予約語としています。開発者はトピックを定義する際に、 org.opensocialやその派生名前空間を使用してはなりません。
C.10.3 gadgets.Hub
C.10.3.1 メソッドの詳細
C.10.3.1.1 publish
publish(topic, payload)
詳細： publishメソッドはOA Hubの定義に従います。OA Hubはpubsubが匿名で、メッセージ配信ガジェットの識別情報を少しも含まないという考えを受け入れます（？）。以下はOA Hubのドキュメントからの抜粋です。
パラメーター：
| 名前 | 型 | 詳細 |
|---|---|---|
| topic | String | OA Hubで定義されるルールにしたがった配 信されるデータのチャンネルを示す文字列。ワイルドカードは使えません。 |
| payload | * | あ らゆるオブジェクトが指定できます。ただし、payloadはJSONにシリアライズできる必要があります。 |
詳しくは OpenAjax Hub 2.0 documentation をご覧ください。
C.10.3.1.1.1 subscribe
subscribe(topic, callback [,scope [,onCompleteCallback [,subscriberData]]])
詳 細：subscribeメソッドはハブに対してガジェットが受信した情報の中の興味があるトピックを指定するために使用します。情報がそのトピックで配信 された際に、ハブはそのガジェットのコールバックメソッドを呼び出します。ガジェットは同じトピックを複数購読することもできるので、subscribe メソッドはその購読を識別するユニークなIDを返します。このIDはトピックをunsubscribeするときに使用されます。このIDの管理はガジェッ ト開発者の責任です。
パラメーター：
| 名前 | 型 | 詳細 |
|---|---|---|
| topic | String | OA Hubで定義されるルールにしたがった配 信されるデータのチャンネルを示す文字列。ワイルドカードを使うことができます。 |
| callback | String | タ ブが選択された時に実行されるコールバック関数（タブ？？）。コールバック関数は既にあるコールスタックの実行が終わるまで呼び出されません。 |
| scope | object | onData コールバックまたはonCompleteコールバックが実行される際に、JavaScriptの「this」キーワードはこのscopeオブジェクトを参 照します。scopeを指定しなかった場合は、windowになります。 |
| onCompleteCallback | function | subscribe 処理が成功または失敗したかどうかをクライアントアプリケーションに通知するために実行される関数です。 |
| subscriberData | * | ク ライアントアプリケーションがこのデータを提供し、onDataコールバック関数のsubscriberDataパラメータでク ライアントアプリケーションに返されます。 |
戻り値：
| 型 | 詳細 |
|---|---|
| String | 購 読ID。このIDはこのハブインスタンス内でユニークな文字列です。 |
詳しくは OpenAjax Hub documentation をご覧ください。
C.10.3.1.1.2 unsubscribe
unsubscribe(subscriptionId)
詳細： このメソッドはハブからガジェットによる購読を削除するために使われます。指定された購読IDの購読が存在しない場合、unsubscribe関数はすぐ に例外を投げます。存在する場合は、すぐに購読を無効にします。
パラメーター：
| 名前 | 型 | 詳細 |
|---|---|---|
| subscriptionId | String | subscribe (...)メソッドが返す購読ID。 |
詳しくは OpenAjax Hub documentation をご覧ください。
C.10.3.1.2 その他のメソッド
gadgets.Hubオブジェクト IframeHubClientのインスタンスであり、他にもいくつかのメソッドをサポートします。詳細は OpenAjax Hub documentation をご覧ください。
C.10.4 コンテナの例
以下の例はコンテナがこの機能をどのように提供しているかを示しています。
- デフォルト値をセットします。
// Create a pubsub settings object
gadgets.HubSettings = {};
// Set default HubClient constructor params object
gadgets.HubSettings.params = {
HubClient: {
onSecurityAlert: function( alertSource, alertType ) {
alert( "Gadget stopped attempted security breach: " + alertType );
window.location.href = "about:blank"; // Forces container to see Frame Phish alert and probably close this gadget
},
scope: gadgetInstance
} };
// Set default onComplete function for HubClient.connect
gadgets.HubSettings.onConnected = function( hub, suc, err ) { };
- onLoadハンドラーを登録します。
onLoadハンドラーは実際にHubClientを作 成し、ManagedHubにそれを接続します。HubClientの生成と接続の前に、ガジェットはgadgets.HubSettingsに保存され たデ フォルト値を上 書きすることができます。例えば、IframeHubClientはparams, seed, tokenLength, logプロパティをサポートしていますが、デフォルト値は設定されていません。ガジェットはデフォルト値が設定されているonSecurityAlert やscopeを上書きする必要があるかもしれません。さらに重要なことに、HubClient.connectのonComplete関数は通常、が dgets.Hub.subscribeを呼ぶことでガジェットの購読をセットアップします。接続が失敗した場合は、onComplete関数はエラーを 処理します。
// Register an onLoad handler
gadgets.util.registerOnLoadHandler( function() {
try {
// Create the HubClient.
gadgets.Hub = new OpenAjax.hub.IframeHubClient( gadgets.HubSettings.params );
// Connect to the ManagedHub
gadgets.Hub.connect( gadgets.HubSettings.onConnect );
} catch(e) {
// TODO: error handling should be consistent with other OS gadget initialization error handling
}
} );
C.10.5 Gadgetの例
デフォルトでは、HubClientはpubsub-2 コードでガジェットがロードされたときに自動的に初期化されます。ガジェットがHubClientコンストラクタのデフォルトパラメータを上書きしたい場 合は、gadgets.HubSettingsで設定することができます。例えば、以下のようになります。
gadgets.HubSettings.params.HubClient.onSecurityAlert = function(alertSource, alertType) {
// handle security alert here
};
gadgets.HubSettings.params.HubClient.log = function(msg) {
// custom logging code here, for recording logging msgs from HubClient
};
gadgets.util.registerOnLoadHandler(function() {
gadgets.Hub.subscribe("org.foo.bar.topic", callback);
gadgets.Hub.publish("org.foo.bar.topic2", data);
});
詳しくは OpenAjax Hub 2.0 Specification document をご覧ください。
C.10.6 メタデータの記述
OpenSocial仕様はガジェットが配信/購読する ことができるイベントを記述する追加メタデータを定義します。これにより、コンテナはガジェットを自動的につなげる（wire）ことができますし、さ らに、ユーザが配信ガジェットを購読ガジェットにつなげることを可能にするUIも提供できます。例えば、手動連携は次のような ケースで必要となります。複数のガジェットが同じトピック名で配信/購読しており、「date」が、あるガジェットでは開始日を意味するが、他のガジェッ トでは終了日である場合や、トピック名やpayloadのタイプが自動的にマッピングするにはあまりに一般的すぎる場合です。
C.10.6.1 メタデータ記述の属性
| 属性 | 型 | 必須 | 詳細 |
|---|---|---|---|
| name | String | Required | ドッ トで区切られたトピック名（例えば、「org.example.randomNumer」）。この名前は OpenAjax Widget Metadata specification で定義された規則に従います。ガジェット開発者は@name属性にユーザ設定変数を使用して上書きすることもできます。詳細は「@nameに変数を使用す る」(Appendix C.10.6.1.1) を ご覧ください。 |
| type | String | Optional | イ ベントのpayloadデータのタイプ名。指定されない場合は、あらゆる型が使用できます。イベントデータ型(Appendix C.10.6.2)を ご覧ください。 |
| title | String | Optional | 技 術者でない者が理解できるようなイベントタイプのタイトル。指定しない場合は、name属性の値が使用されます。 |
| publish | boolean | Optional | こ のトピックでイベントを配信するかを指定します。デフォルトは「false」です。 |
| subscribe | boolean | Optional | こ のトピックで配信されたイベントを購読するかを指定します。デフォルトは「false」です。 |
| description | String | Optional | ガ ジェットの配信/購読の説明です。これはガジェットの動作を説明するために使用されます。トピック"com.example.address"を購読する ガジェットを考えると、その説明は「このガジェットがcom.example.addressトピックのイベントを受信すると、イベントpayloadと して受け取った住所の10km以内の公共交通機関を表示します。」のようになるでしょう。 |
| aboutUrl | String | Optional | description 属性の説明よりもっと詳しい説明を記載したURL。 |
C.10.6.1.1 @nameに変数を使用する
所定のドメイン内でイベントに特定の基準がない場合、別 のグループの開発者が基本的に同じイベントであるトピックに違う名前を使うことは回避不可能です。いつかはトピック名の標準セットが整備されるかもしれま せんが、インストール環境、レガシー実装、政治要因、他のドメインのサードパーティーガジェットの統合要件、スケジュール制約、などの要因がトピック空間 を分断させることが確実なことも不可避であり、長い間このままであるだろう。（？？？）
重要なのは、この仕様は開発者がガジェット間の単純なミスマッチを橋渡しすることを可能にするメカニズムを提供することです。ガジェット開発者がどこでもこのメカニズムを 使用することも大切です。そによりガジェットの再利用性は最大化するでしょう（こ れが大きな目標です）。
C.10.6.1.1.1 @nameに変数を使用する例
以下は@name属性の定義に変数置換を使用する方法の 例です。
<Require feature="pubsub-2">
<Param name="topics"><![CDATA[
<Topic title="Selected Location" name="__UP_location__"
description="The currently selected location" type="http://nsgs.gov/geo#Place"
publish="false" subscribe="true" aboutUrl="">http://nsgs.gov">
</Topic>
<!-- etc. for other topics -->
]]></Param>
</Require>
C.10.6.2 Event Data Types
OpenAjax Hubはデータ型を示す予約された識別子を定義しています。ツールとコンテナはメッ セージについての情報を推定するためにこれを使用できます。こ のメッセージはト ピックを購読する際にガ ジェットが受け取ることを期待するパラメータと同様に配信されます。（？）
OpenAjax Hubによって提供されるデータ型は「組み込み」です。これらはOpenAjax共通型として参照され、名前空間修飾詞を必要としません。 OpenAjax共通型以外の型を使用する場合は、名前空間修飾しを必ず含まなければなりません。名前空間は逆DNSルールに従うべきです。名前空間 org.opensocial.* は仕様で定義された予約語ですので、使用してはいけません（例えば、ソーシャルデータの型）。
| Type Name | Comments |
|---|---|
| string | ECMAScipt string |
| number | ECMAScipt number |
| boolean | ECMAScipt boolean |
| array | ECMAScipt array, e.g. [ 1, 1, 2, 3, 5, 8 ]. The element type/s are not specified when the generic "array" type is used. |
| object * | ECMAScipt object, e.g. { foo: "bar", baz: "boo" }. The specifics of the object are not specified when the generic "object" type is used. |
| null * | ECMAScipt null |
| length * | Any CSS length value <span>color:redHoward 2009.11.10: CSS version?</span> |
| color * | Any CSS color value |
| id | ID value - probably not useful for OpenSocial Gadgets, but might as well keep the two specs in sync |
| class * | zero of more CSS class names, separated by spaces |
| style * | a string that could be used as value for a 'style' attribute |
| url | A URL <span>color:redHoward 2009.11.09: Do we want "uri" also?</span> |
| html | A fragment of HTML markup. |
| countrycode * | A string that represents an http://www.iso.org/iso/country_codes/iso_3166_code_lists.htm A3 ISO 3166 country code. |
| languagecode * | A string that represents an http://www.loc.gov/standards/iso639-2/php/code_list.php ISO 639-2 language code. |
| A string that represents an e-mail address. | |
| person | A string that holds a person's name. |
| postalcode | A string that represents a postal code. |
| phone | A string that represents a phone number. |
| date * | A string that represents a date. MUST be expressed using the "Date Time String Format" defined in the http://www.ecmascript.org/docs/tc39-2009-043.pdf ECMAScript5 specification using one of the date-only forms. For example: "2009-12-15" |
| time * | A string that represents a time of day. MUST be expressed using the "Date Time String Format" defined in the http://www.ecmascript.org/docs/tc39-2009-043.pdf ECMAScript5 specification using one of the time-only forms. For example: "18:45:00Z" or "10:26:24-05:00" |
| timestamp * | A string that represents a date and time of day. MUST be expressed using the "Date Time String Format" defined in the http://www.ecmascript.org/docs/tc39-2009-043.pdf ECMAScript5 specification. For example: "2009-12-15:18:45.000Z" |
| duration * | A string that represents a duration. MUST have format "PYYYY-DDDThh:mm:ss.fff". For example, "P0400-152T20:45:33.123" means "400 years, 152 days, 20 hours, 45 minutes, 33.123 seconds, while "P0003-000T01:56:22.000" means "3 years, 1 hour, 56 minutes and 22.000 seconds." (Must use this one variant defined in the ISO 8601 standard). |
| * | Asterisk, or missing type attribute, means "any datatype" |
C.10.6.3 メタデータ記述のフォーマット
Pub/Subフィーチャーはトピック情報を表現する文 字列を使用するメタデータのためのフォーマットをサポートします。フォーマットは以下の通りです。
<Require feature="pubsub-2">
<Param name="topics"><![CDATA[
<Topic title="string" name="string" description="string" type="string"
publish="boolean" subscribe="boolean" aboutUrl="string">
</Topic>
<!-- etc. for other topics -->
]]</Param>
</Require>
