[Cloud, Integration] Using a Library in OIC

原文はこちら
https://blogs.oracle.com/integration/using-a-library-in-oic

---

Introduction

Oracle Integration Cloud（OIC、以下OICと省略）におけるライブラリは、JavaScript関数を含む単一のファイルもしくは複数ファイルをJARの形で束ねたものです。ライブラリは統合の中で利用され、JavaScriptエンジンがサーバで統合フローの中で実行します。

このエントリでは以下の内容について説明します。

1. 統合の中で利用するにあたって必要とするJavaScript関数に対する要求事項
2. ライブラリを作成するために適したJavaScriptファイルやJavaScriptファイルのコレクションの作成方法

1. JavaScript function requirements

OICで登録ができ、正しく動作可能なJavaScriptに対する要求事項は以下の通りです。

1.1 Function return values should be named

以下の例を考えます。

function add ( param1, param2 ) {
  return param1 + param2;
}

上記の例は完全にJavaScript関数として正しいのですが、OICのライブラリとして登録できません。その理由は、名前付きの戻り値がないためです。これがないと、ライブラリメタデータ・エディタは関数が戻すパラメータを識別できず、結果として統合のダウンストリームアクティビティにマッピングするためのマッパーで利用できません。

OICで利用するためには、上記関数を変更し、以下のように戻り値のパラメータに名前を付ける必要があります。

function add ( param1, param2 ) {
  var retValue = param1 + param2;
  return retValue;
}

この場合、戻り値のパラメータには retValue という名前が付いています。この変更により、ユーザーは戻り値をダウンストリーム・アクティビティにマッピングできるようになります。

1.2 Inner functions

JavaScript関数が別の関数を内部で定義している場合、OICのライブラリメタデータ・エディタは内部関数を識別しませんので、内部関数用にメタデータを作成しません。関数用のメタデータを作成しない場合にはOICで当該関数を利用できませんが、内部関数はその外側にある関数内で利用することは可能です。

function parseDate(d) {
 function foo(d) {
    if(typeof d === 'string') { 
       return Date.parse(d.replace(/-/g,'/')); 
    }
    if(!(d instanceof Array)) { 
       throw new Error("parseDate: parameter must be arrays of strings"); 
    }
    var ret = [],k;
    for(k=0;k<d.length;k++) { 
       ret[k] = foo(d[k]); 
    }
    return ret;
 }
 var retVal = foo(d);
 return retVal;
}

上記の例の場合、 foo() を関数 parseDate() の中で定義しているため、メタデータUIエディタはfoo()を無視し、外部関数parseDate()のみを構成できますが、関数として問題ないため、parseDate()内でfoo()を利用します。

1.3 Long running functions

JavaScript関数の実行は最大1500msを超えてはいけません。（依存関係を含めて）関数の実行がこの閾値を超過した場合、自動的にサーバがプロセスをKILLし、1500msを超えたためにフローをKILLした旨をログメッセージに書き出します。

1.4 Input parameter types

OICは現在String、Number、Booleanの入力パラメータおよび戻り値のみをデータ型としてサポートしています。JavaScriptが異なるオブジェクト型、例えばArrayやDate型を利用する場合、サポートされているデータ型のいずれかであることを期待される入力パラメータを関数が期待するデータ型に変換する必要があります。以下はArray型の入力を取り扱う例です。

1.4.1 Array Input Type

以下の配列処理の例を考えます。

function myArrayProcessor(myArray) {
 var status = 'FAILED';
 for (i=0; i<myArray.length; i++) {

 }
 return status;
}

サポートされるパラメータ型にArrayは含まれていないため、このコードを以下の例のように変更する必要があります。

function myArrayProcessor(myArray) {
 var status = 'FAILED';
 var data = myArray.replace(/'/g, '"');
 myArray = JSON.parse(data);
 for (i=0; i<myArray.length; i++) {

 }
 return status;
}

この関数のメタデータを構成する際にはStringとして入力データ型をマークし、統合内の関数を使う際に入力文字列を解析して関数内でArrayに変換します。

2. Creating library using a JavaScript file or multiple files

2.1 Using single JavaScript file

単一のJavaScriptファイルを使ってライブラリを作成するのは簡単ですが、その単一ファイルに全ての依存関係を含める必要があります。関数が別の関数に依存している場合、依存関係のある関数が同一ファイル内に存在していなければなりません。ライブラリ登録時には、統合内で利用するために必要な関数のメタデータのみ編集すればよいのです。もし依存関係を満足するために存在する別の関数を構成する必要はありません。

以下の相互依存関係にあるJavaScript関数の例を考えます。

function funcOne(param1) {
 return param1;
}

function funcTwo(param2){
 return param2
}

function myFunc(param1, param2) {
 var ret = funcOne(param1) + funcTwo(param2);
 return ret;
}

この例では、funcOne() とfuncTwo() を myFunc() が利用しています。このライブラリのメタデータを構成する際には、統合内で利用できるmyFunc()関数のみを構成すればOKです。

2.2 Using multiple JavaScript files

ライブラリを複数のJavaScriptファイルを基にして作成できます。複数ファイルを使う場合、JARファイルの形で全てのファイルを束ねて、JARファイルをライブラリとして登録する必要があります。

例として、EncodeAndDecodeライブラリを考えます。これは、Base64エンコードおよびデコードのスキームを使ってエンコード、デコードを実施するものです。

ライブラリは2個のファイル、Base64.js（Base64エンコードおよびデコードのロジック）とEncrypt.js（Base64.js内の関数に依存するラッパー関数）から構成されています。エンコードとデコードのラッパー関数を統合内で利用します。両ファイルともJARファイルに含まれており、このJARファイルを使ってライブラリを作成します。

上図のように、ライブラリを利用するために、Encrypt.jsファイル内のencode関数とdecode関数のメタデータを構成します。

3. Debugging JavaScript in a library

時間が経つと、JavaScriptライブラリのサイズと複雑さが増す可能性があります。JavaScriptライブラリのデバッグというと、通常はブラウザでのJavaScriptのテストで、問題なく動作することを確認したらライブラリとしてコードをリリースします。しかしこのやり方では、動作しないことがあります。その理由は、ブラウザが最新のJavaScriptバージョンをサポートする新しい実行エンジンで定期的に更新されていること、そして一般にブラウザエンジンは多くのコードエラーを無視するという点でより自由であるのに対し、OIC内のJavaScriptエンジンはより厳格だからです。
J avaScriptコードをデバッグするためには、以下のサンプルコードのようにCXConsole()のインスタンスを利用できます。

function add ( param1, param2 ) {
 var console = new CXConsole();
 var retValue = param1 + param2;
 console.log("# retValue: ", retValue);
 console.warn("# retValue: ", retValue);
 return retValue;
}

上記コードのログメッセージはserver-diagnostic.logファイルに書き込まれます。