intra-mart Accel Platform 非同期仕様書 第6版 2021-08-01

直列処理機能

直列処理機能は複数のタスクを逐次的に処理する機能です。

タスク厳密な順序関係があり、先行するタスクのビジネスロジックが完了するまで後続のタスクをブロックする必要がある場合、直列処理機能を利用することで処理順序を保証する必要があります。

直列処理機能を利用する場合、タスク登録アプリケーションはタスクメッセージを直列タスクキューに登録する必要があります。 直列処理機能の概要を参照してください。

Overview of queueing serialized task process

直列処理機能の概要

直列タスクキューは複数登録できます。

タスクメッセージ間の実行順序の関係は同一の直列タスクキューにおいてのみ保たれます。

直列タスクキューが異なれば、タスクメッセージ間の実行順序は不定です。 複数の直列タスクキューを参照してください。

Overview of multiple serialized task queue

複数の直列タスクキュー

タスク

複数のタスク間の実行順序を正確にしたい場合、直列処理機能を利用する必要があります。

直列処理機能でビジネスロジック実行中のタスクに例外が発生した場合、後続のタスクの扱いを以下のいずれかに決定する必要があります。

  • 該当するタスクメッセージが所属する直列タスクキューの逐次処理状態を現状のままとする。逐次処理可能状態であれば、後続のタスクを処理する。(有効状態または無効状態を参照)
  • キューの処理を停止し、後続のタスクを待機状態にする。(無効状態を参照)

これらの決定はタスクメッセージの登録時に設定します。 登録するタスクメッセージ毎に直列タスクキューの逐次処理の継続または停止を設定できます。

複数のタスクが存在し、以下の条件のいずれかが満たされる場合は直列処理機能で処理を行う必要があります。

  • 複数のタスクが同時に実行されると実行結果に影響がある。
  • 複数のタスクの実行順序が変更されると期待される実行結果にならない。

直列タスクキュー

直列タスクキューは直列処理機能を利用する場合にタスクメッセージを登録するタスクキューです。

直列タスクキューの詳細については直列タスクキューを参照してください。

直列処理機能におけるタスクメッセージの登録

直列処理機能を利用する場合、タスク登録アプリケーションは非同期処理機能から提供されているAPIを通じてタスクメッセージを直列タスクキューに登録する必要があります。 APIはタスクメッセージを非同期処理機能に登録後、ビジネスロジックの実行を待たずに復帰します。

直列処理機能に登録されたタスクメッセージは後でタスクに変換されてビジネスロジック処理が開始されます。

コラム

タスクメッセージが直列処理機能に登録された時点ではまだ処理が開始されていない可能性があります。

タスクメッセージを登録すると、登録時のコンテキストの情報も保存されます。 タスクメッセージ登録時のコンテキスト情報は、タスクのビジネスロジック実行時に取得して利用することが可能です。

Java

Javaでタスクメッセージを登録する場合、jp.co.intra_mart.foundation.asynchronous.TaskManagerクラスのaddSerializedTaskメソッドを呼び出します。 このメソッドを呼び出すことによってタスク登録アプリケーションはJavaを通じて直列タスクキューにタスクメッセージを追加します。

TaskManager#addSerializedTask

public static jp.co.intra_mart.foundation.asynchronous.SerializedTaskMessage
   addSerializedTask(
      java.lang.String queueId,
      java.lang.String taskClassName,
      java.util.Map<java.lang.String, ?> parameter,
      boolean stopProgressOnError,
      boolean keepTaskMessageOnError
   ) throws
      jp.co.intra_mart.foundation.asynchronous.TaskControlException

queueIdにはタスクメッセージの登録先となる直列タスクキューのキューIDを指定します。

taskClassNameにはビジネスロジックを実行するタスクのクラス名を指定します。

parameterにはビジネスロジック実行時に受け渡したいパラメータを指定します。 パラメータとして指定できる値はJavaを利用するときのパラメータの制限の内容に準じます。 パラメータに無効な値が指定された場合、java.lang.IllegalArgumentExceptionが返されます。

