変更プリプロセッサー
変更プリプロセッサーは、ユーザーが実装するサーバー側のアクション・ハンドラーであり、新規のソース・オブジェクトまたは更新されたソース・オブジェクトを、それらが Content Engine データベースで永続化される前に変更するものです。変更プリプロセッサー・ハンドラーは、クラス定義に関連付けます。クライアントがそのクラスのオブジェクトを保存すると、関連付けられたハンドラーが起動されます。
変更プリプロセッサーは、非同期または同期イベント・アクション・ハンドラーでは実行することが困難または不可能であるソース・オブジェクトの修正をできるようにします。例えば、作成時のみ設定可能な (SOOC) プロパティーは永続化された後に変更できないため、SOOC プロパティーを変更するには、変更プリプロセッサーを使用する必要があります。 変更プリプロセッサーとイベント・アクション・ハンドラーの機能の比較については、「アクション・ハンドラー: 制約事項および最適な方法」を参照してください。
変更プリプロセッサーには、以下の特性があります。
- 作成、更新、または削除の各サーバー要求内のソース・オブジェクトが、変更プリプロセッサー・ハンドラーに渡されます。ソース・オブジェクトには、プロパティー・コレクションと、保留中のアクションのセットが含まれています。
- 変更プリプロセッサー・ハンドラーは、Java コンポーネントまたは JavaScript コンポーネントとして実装できます。Java で実装された変更プリプロセッサーは、コード・モジュール内に配置でき、他のアクション・ハンドラー・タイプ (イベント・アクション、ライフ・サイクル・アクション、およびドキュメント分類子) と同じコード・モジュール内で共存できます。詳しくは、Java アクション・ハンドラーのデプロイを参照してください。
- Document などのサブスクライブ可能なクラス定義に、1 つ以上の変更プリプロセッサーを設定できます。詳細については、セットアップ要件を参照してください。
- クラスに設定された変更プリプロセッサーは、クラス階層内のサブクラスに再帰的に適用されます。例えば、Document クラスに変更プリプロセッサーを設定すると、それが Document クラスのサブクラスにも論理的に適用されます。変更が、作成、更新、削除のいずれであるかに関係なく、変更要求ごとに、ソース・オブジェクトのクラス階層に関連付けられたすべての有効なプリプロセッサーが読み込まれ、呼び出されます。
同じプリプロセッサーが階層内で複数回参照されている場合、階層のルートに最も近いプリプロセッサーが開始され、その他はすべて暗黙的にスキップされます。詳細情報については、変更プリプロセッサーの定義を参照してください。
- 変更プリプロセッサーは同期的に実行されるため、例外が発生すると、トランザクション全体がロールバックされます。
- 監査が有効になっている場合、監査ログ・エントリーに、変更プリプロセッサーが加えた変更が示されます。変更プリプロセッサーは、監査処理の前に開始されます。
- 変更プリプロセッサーは、無効になっていない限り、無条件に開始されます。
- プリプロセッサー内部で加えられた変更を永続化できるのは、必要な権限を要求の開始側ユーザーが保有し、かつプロパティーの制約に違反していない場合のみです。
実装のガイドライン
次のメソッドを ChangePreprocessor インターフェースで実装します。
boolean preprocessObjectChange(com.filenet.api.core.IndependentlyPersistableObject sourceObj)このメソッドを実装する際は、以下の点を考慮してください。
- ソース・オブジェクトの保留中のアクションの配列を取得して、条件付き処理を実行できます。PendingAction オブジェクトは、クライアントが送信したがサーバーがまだ実行していない、ソース・オブジェクトに対して意図された変更 (コンテンツの移動、更新、チェックアウトの各アクションなど) を表します。保留中のアクションの配列を反復処理することにより、クライアントが送信したアクションに基づいて、変更プリプロセッサーがソース・オブジェクト・プロパティーを更新するタイミングを制御できます。コード例については、「変更プリプロセッサー・ハンドラーの作成」を参照してください。
- ソース・オブジェクトのプロパティー・コレクションを取得できます。プロパティー・コレクションは、ソース・オブジェクトの現在の状態と、クライアントからのまだ永続化されていない変更を反映します。
サーバーへの作成要求の場合、プロパティー・コレクション内の項目は少なく、クライアントが指定したプロパティー値、クライアントが設定していないプロパティーに関連付けられたデフォルト値、およびオブジェクト・タイプによって決定される他のいくつかのプロパティーのみが含まれています。
サーバーへの更新要求および削除要求の場合、コレクションには、クライアントによって変更されたプロパティーとマージされたオブジェクトで現在定義されているすべてのプロパティーが含まれます。
変更プリプロセッサー・ハンドラーは、サーバーへの要求のタイプ (作成、更新、削除) に関係なく実行されるため、ソース・オブジェクトのプロパティー・コレクションから入手できるすべてのプロパティーが信頼できるとは限りません。そのため、変更プリプロセッサーの実装では、プロパティーの取得を試みる前に、IsPropertyPresent メソッドを呼び出して、そのプロパティーがコレクション内にあることを確認することをお勧めします。
- 現在のバージョンをチェックアウトすると、副次作用として予約オブジェクトがソース・オブジェクトとして渡されます。この場合、プリプロセッサーに渡されたプロパティー・コレクションには、アクションとともに送信された予約プロパティーと、発信元のソース・オブジェクトからの copy-to-reservation プロパティーが含まれます。そのため、プロパティー定義で CopytoReservation プロパティーが false に設定されているプロパティー・インスタンスは、予約オブジェクトのコレクションにコピーされません。例えば、MimeType プロパティーは、プロパティー定義の制約のためにコレクションにコピーできません。
- プリプロセッサーを使用してプロパティー・コレクションを変更した場合、true を返して、コレクションをサーバーで永続化してください。逆に false を返すと、プロパティー・コレクションへの変更は失われます (永続化しません)。
- クラス階層内でプリプロセッサーのチェーンが再帰的に実行される場合、チェーン内のプリプロセッサーは、前に開始されて true を返したプリプロセッサーから適用されたプロパティー更新を参照できます。プロパティー・コレクションは、すべてのプリプロセッサーが開始されるまでは永続化されません。
許可される操作
- ソース・オブジェクトのプロパティー・コレクションへの更新を実装できます。実装では、fetchProperty を使用して、オブジェクト値プロパティー (OVP) のプロパティー値に基づいて条件付き処理を実行できます。
- コレクションからプロパティーを削除できます。偽装プロパティー (つまりクラス定義では定義されておらず、クライアントとプリプロセッサーの間でのみ意味を持つプロパティー) を削除する必要があることに注意してください。偽装プロパティーを削除しない場合、Content Engine は例外をスローします。
- 変更プリプロセッサーは保留中のアクション処理の前に開始されるため、ソース・オブジェクトの保留中のアクションの配列を取得できます。
許可されない操作
以下の操作は、ソース・オブジェクトの永続化に悪影響を与えるので、開始できません。
- fetchProperties()、checkout()、save()、refresh()、addPendingAction()、clearPendingActions()、delete()、setUpdateSequenceNumber() などのオブジェクトを変更する IndependentlyPersistableObject のメソッド。
- setCaptureSource()、accessContentStream() などのコンテンツ・アクセス・メソッド。
セットアップ要件
変更プリプロセッサーをセットアップするには、以下のようにします。
- ChangePreprocessor インターフェースを実装します。
- CmChangePreprocessorAction オブジェクトを作成します。このオブジェクトには、実装された ChangePreprocessor インターフェースを設定するためのプロパティーが含まれています。IsEnabled プロパティーも含まれていて、これにより、管理者は、プリプロセッサーがクラス階層内のどこで参照されているかに関係なく、システム・スコープ単位でプリプロセッサーを無効にできます。
- CmChangePreprocessorDefinition オブジェクトを作成します。このオブジェクトには、実装された ChangePreprocessorAction オブジェクトを設定するためのプロパティーが含まれています。IsEnabled プロパティーも含まれていて、これにより、管理者は、クラス・スコープ単位でプリプロセッサーを無効にできます。
- CmChangePreprocessorDefinitionList オブジェクトを作成し、それに CmChangePreprocessorDefinition オブジェクトを追加します。
- 変更プリプロセッサーを設定するクラス定義を表す SubscribableClassDefinition オブジェクトを取得します。
- SubscribableClassDefinition オブジェクトで CmChangePreprocessorDefinitionList を設定し、それを保存します。
ObjectStore.CmChangePreprocessorActions プロパティーを持つすべての CmChangePreprocessorAction オブジェクトを取得できます。SubscribableClassDefinition.ChangePreprocessorDefinitions プロパティーを持つすべての CmChangePreprocessorDefinition オブジェクトを取得できます。
セットアップ操作および取得操作のコード例については、「変更プリプロセッサーの操作」を参照してください。