6 Oracle Business Rules SDKの使用

Oracle Business Rules SDK (Rules SDK）には、開発者が、カスタマイズ・アプリケーションの記述に使用できるAPIが用意されています。このアプリケーションは、ルールとデータ・モデル（および Oracle Business Rules ディクショナリに格納されているすべての情報）へのアクセス、作成または変更に使用します。Rules SDK APIを使用すると、適切に定義されたインタフェースを使用して、ディクショナリ・データを作成、変更およびアクセスできます。このAPIは、カスタマイズ・ルール対応アプリケーションの構築にも使用できます。

Rules SDK APIは、既存のルールにアクセスし、Rules Engineを実行するルール対応アプリケーションで使用したり、ルールとデータ・モデルの情報へのアクセス、作成または編集を記述したアプリケーションで使用できます。

この章では、Oracle Business Rules SDK APIについて説明します。

この章の内容は次のとおりです。

6.1 Rules SDKの構築ブロック

最上位レベルのRules SDKパッケージであるoracle.rules.sdkには、次の各パッケージが含まれています。

oracle.rules.sdk.repository
oracle.rules.sdk.dictionary
oracle.rules.sdk.editor.datamodel
oracle.rules.sdk.editor.ruleset
oracle.rules.sdk.exception

JavaBeanモデルに準拠したRules SDKインタフェースには、Beanプロパティごとにgetterとsetterが組み込まれています。たとえば、setName("somevalue")によって、個別インスタンスのnameプロパティが設定されます。

Beanインタフェースに加えて、Rules SDKには、ハッシュ関数のgetおよびputスタイル・インタフェースが用意されています。一般的に、Beanインタフェースは有用ですが、少なくとも1つのGUIフレームワークでHashMapスタイルが必要になります。

6.2 リポジトリとディクショナリの使用

Oracle Business Rulesディクショナリは、リポジトリに格納されています。ディクショナリにアクセスする前に、そのリポジトリへのアクセスを確立する必要があります。このためには、アクセスするリポジトリのタイプと、そのリポジトリ固有のタイプに必要な初期化パラメータを指定する必要があります。出荷時のRule Authorでは、WebDAV（Web Distributed Authoring and Versioning）リポジトリとファイル・リポジトリがサポートされています。

表6-1に、WebDAVリポジトリの初期化パラメータ・キーを示します。リポジトリ・タイプ・キーは、oracle.rules.sdk.store.webdavです。

表 6-1 WebDAVリポジトリ・タイプの初期化パラメータ・キー

パラメータ	キー	説明
URL	`oracle.rules.sdk.store.webdav.url`	希望するWebDAVルール・リポジトリのURL。このパラメータは必須です。
プロキシ・ホスト	`oracle.rules.sdk.store.webdav.proxyHost`	プロキシ・サーバーのホスト名。Rule Authorが実行されているサーバーとWebDAVサーバーとの間にプロキシ・サーバーがある場合のみ必須です。
プロキシ・ポート	`oracle.rules.sdk.store.webdav.proxyPort`	プロキシ・サーバーに使用するポート。Rule Authorが実行されているサーバーとWebDAVサーバーとの間にプロキシ・サーバーがある場合のみ必須です。

表6-2に、ファイル・リポジトリの初期化パラメータ・キーを示します。リポジトリ・タイプ・キーは、oracle.rules.sdk.store.jarです。

表 6-2 ファイル・リポジトリ・タイプの初期化パラメータ・キー

パラメータ	キー	説明
ファイル・パス	`oracle.rules.sdk.store.webdav.path`	ルール・リポジトリが保存されているファイルへのパス。このパラメータは必須です。

6.2.1 WebDAVリポジトリへの接続の確立

例6-1に、WebDAVリポジトリへのアクセスの確立方法を示します。

例 6-1 WebDAVリポジトリへのアクセスの確立

String url;     // the URL for the WebDAV repository
Locale locale;  // the desired Locale

// The following code assumes that the url and locale have been set appropriately
RepositoryType rt =
   RepositoryManager.getRegisteredRepositoryType("oracle.rules.sdk.store.webdav");
RuleRepository repos = RepositoryManager.createRuleRepositoryInstance(rt);
RepositoryContext rc = new RepositoryContext();
rc.setLocale(locale);
rc.setProperty("oracle.rules.sdk.store.webdav.url", url);
repos.init(rc);

WebDAVリポジトリが認証を必要とするように構成されている場合は、次の手順を実行する必要があります。

必要なユーザー名とパスワードを使用して、ウォレットを構成します。
oracle.rules.sdk.callbacks.WalletCallbackクラスのインスタンスを作成し、initメソッドをコールする前に、RepositoryContext内に設定します。

例6-2の/wallets/rules_walletは、WebDAV認証用の資格証明で構成したウォレットへのパスです。

例 6-2 認証用のウォレットの構成

WalletCallback callback = new WalletCallback("/wallets/rules_wallet", null);
rc.setSensitiveDataCallback(callback);

6.2.2 ファイル・リポジトリへの接続の確立

例6-3に、ファイル・リポジトリへのアクセスの確立方法を示します。

例 6-3 ファイル・リポジトリへのアクセスの確立

String path;     // the path to the file repository
Locale locale;  // the desired Locale

// The following code assumes that the path and locale have been set appropriately
RepositoryType rt =
   RepositoryManager.getRegisteredRepositoryType("oracle.rules.sdk.store.jar");
RuleRepository repos = RepositoryManager.createRuleRepositoryInstance(rt);
RepositoryContext rc = new RepositoryContext();
rc.setLocale(locale);
rc.setProperty("oracle.rules.sdk.store.jar.path", path);
repos.init(rc);

6.2.3 ディクショナリのロード

ディクショナリは、ディクショナリ名を指定することでロードできます。この場合は、次のコードを使用して、ディクショナリのデフォルト・バージョンをロードします。

RuleDictionary dictionary = repos.loadDictionary(dictionaryName);

または、次のコードを使用して、ディクショナリ名とバージョンの両方を指定します。

RuleDictionary dictionary = repos.loadDictionary(dictionaryName,
                                                 dictionaryVersion);

これらの例は、ファイル・リポジトリとWebDAVリポジトリの両方に適用できます。

6.3 データ・モデルの使用

Rules SDKデータ・モデルには、ルールの作成に使用するファクト・タイプ、内部変数、制約および関数が含まれています。データ・モデルのファクト・タイプは、対応するルールに基づいて判断できます。Oracle Business Rulesの変数には、複数のルールで共有する情報が含まれています。Oracle Business Rulesの関数には、ルールに対して再使用するロジックが用意されています。制約によって、ルールのカスタマイズに使用する有効な値のセットが制限されます。

注意:
既存のJavaクラスまたはXMLスキーマをインポートするには、Rule Authorアプリケーションを使用する必要があります。SDKでリポジトリを使用できるのは、Rule Authorを使用してクラスまたはスキーマをインポートした後です。SDKの今後のバージョンでは、JavaクラスおよびXMLスキーマを直接インポートできるように機能が拡張される予定です。

リポジトリを使用してRuleDictionaryオブジェクトを作成または開いた後は、Rules SDKを使用してこのディクショナリにデータ・モデルを作成できます。RuleDictionaryオブジェクトは、DataModelインスタンスの作成に必要な内部データ構造にアクセスできます。

この章で紹介するデータ・モデルの例には、emailというサンプル・パッケージからインポートしたJavaファクト・タイプが含まれています。このemailパッケージは、Rule Authorを使用してインポートしました。表6-3に示したクラスとプロパティは、email.jarをインポートして移入しました。

表 6-3 サンプルの`email`パッケージ・クラス

名前	説明	タイプ
`email.ElectronicMessage`	メッセージの発生を表します。	Javaファクト・タイプ
`email.EmailAddress`	電子メール・アドレスを表します。	Javaファクト・タイプ
`email.EmailAddressList`	電子メール・アドレスのリストを表します。	Javaファクト・タイプ

スパムを処理するデータ・モデル例では、emailパッケージが使用され、データ・モデルは、SpamFoundというRLFactオブジェクトを作成することで推論をサポートします。グローバル・カウントを組み込むには、spamCounterという変数を作成し、定数のString変数によってスパムを示します。ルールによって、スパムの電子メール・メッセージが検出されると、killSpamという関数からアクションが提供されます。表6-4に、これらのデータ・モデル・コンポーネントを示します。

表 6-4 emailパッケージを処理するためのサンプル・データ・モデル・タイプ

名前	説明	タイプ
`SpamFound`	電子メール・メッセージがスパムであると判断された場合にアサートされます。	RLファクト・タイプ
`spamCounter`	スパム・メッセージの件数を累計します。	変数
`SpecialOffer_CONST`	特別なオファーの`String`を含む定数です。	定数変数
`fKillSpam`	削除するスパムが検出されるとコールされます。	RL関数

6.3.1 データ・モデルの作成

RuleDictionaryオブジェクトを作成して開いた後は、Rules SDKを使用してeditor.DataModelインスタンスを作成できます。RuleDictionaryオブジェクトは、DataModelインスタンスの作成に必要な内部データ構造にアクセスできます。

次に例を示します。

eDM = new oracle.rules.sdk.editor.datamodel.DataModel(m_dict);

データ・モデル・タイプ・システムの基本はFactTypeオブジェクトです。FactTypeオブジェクトは、プリミティブ、Java、XMLまたはRLファクト・タイプとして定義されます。プリミティブ・ファクト・タイプは固定で、Javaプリミティブ（String、int、doubleなど）が含まれます。Rules SDKでは、RuleDictionaryを作成すると、プリミティブ・タイプが自動的に作成されます。JARファイル、クラス・ファイルまたはスキーマ・ファイルからクラスをインポートするときは、JavaおよびXMLのファクト・タイプを作成します。RLファクト・タイプは、Rules SDKを使用して直接作成できます。Java、XMLおよびRLの各ファクト・タイプではクラスが定義され、JavaBeanで定義されたプロパティを表す関連のプロパティとメソッドを指定できます。

6.3.2 データ・モデル・コンポーネントの作成

データ・モデルの各部分は、適切なModelComponentTableオブジェクトを使用して作成します。新規インスタンス（Function、FactType、VariableまたはConstraint）の作成に必要な順序は、次のとおりです。

データ・モデル内の適切な表をインスタンス化します。
表のインスタンスのadd()メソッドを起動します。

例6-4に、関数インスタンスの作成方法を示します。

例 6-4 関数インスタンスの作成

FunctionTable ft = eDM.getFunctionTable();
Function fKillSpam = ft.add();

既存のJavaクラスまたはXMLスキーマをインポートするには、Rule Authorアプリケーションを使用する必要があります。SDKでリポジトリを使用できるのは、Rule Authorを使用してクラスまたはスキーマをインポートした後です。SDKの今後のバージョンでは、JavaクラスおよびXMLスキーマを直接インポートできるように機能が拡張される予定です。

6.3.3 関数の引数リストの作成

Rules SDKでは、FormalParameterTableオブジェクトを使用して、関数の引数リストを作成します。各FormalParameterエントリは、1つのパラメータを表します。 1番目のパラメータは、FormalParameterTable内の1番目（ゼロ）のエントリ、2番目のパラメータは2番目のエントリと、以下同様に続きます。変数が定数の場合があります。この場合は、最初の初期化後に、値を割り当てることはできません。setFinal()メソッドは、定数の動作を制御します。各FormalParameterオブジェクトには、タイプと名前があります。仮パラメータのタイプは、使用可能なファクト・タイプから選択されます。

例6-5のコードでは、emailサンプルに対するFormalParameterTableオブジェクトが作成されます。

例 6-5 FormalParameterTableの作成

// define the parms of the function
// basically just an instance of ElectronicMessage
// and a String to explain what triggered this
FormalParameterTable fKillSpamParmTable = fKillSpam.getFormalParameterTable();
FormalParameter fp1 = fKillSpamParmTable.add();
FormalParameter fp2 = fKillSpamParmTable.add();
fp1.setName("emsg");
fp1.setAlias("Email Message");

// use the alias for the email.ElectronicMessage fact type
// will be in the getType_Options list
fp1.setType("email.ElectronicMessage");
fp2.setName("reason");
fp2.setAlias("reason");

 // use the primitive type for String
 // will be in the getType_Options list
fp2.setType("String");

6.3.4 初期化式の作成

Rules SDKでは、変数にルールセットの内部の状態が組み込まれます。各変数には、タイプと初期化式を指定する必要があります。変数タイプは、使用可能なファクト・タイプ（データ・モデルにはすべてのファクト・タイプが定義されています）のリストから選択します。

式には、次の2つのタイプがあります。

Expression

このタイプの式は、次の形式に従う必要があります。
```
operand operator operand
```
Expressionで使用可能なオペランドと演算子は、AdvancedExpressionで使用可能なオペランドと演算子よりも制限されています。たとえば、Expressionでは、オペランドに、パラメータが必要な関数を使用できません。
AdvancedExpression

このタイプの式では、すべてのオペランドと演算子が使用できます。

式の初期化には、AdvancedExpressionを使用することをお薦めします。例6-6に、変数の初期値の設定方法を示します。

例 6-6 変数の初期値の設定

InitialValue iv = var.getValue();
AdvancedExpression adv = iv.getAdvancedExpression();
adv.insert(0, "¥"FIXEDVALUE¥"");

6.3.5 RL関数本体の作成

RL関数本体は、RL Languageの複数の文字列で構成されます。RL関数本体は、任意の関数パラメータ、つまり任意のグローバル変数を参照する場合があります。関数本体は文字列で入力します。この文字列は、構文として正しいRL Languageである必要があります（例6-7を参照）。

例 6-7 関数本体の作成

//set the body of the function
// in this case just pretty print a message
fKillSpam.setBody(" println(¥" email from: ¥" + emsg.getSender() + ¥"  because ¥" + 
reason)" );

6.4 ルールセットの使用およびルールの作成と変更

Rules SDKでは、ルールは（条件と呼ばれる）条件式で、条件がtrueと評価された場合に実行される一連のアクションです。ルール条件は、一連のパターンで構成されます。パターンによって一致タイプが決まり、そのタイプと、前のパターン（順序に意味があります）に出現した他のタイプに対するテストが組み込まれます。ルール・アクションには、コール、割当て、取消しおよびアサーションがあります。

図6-1に、ルールセットの一般的なコンテナ階層を示します。

図 6-1 Rules SDKルールセットのコンテナ階層

画像の説明

Rules SDKには、これらの各オブジェクトを表すクラスが用意されています。すべてのクラスは、RuleComponentの下位クラスです。コレクション（ルールセット内のルール、ルール内のパターン、ルール内のアクションなど）の場合は、特定のコレクションを管理するために、Rules SDKによって、RuleComponentTableより下位のクラスが提供されます（図6-2を参照）。RuleComponentTableサブクラスでは、表で表す特定のサブクラスに対して特別なadd()メソッドが提供されます。

図 6-2 Rules SDKのRuleComponent

画像の説明

XMLスキーマ、Javaクラス、RLグローバル変数およびRL関数を記述したRules SDKコンポーネントは、（ディクショナリに格納された）データ・モデル内にあります。通常、RuleComponentインスタンスは、データ・モデル・エンティティを参照します。

6.4.1 ルールセットの作成

一般的に、RuleComponentオブジェクトの作成に使用する順序は、次のとおりです。

RuleSetコンストラクタを使用して、RuleSetインスタンスを作成します。
適切な表（PatternTable、ActionTable、ExpressionTable、SimpleTestTable）のadd()メソッドによって、RuleSetの子を作成します。

Rules SDK APIには、RuleSet内のコレクションを表すクラスが用意されています。これらの各オブジェクトは、RuleComponentの下位オブジェクトです。コレクション（ルールセット内のルール、ルール内のパターンまたはルール内のアクションなど）の場合は、特定のコレクションを管理するために、Rules SDKによって、RuleComponentTableクラスより下位のクラスが提供されます。RuleComponentTableサブクラスでは、表で表す特定のサブクラスに対して特別なadd()メソッドが提供されます。

例6-8のコードでは、emailサンプルに対するRuleSetが作成されます。

例 6-8 ルールセットの作成

oracle.rules.sdk.editor.ruleset.RuleSet rs = null;
  try
    {
      rs = new oracle.rules.sdk.editor.ruleset.RuleSet(m_dict);
      m_curBean = rs;
      rs.setName("SpamRuleSet");
    }
    catch (Exception e)
    {
      System.out.println(" create RuleSet FAILED");
      addException(e);
      return;
    }

6.4.2 ルールセットへのルールの追加

Rules SDKには、RuleSet内のオブジェクトを表すクラスが用意されています。これらの各オブジェクトは、RuleComponentオブジェクトの下位オブジェクトです。コレクション（ルールセット内のルール、ルール内のパターンまたはルール内のアクションなど）の場合は、特定のコレクションを管理するために、Rules SDKによって、RuleComponentTableクラスより下位のクラスが提供されます。RuleComponentTableサブクラスでは、表で表す特定のサブクラスに対して特別なadd()メソッドが提供されます。

コレクションの一部ではないクラスがいくつかあります。これらのクラスにアクセスするには、getterインタフェースで親Beanを使用します。たとえば、適切なPatternインスタンスでgetAdvancedExpression()を起動し、AdvancedExpressionを取得します。

例6-9のコードは、ルールセット内の表にルールを追加する方法を示しています。

例 6-9 ルールセット内の表へのルールの追加

//add rule to the table
oracle.rules.sdk.editor.ruleset.Rule r = rs.getRuleTable().add();
r.setName("DetectSpamRule");

6.4.3 ルールへのパターンの追加

Rules SDK APIには、パターンを表すPatternクラスが用意されています。getPatternTableサブクラスには、例6-10に示すように、パターン・オブジェクトを追加するための特別なadd()メソッドが用意されています。

例 6-10 ルールへのパターンの追加

//add pattern to the rule
oracle.rules.sdk.editor.ruleset.Pattern p = r.getPatternTable().add();

//set pattern
p.setVariable("xx");
p.setFactType( "email.ElectronicMessage");
p.setTestForm("Advanced");

TestFormプロパティでは、パターンに関連付けられたテストのタイプが定義されます。

6.4.4 パターンへのテストの追加

すべてのPatternには、そのPatternに関連したテストを指定できます。テストには、SimpleTestオブジェクトまたはAdvancedExpressionオブジェクトの形式を採用できます。Patternに指定できるテスト数に制限はありません。

RL Languageの生成時には、Rules SDKの論理積（AND）もテストします。たとえば、emailの例に使用するテストには、パラメータ付きの関数が必要です。このためには、AdvancedExpressionオブジェクトが必要です（例6-11を参照）。

例 6-11 パターンへのテストの追加

AdvancedExpression adv = (AdvancedExpression)p.get("AdvancedExpression");

// FUNCTION and Variable complex expression
adv.put("Function", "containsString");
adv.insert(0, adv.getFunctionDescription());

//System.out.println(" function is: <<" + adv.getFunctionDescription() + ">>");
//set the function parms
// normally the cursor position is set by user input actions
adv.setVariable("SPECIAL OFFER");
adv.replace(17, 57, adv.getVariable() );
adv.insert( ((String)adv.getValue()).length() , "," );
adv.setVariable("message.subject");
adv.insert( ((String)adv.getValue()).length() + 1,
adv.getVariable() );
adv.insert( ((String)adv.getValue()).length() , " )" );
//since boolean, this is a single operator no need for anything else

テストが次のような形式の場合は、

operand operator operand

どちらのオペランドもパラメータを必要としない関数であるため、SimpleTestを使用できます。たとえば、パターン変数名がemsgで、テストがemsg.sender == david@fun.comの場合、簡易テストでは、例6-12のようになります。

例 6-12 簡易テスト

// use the simple form of tests
p1.put("TestForm", Pattern.TEST_FORM_SIMPLE);

//////////////////////////////////////////////////////////////////////
// add a SimpleTest to the Pattern
// emsg.sender == "david@fun.com"
//////////////////////////////////////////////////////////////////////

//create a simple test
SimpleTest simple = p1.getSimpleTestTable().add();

// 
// emsg.sender == "david@fun.com"

// set the left side
Expression lhs = simple.getLeft();
lhs.setForm(Expression.FORM_SINGLE_TERM);

lhs.setSingleTermValue("emsg.sender");

// set the operator 
simple.setOperator("==");

// set the right hand side
Expression rhs = simple.getRight();
rhs.setForm(Expression.FORM_ADVANCED);

AdvancedExpression radv = rhs.getAdvancedExpression();
radv.insert(0, "¥"david@fun.com¥"");

6.4.5 ルールへのアクションの追加

Rules SDKでは、次のタイプのActionsをサポートしています。

Assert New
Assert
Assign
Call
Retract
RL

アクションのsetFormプロパティ内の設定によって、アクションのタイプが定義されます。特定のルールに関連付けられたgetActionTableインスタンスのadd()メソッドを使用して、アクションを追加します（例6-13を参照）。

例 6-13 アクション・タイプの定義

//////////////////////////////////////////////////////////////////////
// Add a action to retract the instance of SpamFound
//////////////////////////////////////////////////////////////////////
act = spamRule.getActionTable().add();
act.setForm(Action.FORM_RETRACT);
act.setTarget("spamMessage");  // see above setVariable

//////////////////////////////////////////////////////////////////////
// Add a action to call the kill spam function
//////////////////////////////////////////////////////////////////////
act = spamRule.getActionTable().add();
act.setForm(Action.FORM_CALL);
act.setTarget("kill spam");
//see the datamodel fn definitions, alias for fnKillSpam

Expression exp1 = act.getExpression(0);
Expression exp2 = act.getExpression(1);

exp1.setForm(Expression.FORM_ADVANCED);
exp2.setForm(Expression.FORM_ADVANCED);
AdvancedExpression adv1 = exp1.getAdvancedExpression();
AdvancedExpression adv2 = exp2.getAdvancedExpression();

adv1.setVariable("spamMessage.Spam Email");
adv1.insert(0, adv1.getVariable());

adv2.setVariable("spamMessage.Why is this spam");
adv2.insert(0, adv2.getVariable());

6.4.6 ルールセットおよびルールの追加に関する注意事項

RuleSetにコンポーネントを追加する順序は重要です。必要な子オブジェクトは、親オブジェクトを使用して作成します。たとえば、RuleSetのRuleTableインスタンスにルールを追加できるのは、RuleSetインスタンスを作成した後です。RuleSetを作成した後で、RuleTableのadd()メソッドを使用して、RuleSetにルールを追加します。次に、PatternTable.add() メソッドを使用して、ルールにルール・パターンを追加します。最後に、Pattern内にテストを作成するには、getAdvancedExpression()を使用して、AdvancedExpressionにアクセスするか、標準モードのテストの場合は、SimpleTestTable.add()を使用します。