stopProgressOnErrorにはtaskClassNameで指定したタスクの実行時に例外が発生した場合、対象となる直列タスクキューを停止するかどうかを指定します。

  • trueが設定された場合、例外発生時には直列タスクキューを現在の状態に関わらず停止状態にし、後続のタスクの処理を停止します。
  • falseが設定された場合、例外発生時であっても直列タスクキューの状態を変更しません。

keepTaskMessageOnErrorにはtaskClassNameで指定したタスクの実行時に例外が発生した場合、対象となるタスクメッセージをエラー終了状態にするかどうかを指定します(本引数はintra-mart Accel Platform 2021 Summer(Cattleya)以降のバージョンで利用可能です)。

  • trueが設定された場合、例外発生時には対象となるタスクメッセージをエラー終了状態にします。
  • falseが設定された場合、例外発生時であっても対象となるタスクメッセージを破棄状態にします。

このメソッドは戻り値としてjp.co.intra_mart.foundation.asynchronous.SerializedTaskMessageを返します。

コラム

stopProgressOnErrorkeepTaskMessageOnErrorどちらもtrueが設定された場合は、stopProgressOnErrorの設定が優先されます。 この場合、taskClassNameで指定したタスクの実行時に例外が発生すると、対象となるタスクメッセージは選択待機状態に遷移します。

サーバサイドJavaScript

サーバサイドJavaScriptでタスクメッセージを登録する場合、WorkManagerオブジェクトのaddSerializedTask関数を呼び出します。 この関数を呼び出すことによってタスク登録アプリケーションはサーバサイドJavaScriptを通じて直列タスクキューにタスクメッセージを追加します。

WorkManager#addSerializedTask

function addSerializedTask(queueId, jsPath, parameter, stopQueueProcessingIfError, keepTaskMessageOnError)

queueIdにはタスクメッセージの登録先となる直列タスクキューのキューIDを指定します。

jsPathにはビジネスロジックとなるrun関数が定義されているJSソースファイルのパスを指定します。

parameterにはビジネスロジック実行時に受け渡したいパラメータを指定します。 パラメータとして指定できる値はサーバサイドJavaScriptを利用するときのパラメータの制限の内容に準じます。

stopProgressOnErrorにはjsPath で指定したタスクの実行時に例外が発生した場合、対象となる直列タスクキューを停止するかどうかを指定します。

  • trueが設定された場合、例外発生時には直列タスクキューを現在の状態に関わらず停止状態にし、後続のタスクの処理を停止します。
  • falseが設定された場合、例外発生時であっても直列タスクキューの状態を変更しません。

keepTaskMessageOnErrorにはjsPath で指定したタスクの実行時に例外が発生した場合、対象となるタスクメッセージをエラー終了状態にするかどうかを指定します(本引数はintra-mart Accel Platform 2021 Summer(Cattleya)以降のバージョンで利用可能です)。

  • trueが設定された場合、例外発生時には対象となるタスクメッセージをエラー終了状態にします。
  • falseが設定された場合、例外発生時であっても対象となるタスクメッセージを破棄状態にします。

このメソッドは戻り値としてメッセージIDを返します。

コラム

stopProgressOnErrorkeepTaskMessageOnErrorどちらもtrueが設定された場合は、stopProgressOnErrorの設定が優先されます。 この場合、taskClassNameで指定したタスクの実行時に例外が発生すると、対象となるタスクメッセージは選択待機状態に遷移します。

直列処理機能におけるタスクメッセージの削除

直列タスクキューにタスクメッセージが登録された後であっても、タスクメッセージが実際にタスクとして実行される前であれば任意の時点でタスクメッセージを削除できます。 タスクメッセージはAPIまたは非同期処理管理画面を通じて削除することが可能です。 直列処理機能を利用する場合、タスク登録アプリケーションは非同期処理機能から提供されているAPIを通じてタスクメッセージを直列タスクキューに登録する必要があります。 APIはタスクメッセージを非同期処理機能に登録後、ビジネスロジックの実行を待たずに復帰します。

Java

