FIWAREアプリケーションマッシュアップ - Widget API 仕様

日付 : 2016年8月26日

このバージョン :

https://github.com/Wirecloud/wirecloud/tree/1.0.x/docs/widgetapi/

前のバージョン :

https://github.com/Wirecloud/wirecloud/tree/0.9.x/docs/widgetapi/

最新バージョン :

https://github.com/Wirecloud/wirecloud/tree/develop/docs/widgetapi/

編集者

  • Álvaro Arranz, Universidad Politécnica de Madrid

著作権

Copyright © 2012-2016 by Universidad Politécnica de Madrid

ライセンス

この仕様書は、 FIWARE Open Specification License (暗黙の特許ライセンス) の下でライセンスされています。

要約

Application Mashup GE は、さまざまな性質のために組み合わせられない2つの別々のAPIを提供しています。Widget API (本書の対象) は JavaScript API であり、Application Mashup API は RESTful API です。Application Mashup RESTful API は、次のリンクから入手できます :

http://wirecloud.github.io/wirecloud/restapi/latest/

Widget API は、ウィジェット/オペレータが Application Mashup GE (ワイヤーリング、プレファレンス、コンテキスト情報、 ログなど)によって提供される機能にアクセスできるようにする JavaScript API です。他の機能の中でも、このAPI は、 ウィジェット/オペレータがリモートリソースにアクセスできるようにします (クロスドメイン・プロキシ経由で リモート REST API にアクセスするなど)。

また、このドキュメントでは、FIWARE Application Mashup GE のリファレンス実装である WireCloud を使用してテスト できるいくつかの例を示します。

このドキュメントのステータス

これは進行中の作業であり、日々変化しています。利用可能な最新バージョンは、 https://github.com/Wirecloud/wirecloud/tree/develop で確認できます。あなたのコメントを wirecloud@conwet.com に送ってください。

この仕様書は、 FIWARE Open Specification License (暗黙の特許ライセンス) の下でライセンスされています。

Widget API

MashupPlatform.http

このモジュールは、クロスドメイン・プロキシの使用をサポートするなど、HTTP リクエストを処理するいくつかの方法を 提供します。

現在、このモジュールは2つの方法で構成されています :

MashupPlatform.http.buildProxyURL メソッド

このメソッドは、クロスドメイン間の問題を回避するのに適した URL を作成します。通常、Application Mashup Proxy を使用して処理されますが、ブラウザがサポートしている場合は、アクセス制御リクエストヘッダを使用して処理することも できます。必要な要件がすべて満たされている場合、この関数はプロキシを使用せずに URL を返します。

MashupPlatform.http.buildProxyURL(url, options)
  • url (required, string): ターゲット URL
  • options (optional, object): リクエスト・オプションを持つオブジェクト (後述)

使用例 :

var internal_url = "http://server.intranet.com/image/a.png";
var url = MashupPlatform.http.buildProxyURL(internal_url, {forceProxy: true});
var img = document.createElement("img");
img.src = url;

MashupPlatform.http.makeRequest メソッド

このメソッドは内部的に buildProxyURL メソッドを呼び出して、CORS リクエストを許可するブラウザに続く同じ起点ポリシーに 関連する問題を回避します。

MashupPlatform.http.makeRequest(url, options)
  • url (required, string): リクエストを送信する URL
  • options (optional, object): リクエスト・オプションのリストを持つオブジェクト (後述)

このメソッドは、Request オブジェクトを返します。

使用例:

$("loading").show();
let request = MashupPlatform.http.makeRequest("http://api.example.com", {
    method: "POST",
    postBody: JSON.stringify({ key: value }),
    contentType: "application/json",
    onSuccess: function(response) {
        // A response in the 2xx range was received
    },
    onFailure: function(response) {
        // Something went wrong connecting to the server or a response outside
        // 2xx range was received
    },
    onComplete: function() {
        $("loading").hide();
    }
});

Request オブジェクトは、次のシナリオをサポートする Promise の互換性もあります:

$("loading").show();
let request = MashupPlatform.http.makeRequest("http://api.example.com", {
    method: "POST",
    postBody: JSON.stringify({key: value}),
    contentType: "application/json"
});
request.then(
    (response) => {
        // We have a response from the server
    },
    (error) => {
        // Impossible to read a response from server
    }
).finally(
    () => {
        $("loading").hide();
    }
);

これは、Promise.all(), Promise.allSettled(), Promise.any() または Promise.race() のような他の Promise メソッドで Request オブジェクトを使用できることも意味します。

