ランタイム・サービスの使用

19 ランタイム・サービスの使用

この章では、Oracle Enterprise Schedulerランタイム・サービスAPIを使用して、ジョブ・リクエストを発行および管理し、ジョブ・リクエスト履歴からジョブ・リクエスト情報を問い合せる方法について説明します。

ノート:

ランタイム・サービスには、ログおよび出力APIも含まれます。これらのAPIについては、「ジョブ・リクエスト・ログと出力」で別々に説明します。

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

19.1 ランタイム・サービスの概要

Oracle Enterprise Schedulerを使用すると、Javaクラス、PL/SQLプロシージャおよびプロセス・ジョブ・タイプ(分岐プロセス)など、様々なジョブ・タイプを定義して実行できます。これらのジョブ・タイプを実行するには、ジョブ定義を発行する必要があります。

ランタイム・サービスを使用して、次のような様々なタイプの操作を実行できます。

発行: これらの操作では、Oracle Enterprise Schedulerにジョブ定義を提供して、ジョブ・リクエストを作成できます。
管理: これらの操作では、ジョブ・リクエストの状態を変更して、ジョブ・リクエストを更新できます。
問合せ: これらの操作では、ジョブ・リクエストの状態とレポート・ジョブ・リクエスト履歴を確認できます。

19.2 ランタイム・サービスへのアクセス

メタデータ・サービスと同様に、Oracle Enterprise SchedulerではランタイムMBeanプロキシ・インタフェースを提供します。

ランタイム・サービスのopen()メソッドにより、各Oracle Enterprise Schedulerランタイム・サービス・ユーザー・トランザクションが開始されます。Oracle Enterprise Schedulerアプリケーション・クライアントでは、open()により作成されるRuntimeServiceHandle参照を取得して、その参照をランタイム・サービス・メソッドに渡します。RuntimeServiceHandle参照により、クライアント・アプリケーションにランタイム・サービスへの接続が提供されます。クライアント・アプリケーションでは、close()をコールしてランタイム・サービスを明示的に終了する必要があります。これによりトランザクションが終了し、トランザクションがコミットまたはロールバック(取消し)されます。close()はランタイム・サービス内のトランザクション動作を制御するだけでなく、Oracle Enterprise SchedulerによりRuntimeServiceHandleに関連付けられているリソースを解放できるようにします。

19.2.1 ランタイム・サービスにアクセスしてランタイム・サービス・ハンドルを取得する方法

Oracle Enterprise Schedulerでは、アプリケーション・プログラムに対して、ランタイム・サービスをステートレス・セッションEnterprise Java Bean (EJB)として公開します。Oracle Enterprise Schedulerランタイム・サービスのステートレス・セッションEJBを見つけるために、JNDIを使用できます。

例19-1に、RuntimeServiceLocalHomeオブジェクトを使用したOracle Enterprise Schedulerランタイム・サービスのルックアップを示します。

ノート:

ランタイム・サービスにアクセスするときは、次のことに注意してください。

JndiUtil.getRuntimeServiceEJB()では、RuntimeService EJBがローカルのJNDIロケーション"ess/runtime"にマップされていることを前提としています。これは、ホストされているアプリケーションのメッセージドリブンBean (MDB)内で自動的に行われます。
open()コールによって、RuntimeServiceHandle参照が提供されます。この参照は、アプリケーション・プログラム内の、ランタイム・サービスにアクセスするメソッドで使用します。
ランタイム・サービスの使用が終了したら、close()をコールして、RuntimeServiceHandleに関連付けられているリソースを解放する必要があります。

例19-1 Oracle Enterprise Schedulerランタイム・サービスにアクセスするためのJNDIルックアップ

import oracle.as.scheduler.core.JndiUtil;
// Demonstration of how to lookup runtime service from a
// Java EE application component
    
    RuntimeService runtime = JndiUtil.getRuntimeServiceEJB();
    RuntimeServiceHandle rHandle = null;
    .
    .
    .
    try
    {
         ...
         rHandle = runtime.open();
         ...
    }
    finally
    {
        if (rHandle != null)
        {
            runtime.close(rHandle);
        }
    }

19.3 ジョブ・リクエストの発行

ジョブ定義の発行時に、新しいジョブ・リクエストを作成します。

メタデータ・リポジトリで維持されているジョブ定義を使用してジョブ・リクエストを発行するか、ジョブ定義またはスケジュールがメタデータ・リポジトリに格納されない非定型方式でジョブ・リクエストを作成できます(非定型リクエストの詳細は、「非定型ジョブ・リクエストの発行」を参照してください)。

19.3.1 ランタイム・サービスへのリクエストの発行方法

ジョブ・リクエストを作成するには、submitRequest()をコールします。必要に応じて、次のいずれかの形式でジョブ・リクエストを作成できます。