Javaでタスクメッセージを削除する場合、jp.co.intra_mart.foundation.asynchronous.TaskManagerクラスのremoveSerializedTaskメソッドを呼び出します。 このメソッドを呼び出すことによってタスク管理アプリケーションはJavaを通じて直列タスクキューからビジネスロジック実行前のタスクメッセージを削除します。

TaskManager#removeSerializedTask

public static boolean removeSerializedTask(
      java.lang.String messageId
   ) throws
      jp.co.intra_mart.foundation.asynchronous.TaskIllegalStateException,
      jp.co.intra_mart.foundation.asynchronous.InvalidTaskException,
      jp.co.intra_mart.foundation.asynchronous.TaskControlException

messageIdにはTaskManager#addSerializedTaskまたはWorkManager#addSerializedTaskの呼び出し時に取得されたメッセージIDを指定します。

messageIdが直列タスクキューに登録されたものでない場合、jp.co.intra_mart.foundation.asynchronous.InvalidTaskExceptionが返されます。

messageIdに該当するタスクメッセージが(実行中などの理由により)削除できなかった場合、jp.co.intra_mart.foundation.asynchronous.TaskIllegalStateExceptionが返されます。

サーバサイドJavaScript

サーバサイドJavaScriptでタスクメッセージを削除する場合、WorkManagerクラスのremoveSerializedTaskメソッドを呼び出します。 このメソッドを呼び出すことによってタスク管理アプリケーションはサーバサイドJavaScriptを通じて直列タスクキューからビジネスロジック実行前のタスクメッセージを削除します。

WorkManager#removeSerializedTask

function removeSerializedTask(messageId)

messageIdにはTaskManager#addSerializedTaskまたはWorkManager#addSerializedTaskの呼び出し時に取得されたメッセージIDを指定します。

直列処理機能におけるエラー終了状態のタスクメッセージの再登録

エラー終了状態のタスクメッセージを再実行する場合、タスク登録アプリケーションは非同期処理機能から提供されているAPIまたは非同期処理管理画面を通じてタスクメッセージを直列タスクキューに再登録する必要があります。 APIはタスクメッセージを非同期処理機能に登録後、ビジネスロジックの実行を待たずに復帰します。

直列処理機能に登録されたタスクメッセージは後でタスクに変換されてビジネスロジック処理が開始されます。

コラム

タスクメッセージが直列処理機能に再登録された時点ではまだ処理が開始されていない可能性があります。

再登録時はタスクメッセージを登録した際のコンテキストの情報やパラメータを再利用できます。

エラー終了状態のタスクメッセージの再登録は、intra-mart Accel Platform 2021 Summer(Cattleya)以降のバージョンで利用可能です。

Java

Javaでエラー終了状態のタスクメッセージを再登録する場合、jp.co.intra_mart.foundation.asynchronous.TaskManagerクラスのreentryErroredTaskメソッドを呼び出します。 このメソッドを呼び出すことによってタスク登録アプリケーションはJavaを通じて直列タスクキューにタスクメッセージを追加します。

TaskManager#reentryErroredTask

public static jp.co.intra_mart.foundation.asynchronous.TaskMessage
   reentryErroredTask(
      java.lang.String messageId,
      boolean usePreviousContext,
      java.util.Map<java.lang.String, ?> parameter
   ) throws
      jp.co.intra_mart.foundation.asynchronous.TaskIllegalStateException,
      jp.co.intra_mart.foundation.asynchronous.TaskControlException

messageIdにはTaskManager#addSerializedTaskまたはWorkManager#addSerializedTaskの呼び出し時に取得されたメッセージIDを指定します。

usePreviousContextには前回実行時に利用したコンテキストの情報を再利用するかどうかを指定します。

  • trueが設定された場合、前回実行時に利用したコンテキストの情報を再利用します。
  • falseが設定された場合、再登録時(本メソッドを呼び出した時点)のコンテキストの情報を利用します。

