GlassFish の REST backend

この記事はGlassFish Advent Calendar 2013の8日目として新たに書き下ろしたものです。昨日は「GlassFishドメインのバックアップとリストア」でした。


今回はGlassFishのREST管理チャネルについてご紹介します。昨年9月に開催したGlassFish勉強会で筆者が担当したセッション「GlassFish REST管理チャネル入門」を掘り下げた内容となります。

今年8月のJJUGナイトセミナー・LT大会にて「GlassFish Internal #1 : Introduction to Nucleus」と題する、Nucleusを紹介する内容のLTを担当しました。NucleusとはこのAdvent Calendarでも何度か登場している、GlassFishの基盤部分(カーネルを含む)の呼称です。

セッションでは、Nucleusに対する操作はCLI Framework(極言するとasadmin)経由かREST backend経由の2通りしかなく、管理コンソールも裏ではREST backendを呼び出していることを強調しました。今回取り上げるのは後者のREST backendの一部である、REST管理チャネルです。

1. REST backendについて

REST backendはその名の通りRESTful Webサービスを利用したGlassFishの管理・監視インタフェースです。どちらもHTTPクライアントを用いてDAS(ドメイン管理サーバー)にアクセスしますあす。スタンドアロン運用の場合は localhost:4848 が対象となります。

管理チャネルのURIは /management/domain です。GlassFishのほぼ全ての設定項目と管理操作がこのURI以下のリソースにまとめられています。設定項目の参照にはGETメソッド、変更・削除には主にPOSTメソッドを用います。一部の項目削除にはDELETEメソッドを使用しますが、PUTメソッドが使用される箇所は存在しません。管理操作はコマンドによりGETまたはPOSTメソッドのいずれかを使用します。管理チャネルの設定項目のリソースは、設定値に変更がない限り常に同じ内容となります。

監視チャネルのURIは /monitoring/domain です。Monitoring Frameworkが提供する監視プローブがこのURI以下のリソースにまとめられています。基本的にはGETメソッドを用いて監視対象のスナップショットを取得します。そのため、リクエストごとに毎回異なる内容を取得することになります。

2. REST backendの表現形式

REST backendのリソースはHTML、XML、JSONの3種類の表現形式を持っています。これらはリクエストのAcceptヘッダーでMIMEタイプを指定するか、URIに拡張子(.html .xml .json)を付加することで選択することができます。これらの省略時はConnegによりWebブラウザではHTML、汎用的なHTTPクライアントではJSONになります。ただし管理チャネルの /view-log リソースと子リソース /view-log/details だけは特殊な振る舞いをします。/view-log は常にテキスト形式となり、text/plain 以外のMIMEタイプは指定できず、拡張子を付加することもできません。/view-log/details リソースはJSONまたはXML形式のみサポートし、HTML形式を取ることが出来ません(テキスト形式 text/plain は受け付けますが、JSON形式をそのまま返します)。

REST backendのHTML形式はFORM要素を持っているものがあり、そこから更新操作を行うことが出来ます(ただし、同じ操作を行うのであれば管理コンソールの方が使い勝手が良いため、実用性はあまり高くありません)。

XML形式はスキーマレスで、各要素が直接JSON構文と対応しています。

REST backend 出力のJSON-XML対応表
JSONXML
key : value entry要素: <entry key="key" value="value"/>
{ ... } map要素: <map>...</map>
[ ... ] list要素: <list>...</list>

最も外側は必ず { ... } map要素になります。

3. 管理チャネルの表現形式

管理チャネルでは、各リソースに以下の4つのentryが必ず存在します。

管理チャネル 最上位 entry
entry 名概要
command コマンド名
exit_code 実行結果、成功 SUCCESS または 失敗 FAILURE
message 補足のメッセージ、exit_code : SUCCESS では空が多いが、FAILURE の場合は必ずエラーメッセージが入る
extraProperties mapで構成され、リソースごとに内容は異なる

なお、実際の出力順は message exit_code extraProperties command になります。

extraPropertiesに含まれる代表的なentryには以下のようなものがあります。この他にもリソースによって様々なentryが含まれます。

methodsこのリソースが受け付ける操作のリストです。各操作はmapで構成され、name : HTTPメソッド、messageParameters : パラメータのmapからなります。パラメータはentityと対応しており、keyがパラメータ・キー、valueが値の属性を表します。値の属性は、key : 、type : データ型、optional : 省略可否、defaultValue : デフォルト値、acceptableValue : 許容される値からなり、一部が省略される場合もあります。多くのリソースに存在するentryですが、必ず存在するわけではありません。