特定の時間に1回のみ実行する場合は、メタデータ・リポジトリに格納されているジョブ定義を使用して、新しいジョブ・リクエストを作成します。
メタデータ・リポジトリに格納されている各ジョブ定義とスケジュールを使用して、新しいジョブ・リクエストを作成します。

例19-2に、メタデータ・リポジトリに常駐するジョブ定義を使用して新しいジョブ・リクエストを作成するsubmitRequest()メソッドを示します。また、ジョブ定義とスケジュールがメタデータ・リポジトリに格納されない、非定型ジョブ・リクエストを発行することもでます。詳細は、「非定型ジョブ・リクエストの発行」を参照してください。サブリクエストを発行することもできます。詳細は、「サブリクエストの使用」を参照してください。

ノート:

ランタイム・サービスを使用してジョブ・リクエストを発行するときには、次のことに注意してください。

例19-1に示されているように、ランタイム・サービス・ハンドルを取得します。
ランタイム・サービスでは、メタデータ・サービスを内部的に使用して、指定されたMetadataObjectId、jobDefnIdを持つジョブ定義メタデータを取得します。

例19-2 submitRequest()によるジョブ・リクエストの作成

long requestID = 0L;
MetadataObjectId jobDefnId;
 
RequestParameters p = new RequestParameters();
 
Calendar start = Calendar.getInstance();
start.add(Calendar.SECOND, startsIn);
 
requestID = runtime.submitRequest(r, "My Java job", jobDefnId, start, p);

19.3.2 リクエスト発行時のデフォルト・システム・プロパティに関する注意事項

ジョブ・リクエストを作成するとき、Oracle Enterprise Schedulerによって、ジョブ・リクエストに関連付けられているプロパティが解決および格納されます。特定のシステム・プロパティを、ジョブ・リクエストと関連付けることができます。ジョブ・リクエストが発行されたとき、これらのプロパティをプロパティ階層内に設定していなかった場合は、Oracle Enterprise Schedulerによってデフォルト値が提供されます。

表19-1に、デフォルト・ランタイム・サービス・フィールド名と対応するシステム・プロパティを示します。

表19-1 ランタイム・サービスのデフォルト値フィールドと対応するシステム・プロパティ

値	ランタイム・サービスのデフォルト値フィールド	対応するシステム・プロパティ	説明
0	`DEFAULT_REQUEST_EXPIRATION`	`SYS_requestExpiration`	リクエストのデフォルト有効期限(分数)。デフォルト値は、リクエストが有効期限切れにならないことを意味する0です。
4	`DEFAULT_PRIORITY`	`SYS_priority`	リクエストに関連付けられているデフォルトのシステム優先度。
5	`DEFAULT_REPROCESS_DELAY`	`SYS_reprocessDelay`	`Action.DELAY`を返すコールアウト・ハンドラにより処理が延期されるデフォルトの時間(分数)。
0	`DEFAULT_RETRIES`	`SYS_retries`	失敗したリクエストのデフォルトの再試行回数。デフォルト値は0で、失敗したリクエストが再試行されないことを意味します。
0	`DEFAULT_ASYNC_REQUEST_TIMEOUT`	`SYS_request_timeout`	ジョブ実行が開始された後に、プロセッサが非同期レスポンスを待機する時間を分数で指定します。時間が経過した後、リクエストはタイムアウトになります。

19.3.3 リクエスト発行時のメタデータに関する必知事項

ジョブ・リクエストに関連付けられているすべてのOracle Enterprise Schedulerメタデータは、リクエストの発行時にランタイム・ストアに維持されます。維持されるメタデータ・オブジェクトには、ジョブ定義、ジョブ・タイプ、ジョブ・セット、スケジュール、非互換性定義および除外定義があります。メタデータは最上位レベルのリクエストのコンテキストに格納され、各メタデータ・オブジェクトは絶対親リクエストIDおよびそのメタデータIDによって一意に識別されます。最上位レベルのリクエストに対して、一意のメタデータ・オブジェクトはそれぞれ1回のみ格納され、これは、そのリクエスト内で定義が複数回使用されている場合も同様です。これにより、すべての子リクエストで必ず同じ定義が使用されます。

リクエストが発行されると、リクエストのすべての既知のメタデータが維持されます。サブリクエストの場合は、サブリクエストが発行されるまでメタデータが認識されないため、サブリクエスト・メタデータは、サブリクエストの発行時に、メタデータ・オブジェクトがすでにランタイム・ストアにおいて永続化されていないことが確認された後で、維持されます。

ランタイム・ストアに維持されたメタデータは、絶対親リクエストが削除されるときに削除されます。

19.3.4 DMS ECIDおよびFlowIdのサポート