リクエスト・オプション : 一般オプション

  • contentType (string): リクエストの Content-Type ヘッダ。提供されていない場合は、postBody オプションの値から Content-Type ヘッダが推定されます。postBody 値が String の場合、デフォルトは application/x-www-form-urlencoded になります。Content-Type ヘッダの値を強制的に使用する場合は、このオプションを指定します
  • encoding (string; default UTF-8): リクエストの内容のエンコーディング。現状のまま残しておくのが最善ですが、 奇妙なエンコーディングの問題が発生した場合は、これを調整する必要があります
  • method (string; default POST): リクエストに使用する HTTP メソッド
  • responseType (string; default: ""): レスポンス・タイプを変更するために設定できます。このオプションの有効な値は 、"", "arraybuffer", "blob", "document", "json" と "text" です
  • parameters (object): リクエストのためのパラメータ。これは、GET メソッドのURLに、または PUT メソッドと POST メソッドを使用するときにリクエスト・ボディにエンコードされます
  • postBody (ArrayBufferView, Blob, Document, String, FormData): リクエスト・ボディとして使用する コンテンツ。通常は POST と PUT リクエストを使用しますが、すべてのリクエストで使用することができます。 提供されていない場合は、代わりに parameters オプションの内容が使用されます。最後に、パラメータがない場合、 リクエストにはボディがありません
  • requestHeaders (object): ヘッダ名を表すプロパティを持つ、一連のキーと値のペア
  • supportsAccessControl (boolean; default false): ターゲットサーバが Access Control ヘッダをサポートするかどうかを示します。したがって、可能な場合はクロスドメイン・プロキシを使用せずに リクエストします
  • withCredentials (boolean; default false): Access-Control クッキーや承認ヘッダなどの資格情報を使用して クロスサイト・リクエストを行う必要があるかどうかを示します。さらに、このフラグは、クッキーをレスポンスで 無視する時を示すためにも使用されます。
  • forceProxy (boolean; default false): 渡された他のオプションに関係なく、プロキシを介してリクエストを 送信します
  • context (object; default null): このパラメータとしてコールバックに渡す値。context が null の場合、 コールバックの this パラメータはそのまま残されます

リクエスト・オプション : コールバック・オプション

  • onAbort (WireCloud 0.8.2 の新機能): MashupPlatform.http.makeRequest() によって返された、 リクエスト・オブジェクトの abort（） メソッドが呼び出されたときに呼び出されます

  • onSuccess: リクエストが完了し、そのステータ・スコードが 2xy ファミリに属しているときに呼び出されます。 これは、コード固有のコールバックが定義されている場合にはスキップされ、onComplete の前に発生します。 レスポンス・オブジェクトを第1引数として受け取ります

  • onFailure: リクエストが完了し、ステータス・コードは存在しても、2xy ファミリにないときに呼び出されます。 これは、コード固有のコールバックが定義されている場合にはスキップされ、onComplete の前に発生します。 レスポンス・オブジェクトを第1引数として受け取ります
  • onXYZ (任意の HTTP ステータス・コードを表す XYZ): ステータス・コードがコールバック名で使用されたコードと 完全に一致する場合、レスポンスが完了した直後に呼び出されます。onSuccess と onFailure の実行を防ぎます。 onComplete の前に発生します。レスポンス・オブジェクトを第1引数として受け取ります
  • onComplete: リクエストのライフサイクルの最後にトリガされ、リクエストが完了した後、ステータス固有の コールバックが呼び出され、可能な自動ビヘイビアが処理されます。リクエスト中に何が起きたかにかかわらず、 実行が保証されます。レスポンス・オブジェクトを第1引数として受け取ります
  • onException: onXYZ, onSuccess, onFailure, onComplete コールバックのいずれかを実行して例外が 発生するたびにトリガされます。リクエストを第1引数として受け取り、例外オブジェクトを第2引数として受け取ります
  • onProgress: リクエスト時にこれまでに行われた進捗量を示すために定期的にトリガーされます
  • onUploadProgress: アップロード時にこれまでに行われた進捗量を示すために定期的にトリガーされます

リクエスト・オブジェクト

MashupPlatform.http.makeRequest メソッドによって返されたリクエスト・オブジェクトは、次の属性を提供します :

  • method (string): "GET", "POST", "PUT", "DELETE" など、リクエストによって使用される HTTP メソッド
  • url (string): リクエストが送信された最終的な URL

そして、次のメソッド :

  • abort(): すでにリクエストが送信されている場合は、リクエストを中止します
  • catch(onRejected[, onAborted]): Request.then() の onAborted パラメータをサポートする Promise.catch と同等です
  • finally(onFinally): Promise.finally() と同等、アボート・イベントもキャッチ
  • then(onFulfilled[, onRejected, onAborted]): Promise.then と同等のメソッドで、Request オブジェクトを Promise 互換にします。onFulfilled は、サーバから完全なレスポンスを正常に受信した直後に呼び出されます。サーバへの接続に問題が ある場合、またはブラウザがレスポンスの読み取りに何らかの制限を課す場合、onRejected が呼び出されます。最後に、この メソッドは、リクエストがアボートしたときに呼び出されるハンドラを設定するための追加の onAborted パラメータをサポート します

レスポンス・オブジェクト

