RuleSessionの使用

5.1 RuleSessionコンストラクタのプロパティ

ルール対応アプリケーションを作成するステップおよびRuleSessionオブジェクトの使用方法を学びます。RuleSessionオブジェクトはパッケージoracle.rules.rlに含まれています。

RuleSessionコンストラクタは、引数がない場合、デフォルトのロケールおよびロギング・オプションが設定されたRuleSessionを戻します。

表5-1に、RuleSessionコンストラクタに渡されるマップで設定可能な構成パラメータを示します。

表5-1 RuleSessionコンストラクタの構成パラメータ

パラメータ・キー	値
`CFG_LOGGING`	ブール値。trueの場合、ロギングが有効です。Falseの場合、ロギングが無効です。デフォルトは、trueです。
`CFG_LOCALE`	任意のロケールに対するロケール・オブジェクト。デフォルトはJVMデフォルト・ロケールです。
`CFG_WATCH`	RAWアクティビティ監視のトレース機能に関する必要な設定。この設定は、セッションのリセット時にリストアされます。 `WATCH_RULES`: 起動される監視ルール。 `WATCH_ACTIVATIONS`: 監視ルールのアクティブ化および非アクティブ化。 `WATCH_FACTS`: 監視のファクト操作(アサート、変更、撤回)。 `WATCH_FOCUS`: 監視ルールセット・スタックの変更。 `WATCH_COMPILATION`: 監視ルールの定義。 `WATCH_ALL`: 前述のすべての監視。デフォルトでは、トレース設定は1つも有効化されません。
`CFG_DECISION_TRACE_LEVEL`	トレース対象のルール・エンジン・アクティビティを制御するデシジョン・トレース・レベルを設定します。このレベルは、セッションのリセット時にリストアされます。 `DECISION_TRACE_OFF`: すべてのデシジョン・トレースを無効化します。 `DECISION_TRACE_PRODUCTION`: 起動されるルールをトレースします。 `DECISION_TRACE_DEVELOPMENT`: 詳細なデシジョン・トレース。`WATCH_ALL`およびリセットのトレースに相当します。デフォルトは`DECISION_TRACE_OFF`です。
`CFG_DECISION_TRACE_LIMIT`	トレースが取得されるまで内部的に格納されるトレース・エントリ数に制限を課す整数。デフォルトのデシジョン・トレース制限は10000です。

5.2 RuleSessionのメソッド

outputWriterプロパティは、println、watchおよびshowの出力先を決定します。

rulesetNameプロパティは、明示的にルールセット名を指定せずに、RL文の実行時にルールセットを設定します。デフォルトのrulesetNameはmainです。

executeRulesetメソッドは、指定のルールセット・テキスト(Stringまたはjava.io.Readerとして指定)を解析して実行します。

callFunctionメソッドは、名前付きRL関数(組込みRL関数または以前にexecuteRulesetメソッドの1つを使用してパラメータなしで定義した関数)を起動し、その結果を戻します。単一の引数を取る関数は、callFunctionWithArgumentメソッドを使用して起動できます。任意の数の引数を取る関数は、callFunctionWithArgumentListまたはcallFunctionWithArgumentArrayメソッドを使用してコールできます。引数のリストまたは配列には、各RL関数パラメータのJavaオブジェクトが記載されている必要があります。

5.3 RL型からJava型への変換

次の表では、引数をRL関数に渡すためにJavaオブジェクト型をRL型に変換する方法について説明します。

表5-2に、引数をRL関数に渡すためにJavaオブジェクト型をRL型に変換する方法、およびRL関数の戻り値をJavaに渡すためにRL型をJava型に変換する方法を示します。

表5-2 RLからJavaオブジェクトへの変換

Javaクラス	RL型
`java.lang.Integer`	`int`
`java.lang.Character`	`char`
`java.lang.Byte`	`byte`
`java.lang.Short`	`short`
`java.lang.Long`	`long`
`java.lang.Double`	`double`
`java.lang.Float`	`float`
`java.lang.Boolean`	`boolean`
`Object`	`Object`
`int[]`	`int[]`
`char[]`	`char[]`
`byte[]`	`byte[]`
`short[]`	`short[]`
`long[]`	`long[]`
`double[]`	`double[]`
`float[]`	`float[]`
`boolean[]`	`boolean[]`
`Object[]`	`Object[]`