Oracle Enterprise Schedulerは、DMS ECIDおよびFlowId値をすべてのリクエストに関連付けます。Oracle Enterprise Schedulerでは、通常、リクエストの発行時に現在のDMS実行コンテキストからECIDおよびFlowIdを取得し(存在する場合)、そのECIDおよびFlowId値を後続のリクエストの処理で使用します。たとえば、Oracle Enterprise Schedulerは、ジョブの実行可能ファイルを開始するときに、リクエストにECIDおよびFlowIdを関連付けるDMS実行コンテキストを設定します。

リクエストの発行時、DMS FlowIdプロパティがDMS実行コンテキスト内に存在しない場合、新規FlowIdはリクエストに関連付けられます。たとえば、リクエストがSOAによって発行されていない場合、DMS実行コンテキスト上にFlowIdが存在しない場合があり、Oracle Enterprise Schedulerによって新規FlowIdがリクエストと関連付けられます。

DMS実行コンテキストがリクエストの発行時に存在しない場合、新しいECIDおよびFlowIdがリクエストに関連付けられます。たとえば、リクエストがOracle Enterprise Scheduler PL/SQLインタフェースを使用して発行された場合、PL/SQL発行プロシージャがコールされたときにデータベース・セッションから使用できるDMSコンテキスト情報がない場合があります。新しいECIDおよびFlowIdが、Oracle Enterprise Schedulerの中間層によって検証が正常に完了した後、リクエストに関連付けられます。

19.3.4.1 子リクエストのECIDおよびFlowID

一般的に、子リクエストは、親リクエストからECIDおよびFlowIdを継承します。たとえば、ジョブ・セット・ステップ・リクエストの作成時、Oracle Enterprise Schedulerでは親リクエストのECIDおよびFlowIdが使用されます。

サブリクエストは発行済のリクエストであるため、サブリクエストの発行の現在のDMS実行コンテキストのECIDおよびFlowIdがサブリクエストに関連付けられます。通常、ECIDおよびFlowIdの値は、親リクエストの値と同じですが、これは親ジョブの実行可能ファイルを開始する前に、Oracle Enterprise Schedulerにより親リクエストのECIDおよびFlowIdが含まれるDMS実行コンテキストが設定されるためです。Oracle Enterprise Schedulerがサブリクエストの発行を受信する前に、アプリケーションまたは一部のコンポーネント・レイヤーによりECIDまたはFlowIdが変更される場合があります。その場合、親およびサブリクエストのECIDまたはFlowIdが異なる場合があります。

スケジュールがリクエストの発行時に指定されている場合、発行されるリクエストは実行されていない絶対親を表します。Oracle Enterprise Schedulerは、指定されたスケジュールに従って子インスタンス・リクエストを自動的に作成し、新しいECIDおよびFlowIdが各子インスタンスに使用されます。子インスタンス・リクエストは、インスタンスの親リクエストを表し、それ自体の子が含まれる場合があります(サブリクエストまたはジョブ・セット・ステップ・リクエストなど)。一般的にそのような子には、そのインスタンスの親リクエストと同じECIDおよびFlowIdが含まれます。

19.3.4.2 DMS FlowIdおよびSOA CorrelationFlowId

Oracle Enterprise Schedulerでは、プロパティ名がFlowIdであるDMS FlowIdプロパティが使用されます。SOAには、DMS実行コンテキストに存在している場合があるプロパティがいくつかあります。その2つのプロパティは、SOA CorrelationFlowIdおよびSOA FlowIdプロパティです。DMS FlowIdプロパティ(FlowId)は、SOA CorrelationFlowIdの値の伝播に使用されます。DMSプロパティ名"oracle.soa.tracking.FlowId"は、SOA FlowIdプロパティの値の伝播に使用されます。このため、SOAによって発行されるOracle Enterprise Schedulerリクエストに関連付けられているFlowIdプロパティは、SOA CorrelationFlowIdの値と一致する場合があります。

19.4 ジョブ・リクエストの管理

ジョブ・リクエストを発行した後、requestIDを使用して、次のことを実行できます:

リクエスト情報の取得
リクエストの状態の変更
リクエスト・パラメータの更新

19.4.1 getRequestDetailによるジョブ・リクエスト情報の取得方法

ランタイム・サービスをrequestIDとともに使用して、システム内に存在するジョブ・リクエストの情報を取得できます。表19-2に、ジョブ・リクエスト情報を取得できるようにするランタイム・サービス・メソッドを示します。

表19-2 ランタイム・サービスのGetリクエスト・メソッド

ランタイム・サービス・メソッド	説明
`getRequestDetail()`	指定したリクエストの完全なランタイム詳細を取得します。
`getRequestDetailBasic()`	指定したリクエストの基本的なランタイム詳細を取得します。このメソッドによって返されるRequestDetailには、ほとんどの情報が`getRequestDetail()`として含まれますが、使用頻度の低い特定の情報はパフォーマンスを向上させるために省略されます。
`getRequestParameter()`	リクエスト・パラメータの値を取得します。
`getRequests()`	指定したリクエストに関連付けられている直接的な子リクエスト識別子の列挙を取得します。これには、完了していないリクエストのIDが含まれます(リクエスト・トランザクションがロールバックされる場合や、エラーが発生した場合など)。
`getRequestState()`	指定したリクエストの現在の状態を取得します。