MashupPlatform.http.makeRequest メソッドで使用されるコールバックに渡されるレスポンス・オブジェクトは、 次の属性を提供します :

  • request (Request): 現在のレスポンスのリクエスト
  • status (number): リクエストに対するレスポンスのステータス。これは HTTP の結果コードです
  • statusText (string): HTTP サーバから返されるレスポンス文字列。ステータスとは異なり、 これにはレスポンス・メッセージのテキスト全体が含まれます
  • response (ArrayBuffer, Blob, Document, object, String): responseType に応じた レスポンス・エンティティ・ボディを ArrayBuffer, Blob, String として返します。リクエストが完了していない、 または、成功しなかった、リクエストの responseType オプションが "" だった場合、これは null です
  • responseText (string): リクエストが失敗した場合、または、リクエストの responseType オプションが "" と異なる場合、text としてリクエストにレスポンスするか、または null です
  • responseXML (Document): リクエストが失敗した場合、または XML または HTML として解析できない場合、 Document としてのリクエストにレスポンスするか、または null です。レスポンスは、あたかも text/xml ストリームであるかのように解析されます。responseType が "" と異なる場合、この属性は使用できません。

MashupPlatform.log

このモジュールには以下の定数が含まれています :

  • ERROR: : エラーレベルを示すために使用します
  • WARN: : 警告レベルを示すために使用されます
  • INFO: : Infoレベルを示すために使用されます

これらの定数は、MashupPlatform.widget.log と MashupPlatform.operator.log メソッドを呼び出すときに使用できます。

MashupPlatform.prefs

このモジュールは、マッシブル・アプリケーション・コンポーネントのディスクリプション・ファイル(config.xml ファイル) で定義されたプレファレンスを管理するためのメソッドを提供します。

現在、このモジュールは3つの方法を提供しています :

1つの例外 :

MashupPlatform.prefs.get メソッド

このメソッドは、プリファレンスの値を取得します。このメソッドによって返される値のタイプは、プリファレンスのタイプに よって異なります。

MashupPlatform.prefs.get(key)
  • key (required, string): config.xml ファイルに定義されているプリファレンスの名前

このメソッドは、次の例外を発生させる可能性があります :

  • MashupPlatform.prefs.PreferenceDoesNotExistError

使用例 :

MashupPlatform.prefs.get("boolean-pref"); // true or false
MashupPlatform.prefs.get("number-prefs"); // a number value
MashupPlatform.prefs.get("text-prefs");   // a string value

MashupPlatform.prefs.registerCallback メソッド

このメソッドは、プリファレンスの変更を待機するコールバックを登録します。

MashupPlatform.prefs.registerCallback(callback)
  • 1つ以上のプレファレンスの変化が検出されたときに呼び出される callback 関数。このコールバックは、変更された プリファレンスとその新しい値を持つ Key-Value オブジェクトを受け取ります。

使用例 :

MashupPlatform.prefs.registerCallback(function(new_values) {
    if ("some-pref" in new_values) {
        // some-pref has been changed
        // new_values["some-pref"] contains the new value
    }
});

MashupPlatform.prefs.set メソッド

このメソッドは、プレファレンスの値を設定します。

MashupPlatform.prefs.set(key, value)
  • key (required, string): config.xml ファイルに定義されているプリファレンスの名前
  • value (required, any): プリファレンスの新しい値。このパラメータの許容値は、プリファレンスのタイプに依存します

このメソッドは、次の例外を発生させる可能性があります :

  • MashupPlatform.prefs.PreferenceDoesNotExistError

使用例 :

MashupPlatform.prefs.set("boolean-pref", true);

MashupPlatform.prefs.PreferenceDoesNotExistError 例外

この例外は、プリファレンスが見つからない場合に発生します。

MashupPlatform.prefs.PreferenceDoesNotExistError

MashupPlatform.mashup

マッシュアップ・モジュールには1つの属性が含まれています :

次の方法があります :

MashupPlatform.mashup.context 属性

この属性には、マッシュアップのコンテキスト・マネージャが含まれます。詳細については、 コンテキスト・マネージャに関するドキュメント を参照してください。

MashupPlatform.mashup.context

使用例 :

MashupPlatform.mashup.context.get("title");

MashupPlatform.mashup.addWidget メソッド

WireCloud 0.8.0 の新機能 / Widget API v2

このメソッドにより、ウィジェットおよびオペレータは、新しい一時的なウィジェットを現在のワークスペースに追加することが できます。

このメソッドは、DashboardManagement 機能を使用する場合にのみ使用できます。

MashupPlatform.mashup.addWidget(widget_ref, options);
  • widget_ref (required, string): 使用するウィジェットのid (ベンダー/名前/バージョン)
  • options (optional, object): 追加のオプションを持つオブジェクト