5.4 エラー処理

RuleSessionメソッドの起動でParseExceptionまたはTypeCheckExceptionがスローされても、RuleSessionの状態には影響を与えません。Javaアプリケーション(たとえば、対話型のコマンドライン)では、これらの例外を検出し、RuleSessionの使用を続行できます。

RuleSessionメソッドの起動でRLRuntimeExceptionがスローされた場合は、RuleSessionの状態に影響を与える可能性があり、アプリケーションでRuleSessionを処理できない状態になる場合があります。堅牢なアプリケーションの場合は、RLでRLRuntimeExceptionを検出し、例外がスローされた近辺でリカバリするように試みます。

その他の例外は、多くの場合、アプリケーションで処理できない重大な問題を示します。

5.5 RLクラスの反映

RLクラスは、Javaクラスと同様にRLプログラムで使用できます。new、instanceofおよびcastの演算子は、両方のクラスで使用できます。

ただし、Javaプログラムに渡されたRLクラスのインスタンスは、実際にはoracle.rules.rl.RLObjectのインスタンスです。Javaプログラムでは、RLObjectを調べるためにRLClass、RLPropertyおよびRLArrayクラスを使用できます。使用方法は、java.lang.Class、java.lang.reflect.Fieldおよびjava.lang.Arrayクラスを使用してjava.lang.Objectを反映する場合と同じです。RLCLass、RLPropertyおよびRLArrayは、パッケージoracle.rules.rlに含まれます。

5.6 ルール対応プログラムからの結果の取得

Oracle Business Rulesを使用してルール対応プログラムを作成したときの一般的な疑問は、「評価の結果を取得する方法は?」です。

この項では、ルール・エンジンからルール評価の結果を抽出または表示する方法を説明します。

内容は次のとおりです。

5.6.1 結果の例の概要

この項で使用する例は、高速道路の事故通知システムを示しています。それぞれの例は、ルール・エンジンの評価結果にアクセスするための異なる方法を示しています。これらの例では、2つのJavaクラスtraffic.TrafficIncidentおよびtraffic.IncidentSubscriptionを使用します。

注意:

サンプルのtraffic.*クラスは、Oracle Business Rulesに同梱されていません。

TrafficIncidentクラスは、交通状況に影響を与える事故の情報を表し、次のプロパティが含まれています。

どの高速道路か
上りか下りか
事故の種類
事故の発生時刻
渋滞の見積時間(分単位)

IncidentSubscriptionクラスは、特定の高速道路における事故の通知へのサブスクリプションを記述し、次のプロパティが含まれています。

サブスクライバ - サブスクライバの名前
該当する高速道路
上りか下りか

この例では、高速道路で交通状況に影響を与える事故が発生したとき、これらのクラスを使用してTrafficIncidentオブジェクトをアサートし、ルール評価によって通知の受信者を判断します。

例に示すsessオブジェクトはRuleSessionで、事故通知の多数のサブスクリプションがアサートされます。単純化するために、TrafficIncidentオブジェクトは永続的でないことを前提にしています。実際には、このオブジェクトはアサート対象イベントを表し、その時点で登録されているサブスクライバにのみ通知が送信されます。

この例で使用するクラスはすべてJavaクラスです。ただし、RLクラスの反映を使用して、JavaでRLクラスのインスタンスを操作することもできます。

5.6.2 外部リソースを使用した結果の取得

この方法は、結果用のコンテナをアサートする方法と同じです。ただし、コンテナではなくオブジェクトを使用して、ルール・エンジンの外部にあるリソースに作用します。たとえば、予定の作業をキューに挿入したりスケジュールする場合、データベースを更新する場合、メッセージを送信する場合が該当します。結果を導出するには、アクションでアクセス可能な任意のJavaメソッドを起動できます。コンテナを使用する場合と同様に、外部リソースにアクセスするためにこの例で使用されているオブジェクトは、その内容が推論の対象でないため、再度アサートされることはありません。