例19-3 に、HOLD状態にある直接的な子リクエストがあるかどうかを判別するコードを示します。

例19-3 直接的な子のジョブ・リクエストが保留中であるかどうかの判別

        h = s_runtime.open();
        try {
 
            s_runtime.holdRequest(h,reqid);
 
            Enumeration  e = s_runtime.getRequests(h, reqid);
 
            boolean foundHold = false;
            while (e.hasMoreElements()) {
 
                long childid = ((Long)e.nextElement()).longValue();
                State state = s_runtime.getRequestState(h,childid);
                if (state == State.HOLD) {
                    foundHold = true;
                    break;
                }
            }

19.4.2 ジョブ・リクエスト状態の変更方法

ランタイム・サービスをrequestIDとともに使用して、ジョブ・リクエストの状態を変更できます。表19-3に、ランタイム・サービスのジョブ・リクエスト状態変更メソッドを示します。ジョブ・リクエスト管理メソッドを使用すると、ジョブ・リクエストの状態によっては、リクエストの状態を変更できます。たとえば、リクエストがCOMPLETED状態である場合は、cancelRequest()でリクエストを取り消すことはできません。

表19-3 ランタイム・サービスのジョブ・リクエスト状態メソッド

ランタイム・サービス・メソッド	説明
`cancelRequest()`	終了状態にないリクエストの処理を取り消します。
`deleteRequest()`	終了状態にあるリクエストを削除対象としてマークします。
`holdRequest()`	`WAIT`または`READY`状態にあるリクエストのそれ以降の処理を保留にします。
`releaseRequest()`	リクエストの`HOLD`状態を解除します。

例19-4に、submitRequest()とジョブ・リクエストの状態を制御するメソッドを示します。holdRequest()は、ジョブ・リクエストの処理を保留にします。対応するreleaseRequest()によって、リクエストが解放されます。この例では、リクエストを保留にする必要がある条件は示しません。

ノート:

例19-4について、次のことに注意してください。

例19-1に示されているように、ランタイム・サービス・ハンドルrHandleを取得します。
holdRequest()によって、リクエストがHOLD状態になります。
リクエストがHOLD状態にある間も、必要な一部の処理を実行できます。
releaseRequest()によって、リクエストのHOLD状態が解除されます。

例19-4 ランタイム・サービスのreleaseRequest()の使用

rHandle = runtime.open();
try 
{
            runtime.holdRequest(rHandle,reqid);
.
.
.
            runtime.releaseRequest(rHandle, reqid);
.
.
.
}
finally
{
        if (rHandle != null)
        {
            runtime.close(rHandle);
        }
 }

19.4.3 ジョブ・リクエストの優先度とジョブ・リクエスト・パラメータの更新方法

ランタイム・サービスを使用して、ジョブ・リクエストのシステム・プロパティまたはリクエスト・パラメータを更新できます。表19-4に、ジョブ・リクエストをロックおよび更新できるようにするランタイム・サービス・メソッドを示します。

表19-4 ランタイム・サービスの更新メソッド

ランタイム・サービス・メソッド説明

ランタイム・サービス・メソッド	説明
`lockRequest()`	指定されたリクエストのロックを取得します。ロックは、`close()`操作がその後で起動されるか、またはそのロックを包含するトランザクションがコミットされると解放されます。他のスレッドによってロックが保持されているときに、アプリケーションがこの操作の起動を試みると、このメソッドはロックが解放されるまでブロックされます。このメソッドは、リクエスト・パラメータまたはシステム・プロパティを更新する際に、データの一貫性を確保するために使用します。
`setRequestParameter(`)	指定されたリクエスト・サブジェクトのプロパティ値を、プロパティの読取り専用制約に更新します。

lockRequest()

指定されたリクエストのロックを取得します。ロックは、close()操作がその後で起動されるか、またはそのロックを包含するトランザクションがコミットされると解放されます。他のスレッドによってロックが保持されているときに、アプリケーションがこの操作の起動を試みると、このメソッドはロックが解放されるまでブロックされます。このメソッドは、リクエスト・パラメータまたはシステム・プロパティを更新する際に、データの一貫性を確保するために使用します。

setRequestParameter()

指定されたリクエスト・サブジェクトのプロパティ値を、プロパティの読取り専用制約に更新します。

例19-5に、ジョブ・リクエスト・パラメータを更新するコードを示します。例19-1に示されているように、このコードはtry/finallyブロック内に含められます。