サポートされるオプション :

  • title (string): ウィジェットのタイトル。提供されていない場合、ウィジェットの説明で提供されるデフォルトの タイトルが使用されます
  • permissions (object): ウィジェットに適用する権限を持つオブジェクト。現在、次の権限が用意されています : close, configure, minimize, move, resize と upgrade
  • preferences (object): プレファレンスの初期設定を持つオブジェクト。指定されていない場合は、ウィジェットの デフォルト設定が使用されます
  • properties (object): プロパティの初期設定を持つオブジェクト。指定されていない場合は、ウィジェットの デフォルト設定が使用されます
  • refposition (ClientRect): 新しいウィジェットを配置するためのリファレンスとして使用する要素の位置。 getBoundingClientRect メソッドを使用してそのようなオブジェクトを取得することができます。このオプションは、オペレータからの addWidget メソッドを使用する場合は使用できません
  • top (string, default: 0px): このオプションは、要素の上端とダッシュボードの上端の間の距離を指定します。 refpositionオプションに値を指定すると、この値は無視されます
  • left (string, default: 0px): このオプションは、エレメントの左マージン・エッジとダッシュボードの上端との間の 距離を指定します。refposition オプションに値を指定すると、この値は無視されます
  • width (string, default: null): このオプションは、ウィジェットの幅を指定します。指定されていない場合、 デフォルトの幅が使用されます
  • height (string, default: null): このオプションは、ウィジェットの高さを指定します。指定されていない場合、 デフォルトの高さが使用されます

使用例 :

var widget = MashupPlatform.mashup.addWidget("CoNWeT/kurento-one2one/1.0", {
    "permissions": {
        "close": false,
        "configure": false
    },
    "preferences": {
        "stand-alone": {
            "value": false
        }
    },
    "top": "0px",
    "left": "66%"
});

MashupPlatform.mashup.addOperator メソッド

WireCloud 0.8.0 の新機能 / Widget API v2

このメソッドにより、ウィジェットおよびオペレータは、新しい一時的なオペレータを現在の作業領域に追加できます。

このメソッドは、DashboardManagement 機能を使用する場合にのみ使用できます。

MashupPlatform.mashup.addOperator(operator_ref, options);
  • operator_ref (required, string): 使用するオペレータのid (ベンダー/名前/バージョン)
  • options (optional, object): 追加のオプションを持つオブジェクト

サポートされるオプション :

  • permissions (object): オペレータに適用する権限を持つオブジェクト。現在、以下の権限が利用できます : close,configure および upgrade
  • preferences (object): プレファレンスの初期設定を持つオブジェクト。指定されていない場合は、オペレータの デフォルト設定が使用されます

使用例 :

var operator = MashupPlatform.mashup.addOperator("CoNWeT/ngsientity2poi/3.0.3", {
    "preferences": {
        "coordinates_attr": {
            "value": "current_position"
        }
    }
});

MashupPlatform.mashup.createWorkspace メソッド

WireCloud 0.8.0 の新機能 / Widget API v2

このメソッドにより、ウィジェットおよびオペレータは、現在のユーザの新しいワークスペースを作成できます。このメソッドは 非同期です。

このメソッドは、DashboardManagement 機能を使用する場合にのみ使用できます。

MashupPlatform.mashup.createWorkspace(options)
  • options (required, object): ワークスペースの作成に使用するオプションを持つオブジェクト。次のオプションの うちの少なくとも一方が提供されなければなりません : name, mashup, workspace

サポートされるオプション :

  • name (string): 新しいワークスペースの名前。mashup と workspace のどちらのオプションも使用しない場合、 このオプションは必須です。提供されていない場合、マッシュアップの名前はマッシュアップまたはワークスペースから 取り込まれ、テンプレートとして使用されます
  • mashup (string): 新しいワークスペースを作成するためのテンプレートとして使用するマッシュアップの id (ベンダー/名前/バージョン)。mashup 属性と workspace 属性の両方はオプションですが、一緒に指定することは できません
  • workspace (string): 新しいワークスペースを作成するためのテンプレートとして使用するワークスペースのid (所有者/名前)。 mashup 属性と workspace 属性の両方はオプションですが、一緒に指定することはできません
  • allowrenaming (boolean, default false): このオプションが true の場合、同じ名前のワークスペースがすでに 存在する場合、Application Mashup Server はワークスペースの名前を変更します
  • preferences (object): ワークスペース・プレファレンスの初期値を持つオブジェクト。指定されていない場合、 デフォルト値が使用されます
  • onSuccess (function): ワークスペースが正常に作成された場合に呼ばれるコールバック
  • onFailure (function): ワークスペースの作成中に何らかのエラーが発生した場合に呼ばれるコールバック

使用例 :

MashupPlatform.mashup.createWorkspace({
    name: "New workspace",
    mashup: "CoNWeT/ckan-graph-mashup/1.0",
    onSuccess: function(workspace) {
        alert(workspace.owner + "/" + workspace.name + " created successfully");
    }
});

MashupPlatform.mashup.openWorkspace メソッド

WireCloud 1.0.0 の新機能 / Widget API v3

このメソッドにより、ウィジェットおよびオペレータは現在の作業領域を切り替えることができます。このメソッドは非同期です。

このメソッドは、DashboardManagement 機能を使用する場合にのみ使用できます。

