カスタム定義計算関数の開発

26 カスタム定義計算関数の開発

Essbaseブロック・ストレージ・キューブで使用可能な計算関数を拡張するために、Javaを使用して独自のカスタム定義関数(CDF)を開発できます。関数を記述したら、Javaクラスをインストールしてから、関数をEssbaseサーバーでグローバルに登録するか、またはアプリケーションにローカルに登録します。

Essbase計算スクリプトでカスタム定義関数を使用できます。

Essbaseには、Javaのクラスとアーカイブを作成するためのツールがありません。このため、サポートされるバージョンのJDKが必要です。

カスタム定義関数の例は、Javaコードの例を参照してください。

カスタム定義関数は、ブロック・ストレージ・キューブでのみ使用できます(集約ストレージ・キューブには関係ありません)。

カスタム定義関数を作成するには、次のワークフローを使用します。

カスタム定義関数の要件を確認します。Requirements for Validity of Custom-Defined Functions
カスタム定義関数として使用するためのpublicおよびstaticなメソッドを少なくとも1つ含み、publicなJavaクラスを記述します: カスタム定義関数のJavaクラスの作成およびコンパイル
Javaクラスのインストール: EssbaseサーバーへのJavaクラスのインストール
カスタム定義関数をローカル関数またはグローバル関数として登録します: カスタム定義関数の登録

カスタム定義関数の有効性の要件

Essbaseカスタム定義関数は、Javaクラスのメソッドとして設計します。グローバル関数の場合は、1つのクラスにメソッドを記述します。アプリケーション機能の場合は、アプリケーションごとに個別のクラスおよびjarファイルを使用します。関数をグローバルに登録する前に、1つのアプリケーションにローカルでテストします。サポートされているデータ型、変数および命名規則に注意してください。

カスタム定義関数として使用する複数のメソッドを1つのクラスの中に作成できます。一般的には、Essbaseサーバー上のすべてのアプリケーションでカスタム定義関数として使用する予定のメソッドを、まとめて単一クラス内に作成することをお薦めします。ただし、Essbaseサーバー上の特定のアプリケーションのみで使用されるカスタム定義関数を追加する場合は、そのカスタム定義関数を別のクラス内に作成し、別の.jarファイルでEssbaseサーバーに登録してください。

カスタム定義関数として使用されるメソッドを持つJavaクラスを複数作成するときは、各クラス名が一意であることを確認してください。クラス名が重複していると、重複するクラス内のメソッドが認識されず、そのメソッドをカスタム定義関数として登録できません。

Javaのテスト・プログラムを使用して、Javaのクラスとメソッドをテストします。メソッドの出力に問題がなければ、メソッドをEssbaseサーバー上でインストールして単一のテスト・アプリケーションに登録します。テスト目的で関数をグローバルに登録しないでください。そのようにすると、問題が発生したときに関数を更新することがより難しくなります。

カスタム定義関数内のメソッドは、次のサポートされるデータ型の任意の組合せを入力パラメータにできます。

ブール値
バイト
文字
com.hyperion.essbase.calculator.CalcBoolean
float、double
java.lang.String
short、int、long
これらのいずれかの型の配列

CalcBooleanはEssbase固有のデータ型であり、TRUE、FALSEおよび#MISSINGの3つの値を持つことができます。リストされている他のデータ型の詳細は、JDKのドキュメンテーションを参照してください。

メソッドの戻りデータ型は、voidか、前述のいずれかのデータ型にできます。戻されたデータ型は、Essbase固有のデータ型に変換されます。文字列はstring型にマッピングされます。ブール値はCalcBooleanデータ型にマッピングされます。その他のすべての値はdouble型にマッピングされます。

ノート:

Essbaseでは、戻されるdouble型の変数の値が無限値または非数(Not-a-Number)値であることはサポートされません。これらの値がJavaプログラムから戻された場合は、それらの値がEssbaseで正しく記録または表示されない可能性があります。double型の変数に無限値または非数値があるかどうかを調べて、有限値に設定してからEssbaseに戻す必要があります。JDKのドキュメンテーションのクラスDoubleに関する説明を参照してください。

Essbaseでカスタム定義関数の作成、削除および管理を行うには、次のセキュリティ権限が必要です。