次の例に示すIncidentDispatcherオブジェクトは、アサートされて通知の配信に使用されます。

    rule incidentAlert
    {
        if (fact TrafficIncident ti &&
            fact IncidentSubscription s &&
                 s.highway == ti.highway &&
                 s.direction == ti.direction &&
            fact IncidentDispatcher dispatcher)
        {
            dispatcher.dispatch(s.subscriber, ti);
        }
    }

例5-1に示すJavaコードはIncidentDispatcherおよびTrafficIncidentをアサートし、ルール・エンジンを起動します。これは、推論の対象となるオブジェクトを使用しても実行できます。ただし、この場合は、ルール起動の無限ループを回避するために、ルール条件のテストが必要になります。

例5-1 外部リソースを使用した結果の例

        sess.callFunctionWithArgument("assert", new IncidentDispatcher());
 
        // An accident has happened
        TrafficIncident ti = new TrafficIncident();
        ti.setHighway("I5");
        ti.setDirection("south");
        ti.setIncident("accident");
        ti.setWhen(new GregorianCalendar(2005, 1, 25, 5, 4));
        ti.setDelay(45);
 
        sess.callFunctionWithArgument("assert", ti);
        sess.callFunction("run");

5.7 RLスタック・トレースのデバッグ

ランタイムでは、RLスタック・トレースに詳細なデバッグ情報が提供されます。エラーが発生した場合は、可能なかぎり、問題箇所の識別に役立つ特別なコンテキストが提供されます。この特別なコンテキストは、ルールSDKとルール・デザイナを併用している場合に有効です。

スタック・トレースには、ルール条件、ルール・アクション、関数、変数およびRLクラス定義に関する情報を示す特別なコンテキストが含まれています。XPath形式のフォーマットは、RL構成とそれに続くカッコで囲まれた名前(名前が指定されている場合)で構成されます。構成の後に大カッコで囲まれた番号nが表示される場合は、前の構成に続いてn番目の項目を示します。ルールSDKと併用している場合、ルール・デザイナでは、RL生成によってエラーの場所を非常に特定しやすくなります。

たとえば、例5-2に示されたルールセットについて考えてみます。このルールセットを実行すると、次のレポートが提供されます。

RLNullPointerException: object cannot be null
    at line 12 column 13 in stackTraceContext /Rule(porsche)/Pattern(car)/Test[1]
    at line 17 column 5 in stackTraceContext

例5-2 テスト・ルールセット

ruleset stackTraceContext
{
    class Car
    {
        String make;
        String model;
    }

    rule porsche
    {
        if (fact Car car &&
            car.make.startsWith("Porsche"))
        {
            println(car.make + " " + car.model);
        }
    }

    assert(new Car());
}