例19-5は、次のことを示しています。

例19-1に示されているように、ランタイム・サービス・ハンドルrhandleを取得します。
lockRequest()を使用して、いずれかのリクエストにロックを取得します。
setRequestParameter()により更新操作を実行します。
close()を使用して、トランザクションをコミットまたはロールバック(取消し)します。close()はランタイム・サービス内のトランザクション動作を制御するだけでなく、Oracle Enterprise SchedulerによりRuntimeServiceHandleに関連付けられているリソースを解放できるようにします。

例19-5 ランタイム・サービス・パラメータの更新のサンプル

...
  s_runtime.lockRequest(rhandle, reqid);
  s_runtime.setRequestParameter(rhandle, reqId, paramName, "yy");
...

19.5 ジョブ・リクエストの問合せ

ランタイム・サービスを使用して、ジョブ・リクエスト情報を問い合せることができます。

これを行うには次のステップが必要になります。

リクエスト識別子の問合せとフィルタによる結果の制限。
問合せにより返される各リクエストIDの追加情報を提供するためのリクエスト詳細の取得。

問合せメソッドは、ランタイム・サービスのqueryRequests()メソッドの1つのみです。このメソッドにより、問合せに一致するリクエストIDの列挙が返されます。queryRequests()メソッドには、問合せ結果の選択に役立つフィールド、コンパレータおよび値の組合せが格納されたフィルタ引数が含まれます。戻り値には、完了していないリクエストのIDが含まれます(リクエスト・トランザクションがロールバックされる場合や、エラーが発生した場合など)。フィルタの詳細は、「フィルタの作成方法」を参照してください。

問合せにフィルタを作成すると、ランタイム・ストアを問い合せるときに、表19-5に示されているいずれかのフィールド名を使用できます。

表19-5 ランタイムの問合せ用の問合せフィルタ・フィールド(列挙RuntimeService.QueryFieldで定義)

名前	説明
`ABSPARENTID`	リクエストの絶対親リクエストID。
`APPLICATION`	アプリケーション名。
`ASYNCHRONOUS`	ジョブが非同期、同期または不明のいずれであるかを示します。フィールドの値は、リクエストが処理されるまで設定されません。フィールドのデータ型は`java.lang.Boolean`です。ジョブの性質がまだ決定されていない場合、この値は`NULL`にできます。
`CLASSNAME`	リクエストを処理した実行可能クラスの名前。
`COMPLETED_TIME`	Oracle Enterprise Schedulerでリクエストの処理が終了した日時。このフィールドは、プロセス・フェーズがCOMPLETEDに設定された時間を表します。
`DEFINITION`	ジョブ定義ID(メタデータ・オブジェクトID)。
`ELAPSEDTIME`	リクエストの実行に要した時間(ミリ秒)。
`ENTERPRISE_ID`	エンタープライズID。
`ERROR_TYPE`	リクエスト・エラー・タイプ。
`EXTERNAL_ID`	Oracle Enterprise Scheduler非同期Javaジョブの外部部分の識別子。
`EXTERNAL_JOB_TYPE`	リモート・ジョブのタイプを示します。
`INSTANCEPARENTID`	インスタンスの親リクエストのリクエストID。
`JOB_TYPE`	ジョブ・タイプID(メタデータ・オブジェクトID)。
`LOGICAL_CLUSTER_NAME`	リモート・ジョブが実行される論理クラスタを示します。
`NAME`	リクエストの説明。
`PARENTREQUESTID`	親リクエストID。
`PRIORITY`	リクエストの優先度。
`PROCESS_PHASE`	リクエストのプロセス・フェーズ。
`PROCESSEND`	プロセスが終了した日時。`PROCESSSTART`は、リクエストが`READY`から`RUNNING`に遷移した場合にのみ設定されます。これは、(`PROCESSEND` - `PROCESSSTART`)に、状態が`RUNNING`になってから終了状態に遷移するまでの、実行の全期間が含まれることを意味します。
`PROCESSOR`	リクエストを処理したインスタンスの名前。
`PROCESSSTART`	プロセスが開始した日時。`PROCESSSTART`は、リクエストが`READY`から`RUNNING`に遷移した場合にのみ設定されます。これは、(`PROCESSEND` - `PROCESSSTART`)に、状態が`RUNNING`になってから終了状態に遷移するまでの、実行の全期間が含まれることを意味します。
`PRODUCT`	製品名。
`READYWAIT_TIME`	リクエストがREADYになった後、実行を待機している時間(ミリ秒)。
`REQUEST_CATEGORY`	リクエストに指定されたリクエスト・カテゴリ。
`REQUEST_DMS_ECID`	リクエストの処理に使用されるDMS ECID。
`REQUESTEDEND`	リクエストされた終了時間。
`REQUESTEDSTART`	リクエストされた開始時間。
`REQUESTID`	発行されたリクエストのリクエストID。
`REQUESTTYPE`	リクエストのタイプ(つまり、`RequestType`の要素)。
`RESULTINDEX`	返された結果の開始および終了索引を制御します。ユーザーはこのフィールドを使用して、「10から20までの結果のみを返す」などの結果の制約を示すことができます。
`RETRIED_COUNT`	ジョブに関連付けられている再試行回数。このフィールドは、ジョブが再試行された回数を表します。
`REQUESTTRIGGER`	トリガーID (メタデータ・オブジェクトID)。
`SCHEDULE`	スケジュールID(メタデータ・オブジェクトID)。
`SCHEDULED`	スケジュールされたリクエストの実行時間。
`STATE`	ジョブ・リクエストの状態。
`SUBMISSION`	リクエストの発行時間。
`SUBMITTER`	リクエストの発行者。
`SUBMITTER_DMS_ECID`	リクエスト発行時のDMSコンテキストからのDMS ECID。
`SUBMITTER_FLOWID`	リクエスト発行時のDMSコンテキストからのSOA/DMS FlowId。
`SUBMITTERGUID`	リクエストの発行者GUID。
`TIMED_OUT`	ジョブがタイムアウトしたかどうかを示します。
`TYPE`	リクエストの実行タイプ。
`USERNAME`	リクエストを発行したユーザーの名前。
`WAITTIME`	リクエストが実行を待機している時間(ミリ秒)。
`WORKASSIGNMENT`	リクエストが処理されたときにアクティブだった作業割当ての名前。