ローカル、アプリケーション全体のカスタム定義関数: アプリケーション・マネージャ以上
グローバル、サーバー全体のカスタム定義関数: システム管理者

カスタム定義関数をEssbaseに登録するときに、関数に名前を付けます。この名前が計算スクリプトと式で使用されます。この名前は、関数内で使用されるJavaクラスとメソッドの名前とは別のものです。

カスタム定義関数に名前を付けるときは、次の要件に従います。

名前の先頭に@記号を付けます。関数名の残りの部分には、英字、数字および記号(@、#、$および_)を使用できます。関数名にスペースを含めることはできません。

例: @MYFUNCTION
カスタム定義マクロからのみ呼び出されるカスタム定義関数の場合は、名前の先頭に@_を付けます。これは、一般用途の関数およびマクロと区別するためです。

例: @_MYFUNCTION
カスタム定義関数の名前は一意である必要があります。関数名は、他の関数名、カスタム定義マクロの名前および既存の計算関数の名前とは異なっている必要があります。
Essbaseアプリケーションの中にあるローカル関数と同じ名前のグローバル関数がある場合は、ローカル関数が計算に使用されます。

カスタム定義関数のJavaクラスの作成およびコンパイル

Essbaseカスタム定義関数(CDF)のJavaクラスを作成およびコンパイルするには、テキスト・エディタまたはIDE (統合開発環境)を使用してクラスを記述し、javacツールを使用してコンパイルします。

次に、CDF用のJavaクラスを作成するためのワークフローの例を示します。

テキスト・エディタでJavaクラスを作成します。

たとえば:

public class CalcFunc {
  public static double sum (double[] data) {
    int i, n = data.length;
    double sum = 0.0d;
    for (i=0; i<n; i++) {
      double d = data [i];
      sum = sum + d;
    }
    return sum;
  }
}

ファイルを.java拡張子で保存します。
たとえば:
```
CalcFunc.java
```
.javaファイルが保管されているディレクトリに移動します。コマンド・プロンプトで、次のコマンドを入力します。
```
javac java_filename
```
たとえば:
```
javac CalcFunc.java
```
コンパイラによって.class拡張子の新しいファイルが作成されるまで、コンパイル・エラーを解決します。
たとえば:
```
CalcFunc.class
```

EssbaseサーバーにJavaクラスをインストール

カスタム定義計算関数(CDF)のJavaクラスをEssbaseサーバーにインストールするには、これらのクラスをコンパイルし、次の手順で指定したグローバルまたはアプリケーション・レベルのudfディレクトリにjarファイルをコピーして、アプリケーションまたはサーバーを再起動します。

Javaクラスは、JDK jarツールを使用してJARファイルにコンパイルする必要があります。

.jarファイルを作成してEssbaseサーバーにインストールするには:

.classファイルが保管されているディレクトリに移動します。コマンド・プロンプトで、次のコマンドを入力します。
```
jar cf jar_filename class_filename
```
たとえば:
```
jar cf CalcFunc.jar CalcFunc.class
```
Essbaseサーバーで、.jarファイルを次のいずれかのディレクトリにコピーします(ディレクトリが存在しない場合は、作成します)。
- グローバル・カスタム定義関数を含んでいる.jarファイル:
  ESSBASEPATH/java/udf/
- 特定のアプリケーションでのみ使用する.jarファイル:
  <Application Directory>/app/appname/udf/
  appnameは、ローカルCDFが使用されるアプリケーションの名前です。
ESSBASEPATHまたは<Application Directory>の場所がわからない場合は、Essbaseプラットフォームの環境変数を参照してください。

.jarファイルを別の場所に配置した場合は、CLASSPATH変数を変更して、.jarファイルへのフルパスとファイル名を含める必要があります。
特定のアプリケーションでのみ関数を使用する場合は、そのアプリケーションを再起動します。それ以外の場合は、Essbaseサーバーを再起動します。独立したデプロイメントの場合はサーバーの起動、停止およびチェック、OCIでのスタック・デプロイメントの場合は「コマンドを使用したプロセスの起動、停止およびステータスの表示」を参照してください。

カスタム定義関数の登録

MaxLを使用して、カスタム定義関数(CDF)をEssbaseに登録します。登録タスクは、CDFをJavaクラス内に記述し、クラスをコンパイルしてjarファイルをインストールした後に実行されます。

CDF用のJavaクラスを.jarファイルにコンパイルし、その.jarファイルをEssbaseサーバーにインストールしたら、計算スクリプトと式で使用できるように、関数を登録する必要があります。「カスタム定義関数の有効性の要件」を参照してください。

グローバルCDFを登録すると、Essbaseサーバー上のすべてのEssbaseアプリケーションでそのCDFを使用できます。関数をグローバル関数にする前に、単一のアプリケーションでその関数のテスト(およびそのアプリケーションでのみその関数の登録)を行います。

マクロのカタログを更新する場合と同じプロセスを使用して関数のカタログを更新します。カスタム定義マクロのカタログの更新を参照してください。

注意:

グローバル関数をテスト目的で登録しないでください。問題が発生した場合に変更がより難しくなります。

CDFを登録するには、create function MaxL文を使用します。

CDFをローカル・スコープに登録するには、アプリケーション名を接頭辞として含めます。たとえば、次のMaxL文では、CalcFuncクラスの関数@JSUMが、Sampleアプリケーション内で使用するためのローカル関数として登録されます。

create function Sample.'@JSUM'
as 'CalcFunc.sum'
spec '@JSUM(memberRange)'
comment 'adds list of input members';

グローバル・スコープでCDFを登録する場合は、アプリケーション名を接頭辞として含めません。たとえば、次のMaxL文では、CalcFuncクラスの関数@JSUMが、Essbaseサーバー上のすべてのアプリケーションで使用するためのグローバル関数として登録されます:

create function '@JSUM'
as 'CalcFunc.sum'
spec '@JSUM(memberRange)'
comment 'adds list of input members';

ノート:

Javaメソッドの入力パラメータの指定はオプションです。入力パラメータを指定しない場合、Essbaseでは、Javaコードのメソッド定義から入力パラメータが読み取られます。ただし、複数のCDFを登録するときにメソッド名は同じですがパラメータ・セットが異なる場合、関数のバージョンごとに個別に登録し、関数のバージョンごとにパラメータを指定する必要があります。

登録済カスタム定義関数の実装

ネイティブのEssbase計算関数を使用する場合と同様に、登録済のカスタム定義関数(CDF)を計算スクリプトおよび式で使用できます。

登録済CDFを使用するには:

計算スクリプトまたは式を作成するか、既存の計算スクリプトまたは式を開きます。
- CDFを特定のアプリケーション内でローカルに登録した場合は、そのアプリケーション内の計算スクリプトや式を使用する必要があります。
- CDFがグローバルに登録されている場合は、Essbaseサーバーですべての計算スクリプトまたは式を使用できます。
計算スクリプトまたは式に関数を追加します。

たとえば、JSUMを使用するには、次の計算スクリプトを使用します。

"New York" = @JSUM(@LIST(2.3, 4.5, 6.6, 1000.34));

この計算スクリプトをSample.Basicサンプル・データベースで使用するか、"New York"をテスト・データベースにあるメンバーの名前に置換します。
計算スクリプトまたは式を保存したら、通常どおりに実行します。

カスタム定義ファンクションの更新

Essbaseカスタム定義関数(CDF)を更新するには、それがスコープ内でローカルかグローバルかを決定し、影響を受けるアプリケーションをシャットダウンして、関数のコードを含む.jarファイルを置き換え、関数を再登録します。

CDFを更新する手順は、次の条件によって異なります。

関数がローカルに登録されているのか、グローバルに登録されているか。
CDFのシグネチャ(クラス名、メソッド名または入力パラメータ)がJavaコードで変更されているかどうか。

通常、CDFを更新するには、ファンクションのコードを含む.jarファイルを置換して、再登録する必要があります。ただし、CDFのシグネチャが変更されていない場合、CDFの入力パラメータが1セットのみである(オーバーロードされたメソッドではない)場合は、関数を含む.jarファイルを置換できます。

ノート:

グローバルCDFを更新するのは管理者のみです。

CDFを更新するには:

関数がローカルとグローバルのどちらであるかを確認します。

カスタム定義関数の表示を参照してください。
CDFのJavaクラスに変更を加えて、Javaテスト・プログラムを使用してその出力をテストします。
Javaクラスをコンパイルして、以前の.jarと同じ名前を使用してこれらを新しい.jarファイルにアーカイブします。

以前の.jarファイルに含まれていたCDFのその他のクラスとメソッドを含めます。
ローカルとグローバールのどちらのカスタム定義関数を更新しているのどれかに応じて、次のアクションを実行します。
1. ローカル: .jarファイルの関数を使用するすべてのEssbaseアプリケーションをシャットダウンします。
2. グローバル: すべてのEssbaseアプリケーションをシャットダウンします
どのEssbaseアプリケーションが.jarファイル内のどの関数を使用するかが不明の場合は、すべてのEssbaseアプリケーションをシャットダウンします。
新しい.jarファイルをEssbaseサーバーにコピーして、既存の.jarファイルを同じ名前のファイルで置換します。
CDFのシグネチャが変更されていない場合は、ステップ8にスキップします。
CDFを置き換えるには、create or replace function MaxL文を使用します。次に例を示します。
- ローカル:
```
create or replace function sample.'@JSUM'
as 'CalcFunc.sum';
```
- グローバル:
```
create or replace function '@JSUM'
as 'CalcFunc.sum';
```
シャットダウンしたアプリケーションを再起動します。これにより、カタログが更新されます。

カスタム定義関数の表示

Essbaseでカスタム定義関数(CDF)を表示して、正常に登録されたかどうか、およびスコープ内でローカルかグローバルかを判断します。CDFは、作成して登録するまで表示されません。

CDFを表示するには:

MaxLのdisplay function文を使用します。

たとえば、SampleアプリケーションのCDFおよびすべての登録済グローバル関数を表示するには、次のMaxL文を使用します。

display function Sample;

display function文によって、アプリケーション名なしでグローバル関数がリストされ、それらがグローバルであることが示されます。アプリケーションにグローバル関数と同じ名前の関数が含まれている場合は、ローカル関数のみがリストされます。

カスタム定義関数の削除

Essbaseカスタム定義関数(CDF)を削除/登録解除するには、まずそれらが使用されていないことを確認してください。次に、CDFが定義されているアプリケーションをシャットダウンし、MaxL drop function文を発行してCDFを削除し、影響を受けるアプリケーションを再起動します。

CDFを削除するには、次の権限が必要です。

ローカル: アプリケーションに対するアプリケーション・マネージャ以上の権限
グローバル: システム管理者権限

CDFを削除する前に、その計算スクリプトや式がないことを確認する必要があります。グローバルCDFは、Essbaseサーバー全体の計算スクリプトと式で使用できるため、グローバルCDFを削除する前に、Essbaseサーバー上でその計算スクリプトや式がないことを確認する必要があります。

注意:

ユーザーがEssbaseキューブにアクセスせず、計算ルーチンが実行されていない場合にのみ、グローバルCDFを削除します。

CDFを削除するには:

関数がローカルとグローバルのどちらであるかを確認します。

カスタム定義関数の表示を参照してください。
ローカルCDFとグローバルのどちらのCDFを削除しているかに応じて、以下のアクションを実行します。
1. ローカル: .jarファイルの関数を使用するすべてのEssbaseアプリケーションをシャットダウンします。
2. グローバル: すべてのEssbaseアプリケーションをシャットダウンします。
CDFを削除するには、drop function MaxL文を使用します。次に例を示します。
- ローカル:
```
drop function Sample.'@JSUM';
```
- グローバル:
```
drop function '@JSUM';
```
シャットダウンしたアプリケーションを再起動します。これにより、カタログが更新されます。

カスタム定義関数のコピー

カスタム定義関数(CDF)は、適切なアクセス権がある任意のEssbaseサーバーとアプリケーションにコピーできます。

CDFをコピーするには、create or replace function as MaxL文を使用します。

カスタム定義関数のパフォーマンスに関する考慮事項

カスタム定義関数はEssbase計算機フレームワークの拡張として実装されるため、CDFの動作効率は、Essbaseのネイティブ計算関数よりも低いと考えられる場合があります。

パフォーマンスを最適化するために、特に、計算スピードが重要となるアプリケーションでは、カスタム定義関数の使用を、ネイティブのEssbase計算コマンドおよび関数で実行できない計算に限定してください。