管理チャネル extraProperties の主な子 entry
entry 名概要
childResources 子リソースを表すmapです。各entryのkeyがリソース名、valueがリソースの絶対URIを表します。末端のリソース以外には必ず存在するentryです。
entity このリソースに設定されているパラメータのmapです。keyがパラメータ・キー、valueが値となります。パラメータmapはネストしている場合があります。保持すべきパラメータがないリソースでは省略される場合があります。
commands コマンド(管理操作)のリストです。個々のコマンドはmapで、path : コマンドの相対URI、command : コマンド名、method : コマンド実行に用いるメソッドの3つのentryからなります。
commandLog このリソースに対して実行されたコマンド(管理操作)のコマンド名listです。省略されることもあります。
children 一覧系のコマンド(コマンド名が list- で始まることが多い)の実行結果のリストです。実行結果はmapで、properties : プロパティのmap(空であることも多い)、message : 表示内容 の2つのentryを持ちます。

4. 監視チャネルの表現形式

監視チャネルでも、各リソースに以下の4つのentryが必ず存在します。

監視チャネル 最上位 entry
entry 名概要
command コマンド名
exit_code 実行結果、成功 SUCCESS または 失敗 FAILURE
message 補足のメッセージ、監視チャネルでは常に空白
extraProperties mapで構成され、リソースごとに内容は異なる

なお、実際の出力順は管理チャネル同様 message exit_code extraProperties command になります。

extraPropertiesには以下のentryが含まれます。管理チャネルと異なり、他のentryは含まれません。

監視チャネル extraProperties の子 entry
entry 名概要
entity このリソースの設定されているパラメータのmapです。keyがパラメータ・キー、valueが値となります。パラメータmapはネストしていることが多く、かつ管理チャネルのリソースに比べてネストが深くなる傾向があります。監視チャネルでは保持すべきパラメータがない場合でも必ず存在します(空のmapになる)。
childResources 子リソースを表すmapです。各entryのkeyがリソース名、valueがリソースの絶対URIを表します。管理チャネルと異なり、このentryは必ず存在します。子リソースがない場合は空のmapとなりますが、entityのパラメータ・キーを子リソースURIとすることでentity内容の絞り込みができるようになっています(entityがもつentryが1個以下の場合には絞り込みは出来ません)。

5. REST backendへのアクセス

POSTまたはDELETEメソッドを使用する場合は、X-Requested-Byヘッダーを設定します。参考までHTML形式のFORMではJavaScriptを用いて以下のようなヘッダーを付加しています。

X-Requested-By: GlassFish REST HTML interface

DASにパスワードを設定している場合はそのままREST backendにアクセスすることはできません。また、デフォルトではBASIC認証も使用できません。

BASIC認証を使用する場合は、セキュア管理を有効にする必要があります。セキュア管理を有効にするとDASとの通信がHTTPSに切り替わり、BASIC認証を用いてREST backendにアクセスできるようになります。

セキュア管理を使用しない場合の代替案として、セッション・トークンを取得する方法も用意されています。

セッション・トークンを取得する場合は、まずクライアントでBASIC認証を構成してURI /management/sessions にPOSTメソッドの空リクエストを送信します(X-Requested-Byヘッダーの設定を忘れないように)。このリソースの extraProperties に含まれる token というentryがセッション・トークンです。REST backendへアクセスする際には gfresttoken というクッキーを作成し、セッション・トークンの値を設定します。この手順で、セッション・トークンが有効の間だけですが、認証なしでREST backendへのアクセスが可能になります。なお、セッション・トークンは30分のタイムアウトで無効となるほか、URI /management/sessions/トークン値 にDELETEリクエストを送信することで破棄することもできます。

2013-12-23 補足: マニュアルにはセッション・トークンを取得するにはGETメソッドを使用するようにとありますが、これは誤りです。 /management/sessions へのOPTIONSリクエストの結果で明らかですが、このURIはPOST(およびOPTIONS)メソッドしか受け付けません。子リソース /management/sessions/トークン値 についてはDELETE(およびOPTIONS)のみ使用可能です。

6. 最後に

GlassFishのREST backendは、DAS起動を除くすべての操作をHTTP通信だけで行うことができる、非常に強力な機能です。標準の管理コンソールがREST backendを利用するWebアプリケーションであることからも、その強力さは伺い知ることができます。一方でREST backendはNucleusの一部であり、Config FrameworkやManagement FrameworkといったGlassFishのカーネル近くに位置するコンポーネントに直結しているため、Undocumentedな部分も少なからずあります。

今回ご紹介した内容を押さえておけば、REST backendの出力から未知の部分を類推できるはずです。そして、GlassFishの仕組みをより深く理解するための手掛かりを得ることもできるでしょう。


明日は、もう少し軽めの話題を取り上げたいと思います。