ruleset stackTraceContext
{
class Car
{
String make;
String model;
}
rule porsche
{
if (fact Car car &&
car.make.startsWith("Porsche"))
{
 
println(car.make + " " + car.model);
}
}
assert(new Car());

5.8 RuleSessionプールの使用

ルールを使用する典型的なアプリケーションでは、個々のリクエストに対応する異なるファクトを使用して、同じルールを何回も評価します。RuleSessionの初期化に要する時間は、含まれているルールの数によって異なりますが、通常は数秒です。

これに対し、ルールの実行に必要なのは、初期化よりはるかに短い時間です。したがって、RuleSessionを1回初期化し、新規の各リクエストに対して再利用することで、パフォーマンスを向上させることができます。RuleSessionプールを使用すると、RuleSessionインスタンスのプールを作成できるため、ルールを使用するアプリケーションのパフォーマンスとスケーラビリティが向上します。

RuleSessionプールは、ルール、型、関数の共通の定義をプール内のすべてのセッションで共有します。これにより、同じ数の個別のセッションを使用する場合と比較してメモリー消費量を大幅に削減できます。この共有により、新規セッションを元のルール言語テキストから作成する必要がなくなるため、新規セッションを作成するコストも大幅に低減されます。

5.8.1 RuleSessionプールの作成方法

負荷の増加に対応したパフォーマンスを実現するには、複数のRuleSessionが必要です。RuleSessionインスタンスのプールにより、ルールを使用するアプリケーションのパフォーマンスとスケーラビリティが向上します。プールは、RLコードのリストを使用してインスタンス化されます。RLコードは、プールで作成された各RuleSessionを初期化するために使用されます。RLコードは、リストに記載されている順に実行されます。最初に作成するRuleSessionインスタンスの数を指定できます。一般的には小さい値を指定しますが、通常は、このデフォルト値で十分です。

アプリケーションで使用中のルールが更新された場合は、後続のルール実行で新しいルールが使用されるように、アプリケーションは新しいルールをロードする必要があります。これをプールでサポートするには、refreshPoolメソッドを起動して新しいRLのリストを渡します。プールが更新されると、getPoolableRuleSessionで戻されるRuleSessionは、新しいRLコードで初期化されています。更新前に取得されたRuleSessionがreturnPoolableRuleSessionを使用して戻された場合、そのRuleSessionはプールに戻されません。更新後のプールに保存されるのは、新しいRLコードで初期化されたRuleSessionのみです。

RLコードは通常、ルールSDKで作成されたRuleDictionaryから生成されます。例5-3は、RuleDictionaryから生成されたRLコードでRuleSessionPoolを作成および使用する方法を示しています。

例5-3 RuleSessionプールの作成

     RuleDictionary rd;
     // Code to load rule dictionary not shown
     List rlList = new ArrayList();
     rlList.add(rd.dataModelRL());
     List rulesetAliases = rd.getRuleSetAliases(true);
     for (String alias : rulesetAliases)
     {
         rlList.add(rd.ruleSetRL(alias));
     }
 
     RuleSessionPool pool = new RuleSessionPool(rlList);

5.8.2 RuleSessionプールの使用方法

RuleSessionを使用してルールを実行する場合は、プールからRuleSessionを取得し、実行後にプールに戻します。プール可能なRuleSessionを取得するには、getPoolableRuleSessionメソッドを起動します。プールでは、必要に応じて新しいRuleSessionが作成されます。getPoolableRuleSessionの起動は、空きRuleSessionの待機を妨げることはありません。

RuleSessionPoolは、RuleSession構成パラメータのマップを使用して作成できます。また、プール内のすべてのセッションは指定どおりに構成されます。

ルール実行の完了後、プール可能なRuleSessionをプールに戻すには、returnPoolableRuleSessionメソッドを起動します。プールに戻されたRuleSessionをプールでリセットするには、組込みRL関数のreset()を起動します。これによって、作業メモリーからすべてのファクトが削除され、そのRuleSessionは次の実行のために準備されます。プールから取得したすべてのRuleSessionは、プールに戻す必要があります。ルールの実行中に発生したエラーが原因で今後の使用に適さなくなったRuleSessionは、プールで検出されて廃棄されます。

reset()関数は、作業メモリーの消去に加えて、非ファイナル・グローバル変数のイニシャライザを再実行します。非ファイナル・グローバル変数のイニシャライザを使用すると、必要な場合は、リセット時に他の初期化を実行できます。

次のコード例は、プールからRuleSessionを使用する方法を示しています。

     PoolableObject po = pool.getPoolableRuleSession();
     RuleSession engine = po.getPooledObject();
     // use the RuleSession to execute rules as required here
     pool.returnPoolableRuleSession(po);

プールのサイズに対するソフト上限を指定できます。この指定によって、一時的な需要の増加に対応するためにプールを拡大する一方、需要の減少時には、プールをソフト上限まで縮小できます。

getPoolableRuleSessionメソッドが起動されてプールが空の場合には、RuleSessionプールの実装を使用してRuleSessionインスタンスを作成します。負荷が非常に大きい場合は、ソフト制限を超えるインスタンス件数になります。

負荷の減少に従って、プール内のRuleSessionインスタンスの数は、ソフト制限まで自動的に減少します。

5.9 RuleSessionオプションの使用

RuleSessionを使用したRLランタイムは、次のオプションをサポートしています。

次のオプションがサポートされます。

RuleSession.CFG_LOGGING
RuleSession.CFG_DECISION_TRACE_LEVEL
RuleSession.CFG_DECISION_TRACE_LIMIT

5.9.1 CFG_LOGGINGシステム・プロパティの使用

RL Languageランタイムでは、システム・プロパティとしてのCFG_LOGGINGと、RuleSessionコンストラクタに渡される構成マップのBooleanが検索されます。システム・プロパティの値は、マップの値でオーバーライドされます。

5.9.2 CFG_DECISION_TRACE_LEVELオプションの使用

RuleSession.CFG_DECISION_TRACE_LEVEL初期化パラメータをインクルードして、RuleSessionまたはRuleSessionPoolコンストラクタに渡される構成マップのレベルを指定することで、RuleSessionまたはRuleSessionPoolのトレース・レベルを構成できます。これはRuleSessionの作成時のデシジョン・トレース・レベルを設定します。reset()を起動すると、reset()の後、ルール実行中にレベルが変更されていた場合にレベルを構成値に戻すことができます。詳細は、「ルール・エンジン・レベルのデシジョン・トレースの使用方法」を参照してください。

5.9.3 CFG_DECISION_TRACE_LIMITオプションの使用

トレースのサイズは、デシジョン・トレース内のエントリ数を制限することで制限します。JVM内で使用可能なすべてのヒープを消費するトレースを作成することから、ルール内の不具合の可能性があるため、ルール起動の無限ループを回避するために制限が必要となります。トレースの制限は、setDecisionTraceLimit関数を使用して設定します。この制限は、RuleSession (またはRuleSessionPool)で構成することも可能です。構成するには、RuleSessionまたはRuleSessionPoolコンストラクタに渡される構成マップに目的の制限を指定したRuleSession.CFG_DECISION_TRACE_LIMIT初期化パラメータをインクルードします。詳細は、「ルール・エンジン・レベルのデシジョン・トレースの使用方法」を参照してください。

5.10 デシジョン・トレースの使用

Oracle Business Rulesでは、デシジョン・トレースはルール・エンジンの実行のトレースです。これには、ルールを起動したときのファクトの状態など、ルール・エンジンの状態に関する情報が含まれます。

Oracle Business Rulesのルール・エンジンは、デシジョン・トレースXMLスキーマから、JAXBで生成されたJavaクラスを使用してデシジョン・トレースを構成し、戻します。

5.10.1 ルール・エンジン・レベルのデシジョン・トレースの概要

デシジョン・トレースをビジネス・アナリストにわかりやすく表示するには、関連付けられているルール・ディクショナリを利用できる必要があります。トレースに関連付けられているルール・ディクショナリを使用すると、トレースの出力に、トレース内にある関連するディクショナリのすべてのコンテンツ情報を含める必要がなくなるため、より柔軟性があり効率的なアプローチが可能になります。

XMLスキーマは、ファイルdecisiontrace.xsd内にあり、これはJarファイルrl.jarの一部です(oracle/rules/rl/trace/decisiontrace.xsd)。該当するパッケージは、oracle.rules.rl.trace、oracle.rules.rl.extensions.traceおよびoracle.rules.sdk2.decisiontraceです。decisiontrace XMLスキーマから生成されたJavaクラス・パッケージは、パッケージoracle.rules.rl.trace内にあり、Javadocに含まれています。詳細は、Oracle Business Rules Java APIリファレンスを参照してください。

5.10.2 ルール・エンジン・レベルのデシジョン・トレースの使用

デシジョン・トレースは、一連のXML要素であり、ルールの評価中に発生したルール・エンジン・イベントを示しています。デシジョン・トレースに追加されるイベントの種類は、指定したトレース・レベルによって決まります。次のようなイベントが含まれます。

ファクト操作(アサート、撤回、変更)
ルールの起動
アジェンダで追加または削除されたルールのアクティブ化
ルールセット・スタックの変更
ルールのコンパイル
リセット(デシジョン・トレース分析で状態を維持するために必要)

各トレースには、特定のイベントに関する情報が含まれます。たとえば、ファクト操作のイベント・エントリは次の内容で構成されます。

操作の種類(アサート、変更、撤回)
作業メモリー内のファクトのID
ファクト・タイプ名(RL内のファクト・クラス)
ランタイム・オブジェクト・タイプ名
ファクト・オブジェクト・データ(ゼロ個以上のファクト・プロパティのプロパティ名と値など)
操作がルール・アクションの結果であった場合は、ルール名、RL名
ミリ秒単位のタイムスタンプ

ファクト操作のイベント・トレースでは、ファクト・オブジェクトのコンテンツはJava Beanとしてのオブジェクトの構造を反映します。Beanプロパティが他のBeanへの参照の場合、関連するBeanのコンテンツがトレースに含まれます。Beanプロパティの値は、次のいずれかになります。

プロパティの文字列表現。これは、java.*およびjavax.*パッケージのプリミティブ型およびクラスである場合です。
それぞれのプロパティ値を持つ、ネストされたBeanオブジェクト。
ファクトID。これは、プロパティ値がオブジェクトであり、オブジェクト自身がファクトとしてアサートされている場合に発生します。トレースの時点でのファクトのデータは、トレース分析時のファクトIDを使用することでRuleEngineStateから取得できます。
トレースでListとしてアクセスされる値のコレクション。
トレースでListとしてアクセスされる値の配列。

トレースに含まれる値がどれになるかを実行時に調べるには、nullに対してテストします。null以外の値を持つのは、正しい値のみです。

表5-3に、ルール・エンジンでデシジョン・トレースを制御したりデシジョン・トレースにアクセスするRL関数を示します。

表5-3 RLデシジョン・トレース関数

関数	説明
`getDecisionTrace`	現在のトレースを戻し、新しいトレースを開始します。
`getDecisionTraceLevel`	現在のデシジョン・トレース・レベルを取得します。
`getDecisionTraceLimit`	トレース内のイベント数に対する現在の制限値を戻します。
`setDecisionTraceLevel`	デシジョン・トレース・レベルを指定したレベルに設定します。
`setDecisionTraceLimit`	トレース内のイベント数の制限値を設定します。デフォルトの制限値は10000です。

5.10.2.1 デシジョン・トレース・レベルの設定

デシジョン・トレース・レベルは、setDecisionTraceLevel関数を起動することで設定できます。RuleSession.CFG_DECISION_TRACE_LEVEL初期化パラメータをインクルードして、RuleSessionまたはRuleSessionPoolコンストラクタに渡される構成マップのレベルを指定することで、RuleSessionまたはRuleSessionPoolの初期トレース・レベルを構成することもできます。これはRuleSessionを作成する時点でのデシジョン・トレース・レベルを設定します。

setDecisionTraceLevel関数は初期化後にRuleSessionまたはRuleSessionPoolオブジェクトで起動できます。reset()を起動すると、この関数によりデシジョン・トレース・レベルが構成値に戻されます(ルール実行中にレベルが変更された場合)。したがって、reset()関数はデシジョン・トレースの制限を、RuleSessionまたはRuleSessionPoolの初期化で設定した値にリセットします。このような場合、reset()は初期化パラメータを使用して指定された値をリストアします。

注意:

こうしたRuleSessionに対するreset()のセマンティクスは、CFG_DECISION_TRACE_LIMITまたはCFG_DECISION_TRACE_LEVELあるいはその両方の初期化パラメータを使用して初期化された (または、プールがCFG_DECISION_TRACE_LIMITまたはCFG_DECISION_TRACE_LEVELあるいはその両方の初期化パラメータを使用して作成されている場合に、RuleSessionPoolから取得した)RuleSessionに対してのみ有効です。

トレースのサイズは、デシジョン・トレース内のエントリ数を制限することで制限します。JVM内で使用可能なすべてのヒープを消費するトレースを作成することから、ルール内の不具合の可能性があるため、ルール起動の無限ループを回避するために制限が必要となります。トレースの制限は、setDecisionTraceLimit関数を使用して設定します。この制限は、RuleSession (またはRuleSessionPool)で構成することも可能です。構成するには、RuleSessionまたはRuleSessionPoolコンストラクタに渡される構成マップに目的の制限を指定したRuleSession.CFG_DECISION_TRACE_LIMIT初期化パラメータをインクルードします。

runUntilHaltを使用するルール・アプリケーションでは、トレースの制限に達する前にアプリケーションでgetDecisionTraceを呼び出す必要があります。

デシジョン・トレースは、トレース・データに構造を提供し、これをプログラム的に操作できるようにします。ただし、トレース自体は分析するには、扱いにくい場合があります。トレース分析クラス(oracle.rules.rl.extensions.trace.TraceAnalysis)は、デシジョン・トレースを分析し、トレースの内容を調べやすくします。このクラスを使用して作業メモリー、アジェンダおよびルールセット・スタックの状態をトレースから構成します。

TraceAnalysis APIは次をサポートします。

トレース内に現れるファクト・タイプのリストの取得。
トレース内で起動されたルールの名前のリストの取得。
特定のファクト・タイプの各インスタンスに対する最終ファクト・トレースのリストの取得。
ファクトIDで指定された特定のファクトに対する最終ファクト・トレースの取得。
ファクトIDで指定されたファクトに対するすべてのファクト・トレースの取得。
ファクト・トレースで、ファクト・トレースがルール・アクションによって作成された場合に、アクションが実行されるルールの起動のルール・トレースの取得。
ルール・トレースで、一致してルールが起動された各ファクトに対するファクト・トレースのリストの取得。
次または前のトレースの取得。トレースの調査は通常、トレースの反復ではありません。たとえば、あるファクト・トレースからルール・トレースを取得することは、本質的にはそのルール・トレースへのジャンプです。そのルール・トレースの周囲のトレースは直接調べることができます。
名前で指定されたルールに対するルール・トレースのリストの取得。
トレース・エントリに対するルール・エンジンの状態の取得。ルール・エンジンの状態は、トレースを生成したアクティビティの後のルール・エンジンの状態を反映します。このAPIを使用することで、各トレースの時点でのルール・エンジンの状態を調べることができます。このAPIは開発レベルのトレースで最も役立ちます。本番レベルのトレースでは、追跡できるのは作業メモリー内にあるファクトのみで、それにはファクトの内容は含まれていません。

例5-4に、デシジョン・トレース分析APIを使用したコード・サンプルを示します。

例5-4 デシジョン・トレース分析APIの使用方法

DecisionTrace trace;
...
TraceAnalysis ta = new TraceAnalysis(trace);
// Get all of the last fact traces for a fact type.
List<FactTrace> factTraces = ta.getLastFactTraces("com.example.MyFactType");
// From a particular fact trace, how it was arrived at may be explored, first by
// obtaining the rule that asserted or modified the fact.
// From the FactRecord, the rule that resulted in the record can be obtained.
FactTrace factTrace = factTraces.get(0);  // assumes there is one
RuleTrace ruleTrace = ta.whichRule(factTrace);
  // The ruleTrace will be null if the fact operation was not part of a rule action.
System.out.print("Fact " + factTrace.getFactId() + ", a " + factTrace.getFactType() + " " + factRecord.getFactOp());
if (ruleTrace != null)
    System.out.println(" by rule " + ruleTrace.getRuleName());
else
    System.out.println("");
// The analysis can continue by obtaining the list of FactRecords that matched the rule and
// proceeding to analyze the trace back in time.
List<FactTrace> matchingFacts = ta.getRuleMatchedFacts(ruleTrace);

5.10.3 本番レベルおよび開発レベルのトレース用のデシジョン・トレースのサンプル

例5-5に、本番レベルのトレース・ドキュメントのサンプルを示します。

例5-5 本番レベルのデシジョン・トレースのサンプル

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<decision-trace xmlns="http://xmlns.oracle.com/rules/decisiontrace">
    <trace-entries xsi:type="rule-trace" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <timestamp>1248975549890</timestamp>
        <rule-name>OrderDiscount.goldCustomer</rule-name>
        <token-time>0</token-time>
        <sequence-number>1</sequence-number>
    </trace-entries>
    <trace-entries xsi:type="rule-trace" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <timestamp>1248975549893</timestamp>
        <rule-name>OrderDiscount.goldCustomerDiscount</rule-name>
        <token-time>0</token-time>
        <sequence-number>2</sequence-number>
    </trace-entries>
    <trace-entries xsi:type="rule-trace" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <timestamp>1248975549894</timestamp>
        <rule-name>OrderDiscount.applyDiscount</rule-name>
        <token-time>0</token-time>
        <sequence-number>3</sequence-number>
    </trace-entries>
</decision-trace>

5.10.4 開発レベルのデシジョン・トレースのサンプル

例5-6に、開発レベルのディジョン・トレース・ドキュメントのサンプルを示します。

例5-6 開発レベルのデシジョン・トレースのサンプル

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<decision-trace xmlns="http://xmlns.oracle.com/rules/decisiontrace">
    <trace-entries xsi:type="fact-trace" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <timestamp>1248975491008</timestamp>
        <fact-id>1</fact-id>
        <operation>assert</operation>
        <fact-type>com.example.Customer</fact-type>
        <object-type>com.example.Customer</object-type>
        <fact-object>
            <properties>
                <name>YTDOrderAmount</name>
                <value>
                    <string>2000.0</string>
                </value>
            </properties>
            <properties>
                <name>level</name>
                <value>
                    <string>null</string>
                </value>
            </properties>
            <properties>
                <name>name</name>
                <value>
                    <string>OneLtd</string>
                </value>
            </properties>
            <properties>
                <name>pastDue</name>
                <value>
                    <string>false</string>
                </value>
            </properties>
        </fact-object>
    </trace-entries>
    <trace-entries xsi:type="activation-trace" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <timestamp>1248975491024</timestamp>
        <rule-name>OrderDiscount.goldCustomer</rule-name>
        <token-time>2</token-time>
        <fact-ids>1</fact-ids>
        <operation>add</operation>
    </trace-entries>
    <trace-entries xsi:type="fact-trace" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <timestamp>1248975491025</timestamp>
        <fact-id>2</fact-id>
        <operation>assert</operation>
        <fact-type>com.example.Order</fact-type>
        <object-type>com.example.Order</object-type>
        <fact-object>
            <properties>
                <name>customerName</name>
                <value>
                    <string>OneLtd</string>
                </value>
            </properties>
            <properties>
                <name>discount</name>
                <value>
                    <string>0.0</string>
                </value>
            </properties>
            <properties>
                <name>grossAmount</name>
                <value>
                    <string>400.0</string>
                </value>
            </properties>
            <properties>
                <name>netAmount</name>
                <value>
                    <string>0.0</string>
                </value>
            </properties>
            <properties>
                <name>number</name>
                <value>
                    <string>1001</string>
                </value>
            </properties>
        </fact-object>
    </trace-entries>
    <trace-entries xsi:type="activation-trace" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <timestamp>1248975491035</timestamp>
        <rule-name>OrderDiscount.goldCustomerDiscount</rule-name>
        <token-time>5</token-time>
        <fact-ids>2</fact-ids>
        <fact-ids>1</fact-ids>
        <operation>add</operation>
    </trace-entries>
    <trace-entries xsi:type="rule-trace" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <timestamp>1248975491036</timestamp>
        <rule-name>OrderDiscount.goldCustomerDiscount</rule-name>
        <token-time>5</token-time>
        <fact-ids>2</fact-ids>
        <fact-ids>1</fact-ids>
        <sequence-number>2</sequence-number>
    </trace-entries>
...
    <trace-entries xsi:type="rule-trace" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <timestamp>1248975491036</timestamp>
        <rule-name>OrderDiscount.applyDiscount</rule-name>
        <token-time>7</token-time>
        <fact-ids>2</fact-ids>
        <sequence-number>3</sequence-number>
    </trace-entries>
...
    <trace-entries xsi:type="ruleset-stack-trace" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <timestamp>1248975491037</timestamp>
        <operation>pop</operation>
        <ruleset-name>OrderDiscount</ruleset-name>
    </trace-entries>
</decision-trace>