表19-6にジョブ・リクエストを問い合せるランタイム・サービス・メソッドを、例19-6にこのメソッドの使用方法を示します。

表19-6 ランタイム・サービスの問合せメソッド

ランタイム問合せメソッド	説明
`queryRequests()`	リクエストのサマリーを取得します。

例19-6 queryRequest()メソッドの使用

           Filter filter =
                new Filter(RuntimeService.QueryField.DEFINITION.fieldName(),
                           Filter.Comparator.EQUALS,
                           myJavaSucJobDef.toString())
                .and(RuntimeService.QueryField.STATE.fieldName(),
                     Filter.Comparator.EQUALS,
                     new Integer(12) );
 
            // 
            Enumeration requests =
                runtime.queryRequests(h, filter,
                           RuntimeService.QueryField.REQUESTID, true);

19.6 非定型ジョブ・リクエストの発行

非定型リクエストを使用するには、リクエスト・パラメータ、ジョブ定義、およびオプションで、メタデータ・リポジトリに保存せずに作成および定義するスケジュールを指定します。

非定型リクエストでは、メタデータ・リポジトリでジョブ・リクエストの詳細を定義する必要がありません。このため、非定型リクエストによって、メタデータ・リポジトリへの接続を使用しないで実行できる、省略されたジョブ・リクエスト発行プロセスがサポートされます。

ノート:

非定型リクエストには、ジョブ・セットはサポートされないという制約があります。

19.6.1 非定型リクエストの作成方法

非定型リクエストを作成するには、非定型バージョンのsubmitRequest()を使用します。ジョブ定義の場合は、ジョブ定義MetadataObjectIdを指定するかわりに、表19-7で示されているように、ジョブ定義オブジェクトを定義して、ジョブ・タイプに対応するシステム・プロパティを使用できます。

表19-7 ジョブ・タイプに対する非定型リクエスト・ジョブ定義のシステム・プロパティ

システム・プロパティ	説明
`CLASS_NAME`	実行するJavaクラスを指定します(Javaジョブ・タイプに対して)。
`PROCEDURE_NAME`	実行するPL/SQLストアド・プロシージャを指定します(SQLジョブ・タイプに対して)。
`CMDLINE`	プロセス・ジョブ・リクエストに対して外部プログラムを起動するために使用されるコマンド行を指定します。

非定型バージョンのsubmitRequest()の1つのシグネチャを使用すると、MetadataObjectIdsを指定する必要はありません。Scheduleオブジェクトを、オブジェクト・インスタンスを表す引数として、直接submitRequest()に指定できます。その他の非定型submitRequest()シグネチャを使用すると、メタデータのジョブ定義およびScheduleオブジェクトのインスタンスを使用して、ジョブ・リクエストを発行できます。

例19-7に、スケジュールを使用する非定型リクエスト発行のサンプル・コードを示します。

この例では、リクエスト発行に関する次の非定型固有の詳細に注意してください。