MashupPlatform.mashup.openWorkspace(workspace, options);
  • workspace (required, object): 次の属性で構成されるオブジェクト :
    • owner (required, string): ワークスペースの所有者のユーザ名
    • name (required, string): ワークスペースの名前
  • options (object): ワークスペースを開くために使用するオプションを持つオブジェクト

サポートされるオプション :

  • onFailure (function): ワークスペースを開いているときに何らかのエラーが発生した場合に呼ばれるコールバック

使用例 :

MashupPlatform.mashup.openWorkspace({
    owner: "wirecloud",
    name: "home"
});

MashupPlatform.mashup.removeWorkspace メソッド

WireCloud 1.0.0 の新機能 / Widget API v3

このメソッドにより、ウィジェットおよびオペレータはワークスペースを削除できます。このメソッドは非同期です。

このメソッドは、DashboardManagement 機能を使用する場合にのみ使用できます。

MashupPlatform.mashup.removeWorkspace(workspace, options);
  • workspace (required, object): 次の属性で構成されるオブジェクト :
    • owner (required, string): ワークスペースの所有者のユーザ名
    • name (required, string): ワークスペースの名前
  • options (object): ワークスペースの削除に使用するオプションを持つオブジェクト

サポートされるオプション :

  • onSuccess (function): ワークスペースが正常に削除された場合に呼ばれるコールバック
  • onFailure (function): ワークスペースを削除しているときに何らかのエラーが発生した場合に呼ばれるコールバック

使用例 :

MashupPlatform.mashup.removeWorkspace({
    owner: "user",
    name: "workspace"
});

MashupPlatform.operator

このモジュールは、オペレータの中で実行されている場合にのみ使用できます。現在、Widget API には次の属性があります。

そして、3つのメソッド :

MashupPlatform.operator.id 属性

この属性には、オペレータの id が含まれます。

MashupPlatform.operator.id

MashupPlatform.operator.context 属性

この属性には、オペレータのコンテキスト・マネージャが含まれます。詳細については、 コンテキスト・マネージャに関するドキュメントを参照してください。

MashupPlatform.operator.context;

使用例 :

MashupPlatform.operator.context.get("version");

MashupPlatform.operator.inputs 属性

WireCloud 0.8.0 の新機能 / Widget API v2

入力エンドポイントの名前をキーとして使用するオペレータの入力エンドポイントを指定します。

MashupPlatform.operator.inputs;

MashupPlatform.operator.outputs 属性

WireCloud 0.8.0 の新機能 / Widget API v2

オペレータの入力エンドポイントを指定して、出力エンドポイントの名前をキーとして使用します。

MashupPlatform.operator.outputs;

MashupPlatform.operator.createInputEndpoint メソッド

WireCloud 0.8.0 の新機能 / Widget API v2

このメソッドは、動的入力エンドポイントを作成します。

このメソッドは、DashboardManagement 機能を使用する場合にのみ使用できます。

MashupPlatform.operator.createInputEndpoint(callback);
  • callback (required, function): イベントが入力エンドポイントに到着したときに呼び出される関数

使用例 :

MashupPlatform.operator.createInputEndpoint(function(data_string) {
    var data = JSON.parse(data_string);
    ...
});

MashupPlatform.operator.createOutputEndpoint メソッド

WireCloud 0.8.0 の新機能 / Widget API v2

このメソッドは、動的出力エンドポイントを作成します。

このメソッドは、DashboardManagement 機能を使用する場合にのみ使用できます。

MashupPlatform.operator.createOutputEndpoint();

使用例 :

var endpoint = MashupPlatform.operator.createOutputEndpoint();
...
endpoint.pushEvent("event data");

MashupPlatform.operator.log メソッド

このメソッドは、アプリケーション・マッシュアップのログ・コンソールにメッセージを書き込みます。

MashupPlatform.operator.log(msg, level);
  • msg (required, string): ログに記録するメッセージのテキストです
  • level (optional, default: MashupPlatform.log.ERROR): このオプションのパラメータは、メッセージをログする ために使用するレベルを指定します。使用可能なログレベルについては、MashupPlatform.log を参照してください

使用例 :

MashupPlatform.operator.log("error message description");
MashupPlatform.operator.log("info message description", MashupPlatform.log.INFO);

MashupPlatform.widget

このモジュールは、ウィジェット内で実行されている場合にのみ使用できます。現在、Widget API には次の属性があります :

そいて、次のメソッドがあります :

MashupPlatform.widget.id 属性

この属性には、ウィジェットの id が含まれます。

MashupPlatform.widget.id;

MashupPlatform.widget.context 属性

この属性には、ウィジェットのコンテキスト・マネージャが含まれます。詳細については、 コンテキスト・マネージャに関するドキュメントを参照してください。

MashupPlatform.widget.context;

使用例 :

MashupPlatform.widget.context.get("version");

MashupPlatform.widget.inputs 属性

WireCloud 0.8.0 の新機能 / Widget API v2

入力エンドポイントの名前をキーとして使用して、ウィジェットの入力エンドポイントを指定します。

MashupPlatform.widget.inputs;

MashupPlatform.widget.outputs 属性