parameterにはビジネスロジック実行時に受け渡したいパラメータを指定します。 パラメータとして指定できる値はJavaを利用するときのパラメータの制限の内容に準じます。 パラメータに無効な値が指定された場合、java.lang.IllegalArgumentExceptionが返されます。 省略した場合は、前回登録時に指定したパラメータを使用します。

このメソッドは戻り値としてjp.co.intra_mart.foundation.asynchronous.SerializedTaskMessageを返します。

サーバサイドJavaScript

サーバサイドJavaScriptでエラー終了状態のタスクメッセージを再登録する場合、WorkManagerオブジェクトのreentryErroredTask関数を呼び出します。 この関数を呼び出すことによってタスク登録アプリケーションはサーバサイドJavaScriptを通じて直列タスクキューにタスクメッセージを追加します。

WorkManager#reentryErroredTask

function reentryErroredTask(messageId, usePreviousContext, parameter)

messageIdにはTaskManager#addSerializedTaskまたはWorkManager#addSerializedTaskの呼び出し時に取得されたメッセージIDを指定します。

usePreviousContextには前回実行時に利用したコンテキストの情報を再利用するかどうかを指定します。

  • trueが設定された場合、前回実行時に利用したコンテキストの情報を再利用します。
  • falseが設定された場合、再登録時(本関数を呼び出した時点)のコンテキストの情報を利用します。

parameterにはビジネスロジック実行時に受け渡したいパラメータを指定します。 パラメータとして指定できる値はサーバサイドJavaScriptを利用するときのパラメータの制限の内容に準じます。 省略した場合は、前回登録時に指定したパラメータを使用します。

この関数は戻り値としてメッセージID(messageIdに指定されたメッセージIDと同じ値)を返します。

直列処理機能におけるエラー終了状態のタスクメッセージの削除

エラー終了状態のタスクメッセージは、APIまたは非同期処理管理画面を通じて削除できます。

コラム

エラー終了状態のタスクメッセージの削除は、intra-mart Accel Platform 2021 Summer(Cattleya)以降のバージョンで利用可能です。

Java

Javaでエラー終了状態のタスクメッセージを削除する場合、jp.co.intra_mart.foundation.asynchronous.TaskManagerクラスのremoveErroredTaskメソッドを呼び出します。 このメソッドを呼び出すことによってタスク管理アプリケーションはJavaを通じてエラー終了状態のタスクメッセージを削除します。

TaskManager#removeErroredTask

public static jp.co.intra_mart.foundation.asynchronous.report.SearchRegisteredTaskInfo<? extends jp.co.intra_mart.foundation.asynchronous.report.RegisteredTaskInfo>
   removeErroredTask(
      final java.lang.String messageId
   ) throws
      jp.co.intra_mart.foundation.asynchronous.TaskIllegalStateException,
      jp.co.intra_mart.foundation.asynchronous.TaskControlException

messageIdにはTaskManager#addSerializedTaskまたはWorkManager#addSerializedTaskの呼び出し時に取得されたメッセージIDを指定します。

messageIdに該当するタスクメッセージが(エラー終了状態以外などの理由により)削除できなかった場合、jp.co.intra_mart.foundation.asynchronous.TaskIllegalStateExceptionが返されます。

このメソッドは戻り値としてjp.co.intra_mart.foundation.asynchronous.report.SearchRegisteredTaskInfo<? extends jp.co.intra_mart.foundation.asynchronous.report.RegisteredTaskInfo>を返します。
仮型パラメータの実型はjp.co.intra_mart.foundation.asynchronous.report.RegisteredSerializedTaskInfoです。

サーバサイドJavaScript

サーバサイドJavaScriptでエラー終了状態のタスクメッセージを削除する場合、WorkManagerクラスのremoveErroredTask関数を呼び出します。 この関数を呼び出すことによってタスク管理アプリケーションはサーバサイドJavaScriptを通じてエラー終了状態のタスクメッセージを削除します。

WorkManager#removeErroredTask

function removeErroredTask(messageId)

messageIdにはTaskManager#addSerializedTaskまたはWorkManager#addSerializedTaskの呼び出し時に取得されたメッセージIDを指定します。

この関数は戻り値として削除したタスクメッセージを返します。