CLASS名は、Oracle Enterprise Schedulerによるジョブ・リクエストの実行時に、実行されるJavaクラスを定義するために次のように設定されます。p.add(SystemProperty.CLASS_NAME, "test.job.HelloWorld");
submitRequest()には、ジョブ・タイプを指定する次の引数が含まれます。JobType.ExecutionType.JAVA_TYPE。
表19-7に示されているいずれかのシステム・プロパティを設定することによって、非定型リクエストが処理されるときに実行するJavaクラス、プロシージャ名またはコマンド行プログラムを指定します。
非定型バージョンのsubmitRequest()をコールして、リクエストを定義するために設定するシステム・プロパティに対応するタイプ引数を指定します。指定するタイプは、JAVA_TYPE、SQL_TYPEまたはPROCESS_TYPEのいずれかである必要があります。
他のすべてのジョブ・リクエストと同様に、ジョブ・リクエストに関連付ける適切なシステム・プロパティを設定します。

例19-7 非定型リクエストのリクエスト・パラメータとスケジュールの作成

            RequestParameters p = new RequestParameters();
            String propName = "testProp";
            String propValue = "testValue";
            p.add(propName, propValue);
            p.add(SystemProperty.REQUEST_EXPIRATION, new Integer(10));
            p.add(SystemProperty.LISTENER, "test.listener.TestListener");
            p.add(SystemProperty.EXECUTE_PAST, "TRUE");
            p.add("application", getApplication());
            p.add(SystemProperty.CLASS_NAME, "test.job.HelloWorld");
 
            Calendar start = Calendar.getInstance();
            start.add(Calendar.SECOND, 5);
            Calendar end = (Calendar) start.clone();
            end.add(Calendar.SECOND, 5);
 
            Recurrence recur = new Recurrence(RecurrenceFields.FREQUENCY.SECONDLY,
                                     2, start, end);
 
            Schedule schedule = new Schedule("mySchedule",
                                     "Run every 2 sec for 5 seconds.", recur);
 
            // adhoc submission, no metadata definitions passed
            reqId = runtime.submitRequest(h,
                                    "testAdhocJavaWithSchedule",
                                  JobType.ExecutionType.JAVA_TYPE, schedule,                                       null, Calendar.getInstance(), null, p);

19.6.2 非定型リクエストの作成時の処理内容

非定型のsubmitRequest()では、リクエストに対してリクエスト識別子が返されます。他のすべてのジョブ・リクエストと同様に、このリクエスト識別子をsetRequestParameter()やgetRequestDetail()などのランタイム・コールとともに使用できます。

非定型ジョブ定義を使用してリクエストを作成するsubmitRequestシグネチャは1つのみ存在します。この場合、RequestDetail.getJobDefn()から取得されるジョブ定義IDはNULLです。非定型ジョブ定義がない場合、リクエストは非定型とはみなされません。

19.6.3 非定型リクエストに関する必知事項

非定型リクエストで使用するスケジュールを定義し、除外日を指定するには、スケジュールに対してaddExclusionDate()メソッドを使用して日付を除外する必要があります。非定型リクエストでは、スケジュールに対してaddExclusion()メソッドを使用して除外日を指定するスケジュールは使用できません。

現在、スケジュールが非定型の場合、ExclusionDefinitionのチェックはスキップされます。このため、スケジュールを使用し、addExclusion()を使用して非定型ジョブ・リクエストを発行する場合は、ジョブ・リクエストに対してExclusionsDefinition IDが使用されません。

19.7 前処理および後処理ハンドラの実装

ジョブのコア・ロジックとともに、ジョブの主要実行コードの前後で実行されるコードを含めることができます。前処理ハンドラと呼ばれる、前に実行されるコードを使用して、ジョブ実行可能ファイルに特定の条件を設定するなどの操作を実行できます。

後処理ハンドラと呼ばれる、後で実行されるコードを使用すると、レポートの印刷や通知の送信などによる、ジョブ実行可能ファイルの結果の処理といった操作を実行できます。

特定のインタフェースを実装し、使用するクラスを示すシステム・プロパティを通じてサービスに実装を接続することによって、前処理および後処理ハンドラを提供します。

19.7.1 前処理ハンドラの実装

前処理ハンドラを使用すると、コードでジョブの実行環境を作成するための操作を実行できます。これには、ジョブで必要なリソースへの接続の作成などが含まれます。

プリプロセッサは、リクエストがRUNNING状態に遷移した場合に、リクエストの実行開始時にインスタンス化および起動されます。これはリクエストが実行されるたびに行われ、失敗したリクエストが再試行されたり、一時停止されたリクエストがそのサブリクエストの完了後に再開される場合にも行われます。

前処理ハンドラは、oracle.as.scheduler.PreProcessHandlerインタフェースを実装することにより作成します。前処理ハンドラ・クラスを用意して、SYS_preProcessシステム・プロパティをハンドラ・クラスの完全修飾名に設定することにより、これを使用する必要があることを指定します。ジョブ・メタデータでプロパティを定義するか、リクエスト発行パラメータにプロパティを含めることができます。

19.7.1.1 PreProcessHandlerインタフェースの実装