WireCloud 0.8.0 の新機能 / Widget API v2

出力エンドポイントの名前をキーとして使用して、ウィジェットの入力エンドポイントを指定します。

MashupPlatform.widget.outputs;

MashupPlatform.widget.createInputEndpoint メソッド

WireCloud 0.8.0 の新機能 / Widget API v2

このメソッドは、動的入力エンドポイントを作成します。

このメソッドは、DashboardManagement 機能を使用する場合にのみ使用できます。

MashupPlatform.widget.createInputEndpoint(callback);
  • callback (required, function): イベントが入力エンドポイントに到着したときに呼び出される関数

使用例 :

MashupPlatform.widget.createInputEndpoint(function(data_string) {
    var data = JSON.parse(data_string);
    ...
});

MashupPlatform.widget.createOutputEndpoint メソッド

WireCloud 0.8.0 の新機能 / Widget API v2

このメソッドは、動的出力エンドポイントを作成します。

このメソッドは、DashboardManagement 機能を使用する場合にのみ使用できます。

MashupPlatform.widget.createOutputEndpoint();

使用例 :

var endpoint = MashupPlatform.widget.createOutputEndpoint();
...
endpoint.pushEvent("event data");

MashupPlatform.widget.getVariable メソッド

ウィジェット変数をその名前で返します。

MashupPlatform.widget.getVariable(name);
  • name (required, string): config.xml ファイルに定義されている永続変数の名前

使用例 :

var variable = MashupPlatform.widget.getVariable("persistent-var");
variable.set(JSON.stringify(data));

MashupPlatform.widget.drawAttention メソッド

アプリケーション・マッシュアップ・エンジンは、ウィジェットにユーザの注意が必要であることを通知します。

MashupPlatform.widget.drawAttention()

MashupPlatform.widget.log メソッド

Application Mashup のログ・コンソールにメッセージを書き込みます。

MashupPlatform.widget.log(msg, level);
  • msg (required, string): ログに記録するメッセージのテキストです
  • level (optional, default: MashupPlatform.log.ERROR): このオプションのパラメータは、メッセージをログする ために使用するレベルを指定します。使用可能なログレベルについては、MashupPlatform.log を参照してください

使用例 :

MashupPlatform.widget.log("error message description");
MashupPlatform.widget.log("warning message description", MashupPlatform.log.WARN);

MashupPlatform.wiring

このモジュールは、ウィジェット間の通信を処理するためのいくつかの方法を提供します。

現在、このモジュールは5つの方法で構成されています :

そして、3つの例外があります :

MashupPlatform.wiring.hasInputConnections メソッド

WireCloud 0.8.0 の新機能 / Widget API v2

ワイヤーリングを介してイベントを送信します。

MashupPlatform.wiring.hasInputConnections(inputName);
  • inputName (required, string): 接続がある場合にクエリする入力エンドポイントの名前

このメソッドは、次の例外を発生させる可能性があります :

  • MashupPlatform.wiring.EndpointDoesNotExistError

使用例 :

MashupPlatform.wiring.hasInputConnections("inputendpoint");

MashupPlatform.wiring.hasOutputConnections メソッド

WireCloud 0.8.0 の新機能 / Widget API v2

ワイヤーリングを介してイベントを送信します。

MashupPlatform.wiring.hasOutputConnections(outputName);
  • outputName (required, string): 接続がある場合にクエリする出力エンドポイントの名前

このメソッドは、次の例外を発生させる可能性があります :

  • MashupPlatform.wiring.EndpointDoesNotExistError

使用例 :

MashupPlatform.wiring.hasOutputConnections("outputendpoint");

MashupPlatform.wiring.pushEvent メソッド

ワイヤーリングを介してイベントを送信します。

MashupPlatform.wiring.pushEvent(outputName, data);
  • outputName (required, string): イベントの送信に使用する出力エンドポイントの名前
  • data (required, any): 送信するデータ

このメソッドは、次の例外を発生させる可能性があります :

  • MashupPlatform.wiring.EndpointDoesNotExistError

使用例 :

MashupPlatform.wiring.pushEvent("outputendpoint", "event data");

MashupPlatform.wiring.registerCallback メソッド

指定された入力エンドポイントのコールバックを登録します。指定されたエンドポイントが既にコールバックを登録している場合、 それは新しいものに置き換えられます。

MashupPlatform.wiring.registerCallback(inputName, callback);
  • inputName (required, string): コールバック関数が登録される入力エンドポイントの名前
  • callback (required, function): イベントが入力エンドポイントに到着したときに呼び出される関数

このメソッドは、次の例外を発生させる可能性があります :

  • MashupPlatform.wiring.EndpointDoesNotExistError

使用例 :

MashupPlatform.wiring.registerCallback("inputendpoint", function(data_string) {
    var data = JSON.parse(data_string);
    ...
});

MashupPlatform.wiring.registerStatusCallback メソッド

WireCloud 0.8.0 の新機能 / Widget API v2

