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

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

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

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

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

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

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

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

カスタム定義関数の要件を確認してください: カスタム定義関数の妥当性の要件
カスタム定義関数として使用するためのpublicかつstaticなメソッドを少なくとも1つ含む、publicなJavaクラスを記述します: カスタム定義関数用のJavaクラスの作成とコンパイル
Javaクラスをインストールします: EssbaseサーバーへのJavaクラスのインストール
カスタム定義関数をローカル関数またはグローバル関数として登録します: カスタム定義関数の登録

カスタム定義関数の妥当性の要件

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

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

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

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

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

boolean
byte
char
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カスタム定義関数のJavaクラスを作成しコンパイルするには、テキスト・エディタまたはIDE (統合開発環境)を使用してクラスを記述し、javacツールを使用してそれをコンパイルします。

カスタム定義関数用の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は、ローカル・カスタム定義関数が使用されるアプリケーションの名前です。
ESSBASEPATHまたは<Application Directory>の場所がわからない場合は、Essbaseプラットフォームでの環境変数を参照してください。

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

カスタム定義関数の登録

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

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

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

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

注意:

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

カスタム定義関数を登録するには、MaxLのcreate function文を使用します。

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

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

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

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

ノート:

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

登録済カスタム定義関数の使用方法

登録したカスタム定義関数は、ネイティブのEssbase計算関数を使用するのと同じ方法で、計算スクリプトおよび式で使用できます。

登録済カスタム定義関数を使用するには、次のようにします。

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

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

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

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

カスタム定義関数の更新

Essbaseカスタム定義関数を更新するには、そのスコープがローカルかグローバルかを特定し、影響を受けるアプリケーションを停止し、その関数のコードを含む.jarファイルを置き換え、その関数を再登録します。

カスタム定義関数を更新する手順は、次の条件に応じて異なります。

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

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

ノート:

グローバル・カスタム定義関数の更新は、DBAのみが行うようにしてください。

カスタム定義関数を更新するには、次のようにします。

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

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

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

カスタム定義関数の表示

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

カスタム定義関数を表示するには:

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

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

display function Sample;

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

カスタム定義関数の削除

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

カスタム定義関数を削除するには、次の権限が必要です。

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

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

注意:

グローバルなカスタム定義関数は、Essbaseキューブにアクセスしているユーザーがおらず計算ルーチンが実行されていない場合のみ削除します。

カスタム定義関数を削除するには:

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

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

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

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

カスタム定義関数をコピーするには、MaxL文のcreate or replace function asを使用します。

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

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

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