PreProcessHandler実装では、ジョブで必要な前処理アクションを実行してから、インタフェースの1つのメソッドであるpreProcessからoracle.as.scheduler.HandlerActionインスタンスを返す必要があります。(ジョブで取消しがサポートされるようにするために、クラスでCancellableインタフェースを実装することもできます。これには、空のコンストラクタも提供する必要があります。)

preProcess実装により返されるHandlerActionインスタンスでは、ジョブを続行する必要があるかどうか、および続行する条件に関するステータスを示す必要があります。HandlerActionクラスを構築する場合、リクエストに対する前処理のステータスを示すHandlerStatusインスタンスにこのクラスを渡します。

サポートされているHandlerStatus値とアクションを次のリストに示します。サポートされていないステータスの場合は、リクエストがエラー状態に遷移し、再試行の対象となります(構成されている場合)。

PROCEEDは、リクエスト処理を開始する必要があることをOracle Enterprise Schedulerに通知します。リクエストは、RUNNING状態のままとなります。
WARNは、リクエスト処理を開始する必要があるが、警告をログに記録する必要があることをOracle Enterprise Schedulerに通知します。リクエストは、RUNNING状態のままとなります。
CANCELは、リクエストの前処理が取り消されたことをOracle Enterprise Schedulerに通知します。リクエストは、CANCELLED状態に遷移します。
DELAYは、SYS_reprocessDelayシステム・プロパティで指定された時間、リクエスト処理を延期するようOracle Enterprise Schedulerに通知します。リクエストは遅延中、RUNNING状態のままとなります。
SYSTEM_ERRORは、ハンドラでエラーが発生したことをOracle Enterprise Schedulerに通知します。リクエストはエラー状態に遷移し、再試行の対象となります(構成されている場合)。
BIZ_ERRORは、ハンドラでビジネス・エラーが発生したことをOracle Enterprise Schedulerに通知します。リクエストはエラー状態に遷移し、再試行の対象にはなりません。

19.7.2 後処理ハンドラの実装

後処理ハンドラを使用すると、コードでジョブの実行後に行う必要がある操作を実行できます。これには、ジョブによって要求されたリソースへの接続の解放や、リクエスト固有のデータまたはステータスに基づくレポートの生成などが含まれます。

リクエストがCOMPLETED状態に遷移した場合、ポストプロセッサはジョブの実行後にインスタンス化および起動されます。プリプロセッサとは異なり、ポストプロセッサはリクエストに対して1回のみ起動されます。

後処理ハンドラは、oracle.as.scheduler.PostProcessHandlerインタフェースを実装することにより作成します。後処理ハンドラ・クラスを用意して、SYS_postProcessシステム・プロパティをハンドラ・クラスの完全修飾名に設定することにより、これを使用する必要があることを指定します。ジョブ・メタデータでプロパティを定義するか、リクエスト発行パラメータにプロパティを含めることができます。

19.7.2.1 PostProcessHandlerインタフェースの実装

PostProcessHandler実装では、ジョブで必要な後処理アクションを実行してから、インタフェースの1つのメソッドであるpostProcessからoracle.as.scheduler.HandlerActionインスタンスを返す必要があります。(ジョブで取消しがサポートされるようにするために、クラスでCancellableインタフェースを実装することもできます。これには、空のコンストラクタも提供する必要があります。)

postProcess実装により返されるHandlerActionインスタンスでは、ジョブを終了する必要があるかどうかおよび終了する条件に関するステータスを示す必要があります。HandlerActionクラスを構築する場合、リクエストに対する後処理のステータスを示すHandlerStatusインスタンスにこのクラスを渡します。

サポートされているHandlerStatus値とアクションを次のリストに示します。サポートされていないステータスの場合は、リクエストがWARNING状態に遷移します。

PROCEEDは、リクエストの後処理が正常に完了したことをOracle Enterprise Schedulerに通知します。ポストプロセッサを起動する直前のリクエストのステータスに応じて、リクエストがSUCCEEDED状態またはWARNING状態に遷移します。
WARNは、リクエストの後処理により警告が生成されたことをOracle Enterprise Schedulerに通知します。リクエストは、WARNING状態に遷移します。
CANCELは、リクエストの後処理が取り消されたことをOracle Enterprise Schedulerに通知します。リクエストは、WARNING状態に遷移します。
DELAYは、SYS_reprocessDelayシステム・プロパティで指定された時間、リクエスト処理を延期するようOracle Enterprise Schedulerに通知します。リクエストは遅延中、COMPLETED状態のままとなります。
SYSTEM_ERRORは、ハンドラでエラーが発生したことをOracle Enterprise Schedulerに通知します。リクエストは、WARNING状態に遷移します。
BIZ_ERRORは、ハンドラでビジネス・エラーが発生したことをOracle Enterprise Schedulerに通知します。リクエストは、WARNING状態に遷移します。