Widget API を使用して行われた変更を除いて、マッシュアップのワイヤーリング状態が変更されるたびに呼び出される コールバックを登録します。

MashupPlatform.wiring.registerStatusCallback(callback);
  • callback (required, function): ワイヤーリング設定が変更されるたびに呼び出される機能

使用例 :

MashupPlatform.wiring.registerStatusCallback(function() {
    ...
});

MashupPlatform.wiring.EndpointDoesNotExistError 例外

この例外は、入出力エンドポイントが見つからない場合に発生します。

MashupPlatform.wiring.EndpointDoesNotExistError;

MashupPlatform.wiring.EndpointTypeError 例外

WireCloud 0.8.0 の新機能 / Widget API v2

ウィジェット/オペレータは、入力エンドポイントに到着するデータが期待されるタイプではないことを検出すると、 この例外をスローできます。

MashupPlatform.wiring.EndpointTypeError(message);
  • message (required, string): 例外を説明するメッセージテキスト

使用例 :

MashupPlatform.wiring.registerCallback("inputendpoint", function(data) {
    try {
        data = JSON.parse(data);
    } catch (error) {
        throw new MashupPlatform.wiring.EndpointTypeError("data should be encoded as JSON");
    }

    ...
});

MashupPlatform.wiring.EndpointValueError 例外

WireCloud 0.8.0 の新機能 / Widget API v2

ウィジェット/オペレータは、適切なタイプを持っていても入力エンドポイントに到着するデータに不適切な値が含まれている ことを検出すると、この例外をスローできます。

MashupPlatform.wiring.EndpointValueError(message);
  • message (required, string): 例外を説明するメッセージテキスト

使用例 :

MashupPlatform.wiring.registerCallback("inputendpoint", function(data) {
    ...

    if (data.level > 4 || data.level < 0) {
        throw new MashupPlatform.wiring.EndpointValueError("level out of range");
    }

    ...
});

エンドポイント・インスタンス

WireCloud 0.8.0 の新機能 / Widget API v2

エンドポイント・インスタンスは1つの属性を提供します :

エンドポイントのタイプに応じて、以下のメソッドがあります :

Endpoint.connected 属性

この属性は、関連付けられたエンドポイントに少なくとも1つの接続があるかどうかを示します。

Endpoint.connected;

使用例 :

if (MashupPlatform.widget.inputs.source.connected) {
    $("#alert").hide();
} else {
    $("#alert").show();
}

Endpoint.connect メソッド

このメソッドは、インスタンスに関連付けられたエンドポイントとパラメータとして渡されたエンドポイントの間の接続を 確立します。

Endpoint.connect(endpoint);
  • endpoint (required, Endpoint): 接続のもう一方の端に接続する入出力エンドポイント

使用例 :

var operator = MashupPlatform.mashup.addOperator("CoNWeT/ngsientity2poi/3.0.3", ...);
var widget = MashupPlatform.mashup.addWidget("CoNWeT/map-viewer/2.5.7", ...);

MashupPlatform.widget.outputs.entity.connect(operator.inputs.entityInput);
operator.outputs.poiOutput.connect(widget.inputs.poiInput);

Endpoint.disconnect メソッド

WireCloud 1.0 / Widget API v2 の新機能

このエンドポイントで開始または終了する動的接続を削除します。このメソッドは、ワイヤーリング・エディタを使用して ユーザが作成した接続の切断には使用できません。

Endpoint.disconnect(endpoint);
  • endpoint (optional, Endpoint): 削除する接続の反対側のエンドポイント。endpoint が null の場合、 このエンドポイントに関連するすべての動的な接続が切断されます

使用例 :

var operator = MashupPlatform.mashup.addOperator("CoNWeT/ngsientity2poi/3.0.3", ...);
var widget = MashupPlatform.mashup.addWidget("CoNWeT/map-viewer/2.5.7", ...);

MashupPlatform.widget.outputs.entity.connect(operator.inputs.entityInput);
operator.outputs.poiOutput.connect(widget.inputs.poiInput);

...

MashupPlatform.widget.outputs.entity.disconnect(operator.inputs.entityInput);
operator.outputs.poiOutput.disconnect(widget.inputs.poiInput);

Endpoint.pushEvent メソッド

ワイヤーリングを介してイベントを送信します。

出力エンドポイントでのみ使用できます。

Endpoint.pushEvent(data);
  • data (required, any): 送信するデータ

使用例 :

MashupPlatform.widget.outputs.entity.pushEvent("event data");

ウィジェット・インスタンス

WireCloud 0.8.0 の新機能 / Widget API v2

MashupPlatform.mashup.addWidget メソッドを使用して取得された ウィジェットのインスタンスは、次の属性を提供します :

そして、次のメソッド :

Widget.inputs 属性

入力エンドポイントの名前をキーとして使用して、ウィジェットの入力エンドポイントを指定します。

Widget.inputs;

Widget.outputs 属性

出力エンドポイントの名前をキーとして使用して、ウィジェットの入力エンドポイントを指定します。

Widget.outputs;

Widget.addEventListener メソッド

