プラグインによるORDS機能の拡張

14 プラグインによるORDS機能の拡張

この章では、ORDSプラグイン・フレームワークの使用について説明し、例を示します。

ORDSには、お客様独自のカスタム機能をORDS Webアプリケーションに追加できるプラグイン・フレームワークがあります。プラグインは、jarファイルをlib/extディレクトリに配置することでORDSランタイムに追加できます。ORDSディストリビューションには、サンプル・プラグインのソースが含まれています。それらのプラグイン・サンプルは、ビルド・プロセスの自動化に使用するソフトウェア・ツールであるApache antを使用してビルドできます。

プラグイン・デモンストレーション・サンプル
この項では、プラグイン・デモンストレーション・サンプルを見つけてビルドする方法を示します。
Graal JavaScriptコンポーネントの埋込み
プラグインJavascript

14.1 プラグイン・デモンストレーション・サンプル

この項では、プラグイン・デモンストレーション・サンプルを見つけてビルドする方法を示します。

プラグインデモンストレーション・サンプルは、examples/plugins/plugin-demoの場所にあります。これには、HttpServlet (実行時にデータベース接続が挿入される)のソースが含まれでいます。このサーブレットでは、そのJDBCデータベース接続を使用してデータベースで問合せが実行され、実行時にレスポンスが返されます。

次の手順を実行してデモンストレーション・サンプルをビルドし使用します。

ディレクトリをexamples/plugins/plugin-demoに変更します。
antを実行してexamples/plugins/plugin-demo/built/plugin-demo.jarファイルをビルドします
plugin-demo.jarをORDSディストリビューションのlib/extディレクトリにコピーし、ORDSインスタンスを起動します。
次のURLパターンを使用してサーブレットを起動します: http://server/ords/schema/demos/plugin?who=somebody
1. たとえば、http://localhost:8080/ORDS/hr/demos/plugin?who=scottのようにします。ここでは、ORDSはデフォルト・プールを使用して構成されており、HRはそのデータベース内のREST対応スキーマの別名です。

Javaベースのプラグインの開発とデプロイの詳細は、Oracle REST Data Services Java APIリファレンスというブックを参照してください。

14.2 Graal JavaScriptコンポーネントの埋込み

JDKバージョン21のGraalVMで実行されているORDSでJavaScriptをゲスト言語として実行できるようにするには、JavaScriptコンポーネントをプラグインとして埋め込む必要があります。

JavaScriptの埋込みに必要なアーティファクトは次のとおりです。

GraalVMポリグロットAPI
JavaScript言語

次に、必要な依存関係の取得に役立つMaven依存性の設定を示すサンプル・コード・スニペットを示します。

<dependency>
    <groupId>org.graalvm.polyglot</groupId>
    <artifactId>polyglot</artifactId>
    <version>${graalvm.version}</version>
</dependency>
<dependency>
    <groupId>org.graalvm.polyglot</groupId>
    <!-- Language: js -->
    <artifactId>js</artifactId>
    <version>${graalvm.version}</version>
    <type>pom</type>
</dependency>

埋込み言語への依存性設定の詳細は、GraalVMリファレンス・マニュアルの言語の埋込みの項を参照してください。必要なアーティファクトをダウロードしたら、実行時にクラスパスに含められるようにlib/ext/ディレクトリに配置します。

14.3 プラグインJavascript

ORDSでは、リクエスト時にORDSインスタンスで実行可能なJavaScriptをお客様が定義できるようにするためのサービス・フレームワークとして、JavaScriptが提供されています。これは、アプリケーションの開発に使用される従来のRESTfulサービスの概念に似ています。このフレームワークは、モジュール、テンプレートおよびハンドラというアーキテクチャに基づいています。「Oracle REST Data Servicesアプリケーションの開発」を参照してください。データベースでモジュール、テンプレートおよびハンドラを定義するのではなく、それらをプラグインとしてXML表現において指定し、そのXML表現がlib/ext/ディレクトリから読み取られます。

ORDSのexamplesディレクトリにはplugin-javascriptサンプルが含まれており、そのソースはexamples/plugins/plugin-javascriptディレクトリにあります。この項では、そのプラグインの主要要素について説明します。

ノート:

ORDSのJavaScriptプラグイン機能が動作するには、JSコンポーネント付属GraalVMが必要です。

このORDS機能が動作するには、JSコンポーネント付属GraalVMが必要です。詳細は、GraalVMの構成を参照してください。

このサンプルには、JavaScriptソースのインライン定義と外部定義が多数含まれています。外部JavaScriptソースへの参照は、クラスパスにあるファイルに対するものです。

ファイル	説明
`build.xml`	`ant`ビルド・プロジェクト。
`src/js/example.js`	外部JavaScriptファイルのサンプル。ここでの外部とは、XMLリソース・モジュール・ファイル内で定義されているのではなく参照されているということです。
`src/META-INF/manifest.json`	XMLリソース・モジュールを登録するためにORDSで起動時に読み取る、プラグイン構成メタデータ・ファイル。
`src/META-ING/modules/javascript.xml`	テンプレートとハンドラを多数含むサンプル・モジュールを定義する、XMLリソース・モジュール・ファイル。

次の手順を実行してサンプルをビルドし使用します。

ディレクトリをexamples/plugins/plugin-javascriptに変更します。
antを実行してexamples/plugins/plugin-javascript/built/plugin-javascript.jarファイルをビルドします。
plugin-javascript.jarファイルをORDSディストリビューションのlib/extディレクトリにコピーし、サポートされているJSコンポーネント付属GraalVMを使用してORDSインスタンスを起動します。
次のURLパターンを使用して定義済ハンドラを起動します: http://server/ords/javascript-examples/{template pattern}
1. たとえば、http://localhost:8080/ords/javascript-examples/nowです。この場合は、現在の時間が返されます。
  
  ノート:
  ORDS RESTサービスとは異なり、JavaScript as a Service実装ではデータベース接続が不要であり使用されません。

サービスの用途と使用
この項では、サンプル・サービスの用途と使用について説明します。

親トピック: プラグインによるORDS機能の拡張

14.3.1 サンプル・サービスの用途と使用

この項では、サンプル・サービスの用途と使用について説明します。

用途	リクエスト	アクション	レスポンス
現在のUTC時間を`application/json`として返すインラインJavascriptのサンプル。	`/ords/javascript-examples/now`	`GET`	`{ "now":"2023-08-31T16:08:55.471Z" }`
パラメータを受け入れるインラインJavascriptのサンプル。	`/ords/javascript-examples/future?days=7`	`GET`	`{ "now":"2023-08-31T16:08:55.471Z", "future":"2023-09-07T16:08:55.471Z", "days":7 }`
様々なソースからの各種パラメータを受け入れるインラインJavascriptのサンプル。	`/ords/javascript-examples/hello?name=Ted curl --location 'ords/javascript-examples/hello' \ --header 'Agent: Test'`	`GET`	`Hello Ted Hello Test`
パラメータを受け入れる外部Javascriptファイルのサンプル。	`/ords/javascript-examples/fibonacci?length=50`	GET	`{fib: 12586269025}`
暗黙的パラメータ`content_type`および`body_text`を使用してリクエスト値を取得し、`ords_response`を使用して`HttpServletResponse`での`setStatus`および`setContentType`を呼び出すインラインJavascriptのサンプル。	`curl --location '/ords/hr/javascript-examples/countwords' \ --header 'Content-Type: application/json' \ --data '{"text": "How many words are here?"}'`	`POST`	`{"text": "How many words are here?","count": 5}`

親トピック: プラグインJavascript