|
|
WebLogic Portal は、ポータル データをクライアントから動的に取得、変更、および更新するために Web ベースの REST スタイル API セットを提供します。この章では、WLP REST API およびその使用例とサンプルについて説明します。
| ヒント : | 各 WLP REST コマンドの詳細については、「WLP REST API リファレンス」を参照してください。 |
REST (REpresentational State Transfer) は、URL で特定の資源が利用できるようにするサービスを構築する方法です。REST サービスには、リソースを操作するために明確に定義されたオペレーションがあります。通常、これらのオペレーションには、読み込み、書き込み、編集、および削除が含まれます。WLP の場合は、リソースはポートレット、ページまたはブックであることがあります。たとえば、以下の WLP REST コマンドで特定の Web アプリケーションのポートレット リストが取得できます。
http://localhost:7001/myWebApp/bea/wlp/api/portlet/list?webapp=myWebApp
| ヒント : | REST の詳細については、http://en.wikipedia.org/wiki/Representational_State_Transfer で「Representational State Transfer」を参照してください。 |
WLP REST API は、「ポートレット リストの取得」、「ページのブックへの追加」などの簡単な使用例に焦点を当てます。WLP REST API は、REST API の一般的なパターンに従うことで、ポータル アーティファクトを読み込む、作成、更新、および削除するコマンドを提供します。たとえば、ポートレットのリスト、追加、更新および削除のための WLP REST コマンドが存在します。これらの REST コマンドの結果は WLP のカスタマイズ フレームワークを通じて持続されます。この章で説明した REST コマンドは、ポートレットの表示を目的としません。
| 注意 : | REST API コマンドのいくつかはストリーミング ポータルのみで機能します。通常、ストリーミング ポータルは、Portal Administration Console を使用してコンフィグレーションされたポータルです。詳細については、「ファイルベース ポータルとストリーミング ポータル」を参照してください。 |
「REST API マニュアル」は e-docs から入手できます。
現在、WLP REST コマンドでは、WLP の訪問者のカスタマイズ機能をサポートするために WLP データへのアクセスが提供されます。ブラウザ ベースのツールはこれらのコマンドでユーザのデスクトップと対話して、更新できます。たとえば、REST コマンドは、配置の動作機能だけではなく、Dynamic Visitor Tool サンプル アプリケーション (Dynamic Visitor Tools サンプルを参照) でも幅広く使用されます。これらのコマンドを使用して、ポートレットのページへの追加、削除およびページ上のポートレットの移動できます。つまり、WLP REST コマンドは、Web サービスアプローチの代用
となるより自然で使いやすい方法です。
| 注意 : | 一部の REST コマンドはデスクトップ上で現在表示されないもののみ返します。たとえば、これによって、ユーザがデスクトップにすでに追加されているポートレットのリストを表示したくない場合の使用例がサポートされます。 |
<protocol>://<host>:<port>/<webapp>/bea/wlp/api/<type>/<action>/<label>?<params>
表 7-1 では、WLP REST コマンドの構成要素について説明します。
各 REST コマンドでは、e-docs の「REST API リファレンス マニュアル」にリストしているパラメータが入力できます。この節で、一般に使用される 3 つのパラメータについて詳細に説明します。
webapp パラメータが常に必要です。REST コマンドが呼び出す Web アプリケーションの名前を指定します。指定した EAR に 1 つ以上の Web アプリケーションがデプロイされている場合、このパラメータでそのアプリケーションを切り替えることができます。パラメータで指定した Web アプリケーションは、ポストしている Web アプリケーション (ベース URL で指定したアプリケーション) と異なることがあります。
たとえば、以下のコマンドでは、myWebApp はコマンドを受信するアプリケーションであり、yourWebApp アプリケーションに対してポートレット リストが取得されます。両方の Web アプリケーションが同じ EAR でデプロイされる必要があります。
http://localhost:7001/myWebApp/bea/wlp/api/portlet/list?webapp=yourWebApp
形式パラメータは、xml または json のいずれかになります。デフォルトは xml です。JSON は JavaScript のオブジェクト表記法であり、JavaScript のあるブラウザ環境において使いやすいです。詳細については、「JSON」を参照してください。次に例を示します。
http://localhost:7001/myWebApp/bea/wlp/api/portlet/list?webapp=yourWebApp&format=json
スコープ パラメータにより、一部の REST コマンドを微調整できます。このパラメータは取得されたデータおよび更新されたデータに影響を与えます。スコープ パラメータでは、以下の 3 つの値のいずれかを入力できます。
| 注意 : | スコープを指定しない場合は、通常の非特権ユーザのためにデフォルト値は訪問者です。ただし、ユーザは管理者権限がある場合、デフォルト値がセッションから読み込まれます。adminscope REST コマンドを使用して、この値を設定できます。 |
図 7-2 は、ポータル アプリケーション内のスコープの階層、伝達される変更の方向、およびさまざまなレベルで変更を加えるために通常に使用されるツールを示します。
scope パラメータの値が visitor に設定される場合、パーミッションがあるユーザは任意にユーザ名を指定できます。WLS 管理者、WLP 管理者、およびコミュニティ リーダーは他のユーザのデスクトップに変更を加えることができますが、通常のユーザは独自のデスクトップのみを変更できます。
/bea/wlp/api/adminscope/item?webapp=mywebapp&portal=portalpath&desktop=
desktoppath&scope=visitor
このコマンドによって、HttpSession に特別なトークンが追加されます。個々のユーザはデスクトップのために要求をする場合、この同じトークンが使用されます。「weblogic」というユーザはデスクトップにログインする場合、フレームワークは、この値に応じてどのビューに戻すかを決定します。この値は admin である場合、デフォルト ビューに戻し、それ以外の場合、管理者の独自のビューに戻します。
| ヒント : | ベスト プラクティスは、セッションに格納される値に頼るではなく、常に scope パラメータを設定することです。セッションがどの時点でもタイムアウトするからです。 |
以下の REST コマンドは、2 つのポートレットのみある「myWeb」というポータル Web アプリケーションのポートレット リストを取得します。
http://localhost:7001/myWeb/bea/wlp/api/portlet/list?webapp=myWeb
コード リスト 7-1 は、この REST コマンドに返された XML データ (デフォルトのフォーマット) のタイプの例を示します。これらのポートレット情報 (ポートレット ラベルなど) を解析して、他の REST コマンド (ポートレットをページへ追加するコマンドなど) への入力として使用できます。
<rsp>
<portlet_summaries>
<portlet_summary>
<label>p1</label>
<title>Portlet One</title>
</portlet_summary>
<portlet_summary>
<label>p2</label>
<title>Portlet Two</title>
</portlet_summary>
</portlet_summaries>
</rsp>
| ヒント : | デフォルトでは、WLP REST コマンドによって XML フォーマットでデータが返されます。コマンドに format=json パラメータを追加することで、クライアントに XML オブジェクトの代わりに JSON (JavaScript Object Notation) オブジェクトを返すことができます。JSON 応答を JavaScript オブジェクトに変換するのは簡単です。データはオブジェクトの形に変換されたら、JavaScript で item.title と item.markupName のような見慣れたドット記法を使用して、値を反復と取得できます。「JSON」を参照してください。 |
wlp-restapi-config.xml コンフィグレーション ファイルを編集することにより、特定の REST コマンドを無効にすることができます。REST コマンドを無効にするには、次の手順に従います。
WEB-INF フォルダを開く。 wlp-restapi-config.xml を右クリックし、[プロジェクトにコピー] を選択する。これにより、ユーザは編集できるように、ファイルがライブラリ モジュールからプロジェクトにコピーされる。 <rest-handler>
<name>getPortlets</name>
<path>portlet/list</path>
<handler-class>com.bea.wlp.rest.portlet.command.GetPortlets
</handler-class>
<methods>
<method>
<name>get</name>
<enable>false</enable></method>
</methods>
</rest-handler>
この節では、WLP REST コマンドとそれらの応答の例について説明します。「Disc を使用したポータル情報の取得」を含む、さらに完全の高い例については、「REST と Disc の使用」を参照してください。
以下の REST コマンドによって、「banking」という Web アプリケーションから revenue_1 ラベルがある単一ポートレットの詳細が返されます。コード リスト 7-3 に、この結果を示します。
http://blaster:7041/banking/bea/wlp/api/portlet/details/revenue_1?webapp=dvt
<rsp>
<title>5 Largest Customers</title>
<content_uri>/portlets/revenue/index.jsp</content_uri>
<forkable>false</forkable>
<fork_render>false</fork_render>
<is_public>true</is_public>
<cacheable>false</cacheable>
<cache_expires>-1</cache_expires>
<portlet_file>/portlets/revenue/revenue.portlet</portlet_file>
<deleted>false</deleted>
<webapp>dvt</webapp>
<wsrp_user_properties_mode>3</wsrp_user_properties_mode>
<state_change_flag>0</state_change_flag>
<requires_url_templates>false</requires_url_templates>
<templates_stored_in_session>false</templates_stored_in_session>
<producer_offered_portlet>false</producer_offered_portlet>
<created_date>2007-10-31 15:54:19.0</created_date>
<modified_date>2007-10-31 15:54:19.0</modified_date>
</rsp>
| ヒント : | 同じコマンドでそれぞれのポータル アーティファクト (ページやブックなど) をクエリすることで、同様の情報を取得できます。適切なコマンド構文については、e-docs の『REST API リファレンス マニュアル』を参照してください。 |
ポータル データを更新する REST コマンドは、HTTP POST メソッドを必要とします。コード リスト 7-4 は、XMLHttpRequest.open メソッドを使用して、REST URL をポストする簡単なスクリプトを示します。
<script type="text/javascript">
var urlStem =
'http://localhost:7001/myWeb/bea/wlp/api/portlet/item/restTest_1';
var params = "webapp=myWeb&title=New Title";
var xmlhttp = new bea.wlp.disc.io.XMLHttpRequest();
var url = urlStem + "?" + params;
xmlhttp.open('POST', urlStem, true);
xmlhttp.send(params);
</script>
REST コマンドを使用して、オブジェクトを作成、削除、更新できます。以下に、ページ間でブックを移動する方法を説明します。
<protocol>://<hostname>:<port>/<webapp>/bea/wlp/api/<type>/<action>/<childtype>/<label>?webapp=<webapp>&format=<format>
childtype は、タイプで指定された、ラベルがあるオブジェクトの子です。たとえば、以下に示す URL でブック内にページを移動します。
http://mysite.com/flatweb/bea/wlp/api/book/move/bookorpage/mainbook_01
mainbook_01 は、ページが移動されるブックのラベルです。POST パラメータは以下のようになります。
webapp=flatweb
portal=flatirons
desktop=flatweb
scope=visitor
label=mypage
position=0
alignment=0
label は、移動するページのラベルで、position はブック内の移動先の位置です。スコープでは、「visitor」、「admin」、または「library」が指定できます。これによって、「admin」ユーザがデフォルト インスタンス、ライブラリ インスタンスなどに変更を加えることができます。
| 注意 : | DOM によって、変更が自動的に反映されない。ページを更新するために、クライアント側で DHTML を使用します。 |
REST コマンドは、単独で全ての使用例を満たすことができません。ポータル コンテキスト オブジェクトとそれらが含む情報を取得するには、Disc JavaScript API を使用する必要があります。後で、ポータルを更新する REST の呼び出しにこの情報を追加できます。たとえば、ポートレットを移動するには、Disc API を使用してポートレットの現在場所に関する情報を取得し、その情報を REST の呼び出しに追加する必要があります。Disc フレームワークについては「WLP Disc フレームワーク」で説明します。
以下の節では、クライアント側のポータル開発での REST と Disc の使用に関する重要な概念について説明します。
以下の節では、「まとめ」に全体に示したサンプル JSP ポートレットのさまざまな部分について説明します。ポートレットでは、ドロップダウン リストから新しいレイアウトを選択して、ページのレイアウトを変更できます。このリストには、Disc API でポータルをクエリすることで入力します。ユーザの選択は、REST コマンドでサーバに通信されます。
Disc コンテキスト オブジェクトから取得される情報を使用して、ポータルを更新するために、REST API コマンドを呼び出すことができます。ほとんどの REST コマンドは、コンテキスト オブジェクトからのみ取得されるパラメータを必要とします。e-docs の「WLP REST API マニュアル」に REST コマンド パラメータのリストと説明をまとめます。
コード リスト 7-5 の関数は、Disc コンテキスト オブジェクトを使用して、ポータルから情報を取得します。この情報は REST コマンド パラメータを構成するのに使用されます。コードは簡単な JavaScript のことです。REST コマンドでは、ポートレット コンテキスト、ページ コンテキスト、ポータルのパース、デスクトップのパースなどのパラメータが必要です。パラメータが取得されたら、REST コマンドの URL が構造されます。
...
function ${uid}setLayout(layoutName) {
// 出力に使用するキャンバス要素を取得する
var canvas = document.getElementById("${uid}canvas");
// Disc からポートレット コンテキストを取得する
var portletContext = bea.wlp.disc.context.Portlet.findByElement(canvas);
// ポートレットの親ページ コンテキストを取得する
var pageContext = portletContext.getParentPage();
// Disc からアプリケーション インスタンスを取得する
var appContext = bea.wlp.disc.context.Application.getInstance();
// REST コマンドに渡すパラメータを作成する
var params = "";
params += "&portal=" + appContext.getPortalPath();
params += "&desktop=" + appContext.getDesktopPath();
params += "&webapp=" + appContext.getWebAppName();
params += "&layout=" + layoutName;
// ページ属性を変える REST コマンドの URL を構成する
var url = "/" + appContext.getWebAppName();
url += "/bea/wlp/api/page/item/" + pageContext.getLabel();
...
REST コマンドを送信するリクエストを構成した後は、そのコマンドをサーバに送信する必要があります。コマンドを送信し、結果を取得するには、XHR オブジェクトを使用することをお勧めします。
コード リスト 7-6 は、URL を使用することで XHR リクエストを開始し、パラメータ リストを送信するコードのサンプルを示します。コード リスト 7-5 で説明した同様のメソッドで URL とパラメータ リストを構造できます。
...
// Disc からポータル対応の XMLHttpRequest を取得する。
var xmlHttpReq = new bea.wlp.disc.io.XMLHttpRequest();
xmlHttpReq.onreadystatechange = function() {
if (xmlHttpReq.readyState == 4) {
if(xmlHttpReq.status == 200) {
var msg = "Layout changed to " + layoutName + ".\n\n";
msg += "Press OK to refresh desktop.";
if (confirm(msg)) {
window.location.reload();
}
} else {
alert("Unable to change layout.");
}
}
};
xmlHttpReq.open('POST', url, true);
xmlHttpReq.send(params);
}
...
一部の REST コマンドによって、単純なステータス応答が返されます。他のコマンドによって、ポートレットの詳細な情報などの追加データが返されます。コード リスト 7-7 のコード サンプルでは、REST コマンドからの応答データの処理方法を示します。このサンプルでは、応答はリクエストされた使用可能なポータル レイアウトのリストです。応答データは、リストを解析して、ドロップダウン メニューに表示する関数に渡されます。コード リスト 7-5 で前述したものと同様のメソッドで REST コマンドとそれらのパラメータを構造できます。
...
// Disc からアプリケーション インスタンスを取得する
var appContext = bea.wlp.disc.context.Application.getInstance();
// REST コマンド用のパラメータを構造する
var params = "";
params += "?portal=" + appContext.getPortalPath();
params += "&desktop=" + appContext.getDesktopPath();
params += "&webapp=" + appContext.getWebAppName();
params += "&format=json";
// REST からレイアウトのリストを取得できる URL を構成する
var url = "/" + appContext.getWebAppName();
url += "/bea/wlp/api/layout/list";
url += params;
//Disc からポータル対応の XMLHttpRequest を取得する
var xmlHttpReq = new bea.wlp.disc.io.XMLHttpRequest();
xmlHttpReq.onreadystatechange = function() {
if (xmlHttpReq.readyState == 4) {
if (xmlHttpReq.status == 200) {
// 応答からデータを取得する
var data = eval('(' + xmlHttpReq.responseText + ')');
${uid}displayLayouts(data)
} else {
alert("Unable to retrieve layouts.");
}
}
};
xmlHttpReq.open('GET', url, true);
xmlHttpReq.send(null);
...
コード リスト 7-8 は、REST と Disc を使用して、ポータルのレイアウトを変更するために UI を提供する JSP ファイルを全体に示します。すべての UI コードはクライアント側のコードです。Disc は、ポータルから情報を取得するために使用され、REST は、ポータルを更新するために使用されます。XHR は、サーバに非同期リクエストをするために使用されます。図 7-3 では、ポータル内のポートレット レイアウトの変更を示します。ポートレットでは、ユーザがログインされることが必要です。
<%-- Copyright (c) 2006-2008 by BEA Systems, Inc. All Rights Reserved. --%>
<jsp:root
version="2.0"
xmlns:jsp="http://java.sun.com/JSP/Page"
xmlns:render="http://www.bea.com/servers/portal/tags/netuix/render"
>
<jsp:directive.page session="false" />
<jsp:directive.page isELIgnored="false" />
<render:encodeName name="" var="uid"/>
<div id="${uid}canvas" style="display: none;">
<div style="text-align: left; margin: 8px; white-space: normal;">
Press the <span style="font-weight: bold">Change Layout</span> button
to display a list of layouts. The current layout for this page will
be selected in the drop-down list, which may be changed by selecting
a different layout. To view the changes click OK in the confirmation
dialog to refresh the desktop.
</div>
<div style="text-align: center; margin: 8px;">
<button name="changeLayout" onclick="${uid}getLayouts();">
Change Layout
</button>
</div>
<div
id="layouts"
style="text-align: center; margin: 8px; visibility: hidden;">
Layouts:
<select
id="${uid}layoutSelect"
onchange="${uid}setLayout(this.options[this.selectedIndex].value)">
</select>
</div>
</div>
<div id="${uid}message" style="text-align: center; padding: 16px;">
<span id="${uid}discMsg" style="display: none">
Please enable Disc to use this portlet.
</span>
<span id="${uid}desktopMsg" style="display: none">
Please use this portlet on a portal desktop.
</span>
<span id="${uid}loginMsg" style="display: none">
Please login to use this portlet.
</span>
<span id="${uid}customizeMsg" style="display: none">
Please enable customization to use this portlet.
</span>
</div>
<script type="text/javascript">
function ${uid}loadInit() {
if (typeof bea == "undefined") {
document.getElementById("${uid}discMsg").style.display = "";
} else {
// Disc からアプリケーション インスタンスを取得する
var appContext = bea.wlp.disc.context.Application.getInstance();
if (appContext.getDotPortal()) {
// ポートレットがデスクトップにある必要があることをユーザに通知する
document.getElementById("${uid}desktopMsg").style.display = "";
} else if (!appContext.getUserName()) {
// ポートレットを使用できるように、ユーザがログインしている必要があることを通知する
document.getElementById("${uid}loginMsg").style.display = "";
} else if (!appContext.getCustomizationEnabled()) {
// ユーザに Disc を有効にすることを通知する
document.getElementById("${uid}customizeMsg").style.display = "";
} else {
// canvas div を表示し、message div を非表示にする
document.getElementById("${uid}canvas").style.display = "";
document.getElementById("${uid}message").style.display = "none";
}
}
}
function ${uid}getLayouts() {
// Disc からアプリケーション インスタンスを取得する
var appContext = bea.wlp.disc.context.Application.getInstance();
// REST コマンド用のパラメータを構造する
var params = "";
params += "?portal=" + appContext.getPortalPath();
params += "&desktop=" + appContext.getDesktopPath();
params += "&webapp=" + appContext.getWebAppName();
params += "&format=json";
// REST からレイアウトのリストを取得できる URL を構成する
var url = "/" + appContext.getWebAppName();
url += "/bea/wlp/api/layout/list";
url += params;
// Disc からポータル対応の XMLHttpRequest を取得する
var xmlHttpReq = new bea.wlp.disc.io.XMLHttpRequest();
xmlHttpReq.onreadystatechange = function() {
if (xmlHttpReq.readyState == 4) {
if (xmlHttpReq.status == 200) {
// 応答からデータを取得する
var data = eval('(' + xmlHttpReq.responseText + ')');
${uid}displayLayouts(data)
} else {
alert("Unable to retrieve layouts.");
}
}
};
xmlHttpReq.open('GET', url, true);
xmlHttpReq.send(null);
}
function ${uid}displayLayouts(data) {
// 出力に使用する select 要素を取得する
var select = document.getElementById("${uid}layoutSelect");
// select 要素を使用して、Disc からポートレット コンテキストを取得する
var portletContext = bea.wlp.disc.context.Portlet.findByElement(select);
// ポートレットの親ページ コンテキストを取得する
var pageContext = portletContext.getParentPage();
// ページの現在のレイアウトを取得する
var layoutContext = pageContext.getLayout();
// レイアウトのマークアップ名を取得する
var layoutName = layoutContext.getMarkupName();
// select の親 div の表示を設定する
var div = select.parentNode;
div.style.visibility = "visible";
// select ボックスをクリアする
select.options.length = 0;
// 応答データからレイアウトの詳細を取得する
var layoutDetails = data.content.layouts;
var layoutDetail = null;
// layoutDetails を反復処理し、レイアウトごとにオプションを作成する
for (var i = 0; i < layoutDetails.length; i++) {
layoutDetail = layoutDetails[i];
// レイアウト詳細のために新しい option 要素を作成する
option = document.createElement("option");
option.value = layoutDetail.markup_name;
option.innerHTML = layoutDetail.title;
// マークアップ名を現在のレイアウトと比較し、マッチするものを選択する
if (layoutDetail.markup_name == layoutName) {
option.selected = "selected";
}
select.appendChild(option);
}
}
function ${uid}setLayout(layoutName) {
// 出力に使用するキャンバス要素を取得する
var canvas = document.getElementById("${uid}canvas");
// Disc からポートレット コンテキストを取得する
var portletContext = bea.wlp.disc.context.Portlet.findByElement(canvas);
// ポートレットの親ページ コンテキストを取得する
var pageContext = portletContext.getParentPage();
// Disc からアプリケーション インスタンスを取得する
var appContext = bea.wlp.disc.context.Application.getInstance();
// REST コマンドに渡すパラメータを作成する
var params = "";
params += "&portal=" + appContext.getPortalPath();
params += "&desktop=" + appContext.getDesktopPath();
params += "&webapp=" + appContext.getWebAppName();
params += "&layout=" + layoutName;
// ページ属性を変える REST コマンドの URL を構成する
var url = "/" + appContext.getWebAppName();
url += "/bea/wlp/api/page/item/" + pageContext.getLabel();
// Disc からポータル対応の XMLHttpRequest を取得する
var xmlHttpReq = new bea.wlp.disc.io.XMLHttpRequest();
xmlHttpReq.onreadystatechange = function() {
if (xmlHttpReq.readyState == 4) {
if(xmlHttpReq.status == 200) {
var msg = "Layout changed to " + layoutName + ".\n\n";
msg += "Press OK to refresh desktop.";
if (confirm(msg)) {
window.location.reload();
}
} else {
alert("Unable to change layout.");
}
}
};
xmlHttpReq.open('POST', url, true);
xmlHttpReq.send(params);
}
//このポートレット用の onload 関数を追加する
var ${uid}oldonload = (window.onload) ? window.onload : function () {};
window.onload = function () { ${uid}oldonload(); ${uid}loadInit(); };
</script>
</jsp:root>
|