このメソッドは、呼び出された Widget のリスナーに指定されたリスナーを登録します。

Widget.addEventListener(name, handler);
  • name (required, string): 待機するイベントの名前
  • listener (required, function): 指定されたタイプのイベントがウィジェットによって発生されたときに呼び出される関数

使用例 :

var widget = MashupPlatform.mashup.addWidget(...);
....
widget.addEventListener("close", onWidgetClose);

Widget.remove メソッド

このメソッドは、ワークスペースからウィジェットを削除します。ウィジェットを削除する前に、このウィジェットを含む ワイヤーリング接続が切断されます。

Widget.remove();

使用例 :

var widget = MashupPlatform.mashup.addWidget(...);
....
widget.remove();

ワークスペース・インスタンス

WireCloud 1.0.0の新機能/ Widget API v3

MashupPlatform.mashup.createWorkspace メソッドを使用して取得されワークスペースのインスタンスには、 次の属性があります :

そして、次のメソッドがあります :

Workspace.name 属性

ワークスペースの名前の文字列。

Workspace.name;

Workspace.owner 属性

ワークスペースの所有者のユーザ名を含む文字列。

Workspace.owner

Workspace.open メソッド

WireCloud 1.0.0 の新機能 / Widget API v3

このメソッドはワークスペースを開き、現在のワークスペースを閉じます。

Workspace.open(options);
  • options (object): ワークスペースを開くために使用するオプションを持つオブジェクト

サポートされるオプション :

  • onFailure (function): ワークスペースを開いているときに何らかのエラーが発生した場合に呼び出すコールバック

使用例 :

MashupPlatform.mashup.createWorkspace({
    ...,
    onSuccess: function(workspace) {
        workspace.open();
    }
);

Workspace.remove メソッド

WireCloud 1.0.0 の新機能 / Widget API v3

このメソッドは、ワークスペースを削除します。

Workspace.remove(options);
  • options (object): ワークスペースの削除に使用するオプションを持つオブジェクト

サポートされるオプション :

  • onSuccess (function): ワークスペースが正常に削除された場合に呼び出すコールバック
  • onFailure (function): ワークスペースを削除しているときに何らかのエラーが発生した場合に呼ばれるすコールバック

使用例 :

var myWorkspace;

MashupPlatform.mashup.createWorkspace({
    ...,
    onSuccess: function(workspace) {
        myWorkspace = workspace;
    }
);

...

myWorkspace.remove();

オペレータ・インスタンス

new in WireCloud 0.8.0 / Widget API v2

MashupPlatform.mashup.addOperator メソッドを使用して取得したオペレータ・インスタンスには、次の属性があります :

そして、次のメソッド :

Operator.inputs 属性

入力エンドポイントの名前をキーとして使用するオペレータの入力エンドポイントを指定します。

Operator.inputs;

Operator.outputs 属性

オペレータの入力エンドポイントを指定して、出力エンドポイントの名前をキーとして使用します。

Operator.outputs;

Operator.addEventListener メソッド

このメソッドは、呼び出されたオペレータのリスナーに指定されたリスナーを登録します。

Operator.addEventListener(name, handler);
  • name (required, string): 待機するイベントの名前
  • listener (required, function): 指定されたタイプのイベントがオペレータによって発生したときに呼び出される関数

使用例 :

var operator = MashupPlatform.mashup.addOperator(...);
....
operator.addEventListener("close", onOperatorClose);

Operator.remove メソッド

このメソッドは、作業領域からオペレータを削除します。オペレータを取り外す前に、このオペレータに関係するワイヤーリング 接続を切断します。

Operator.remove();

使用例 :

var operator = MashupPlatform.mashup.addOperator(...);
....
operator.remove();

コンテキスト・マネージャ

各コンテキスト・マネージャは、3つのメソッドをサポートしています :

ContextManager.getAvailableContext メソッド

このメソッドは、指定されたレベルで使用できるコンセプトについての情報を提供します。

ContextManager.getAvailableContext();

使用例 :

MashupPlatform.context.getAvailableContext();

ContextManager.get メソッド

コンセプトの現在の値を取得します。

ContextManager.get(key);
  • key (required, string): name of the concept to query.

使用例 :

MashupPlatform.widget.context.get("heightInPixels");
MashupPlatform.mashup.context.get("name");
MashupPlatform.context.get("username");

ContextManager.registerCallback メソッド

いずれかのコンセプトが変更されたときに呼び出されるコールバックを登録できます。

ContextManager.registerCallback(callback);
  • callback (required, function): コンテキスト・マネージャが管理するコンテキスト情報が変更されるたびに 呼び出される関数

使用例 :

MashupPlatform.widget.context.registerCallback(function(new_values) {
    if ("some-context-concept" in new_values) {
        // some-context-concept has been changed
        // new_values["some-context-concept"] contains the new value
    }
});

謝辞

編集者はこの仕様に積極的に貢献した以下の人々に感謝の意を表します : Aitor Magan と Francisco de la Vega

参考文献