この章では、Oracle Managed File Transfer (MFT)におけるファイル転送の前処理と後処理のためのカスタム・コールアウトの作成方法と使用方法を説明します。
コールアウトを作成するには、JavaおよびXMLコードに習熟しており、「アーティファクト(転送、ソースおよびターゲット)の設計」に説明されている転送の作成方法を習得している必要があります。
この章の内容は次のとおりです。
Oracle Managed File Transferには、転送の前処理および後処理用の組込みの圧縮、圧縮解除、暗号化および復号化の各アクションが用意されています。詳細は、「転送の前処理と後処理のアクションの設定」と「ソース処理アクションの設定」を参照してください。
カスタム・コールアウトと呼ばれる前処理アクションおよび後処理アクションを新しく作成できます。カスタム・コールアウト使用の例は、次のとおりです。
コピーライト・ヘッダーおよびフッターの追加
内容の検証
配信が成功または失敗した場合の個別のアプリケーションへの通知
配信が成功または失敗した場合の個別のアプリケーションの起動
MFTデータベースに永続化されているカスタム・ヘッダーまたはプロパティの追加
代替暗号化技術の追加
この章では、改行変換コールアウト例を使用します。
カスタム・コールアウトは、ソースまたはターゲットと関連付けることができます。転送時の処理アクションの実行順序は次のとおりです。
ソース前処理アクション
ターゲット前処理アクション
ペイロード配信
ターゲット後処理アクション
注意:
MFTコンソールでは、ターゲット処理アクションは転送時に構成されます。「アーティファクト(転送、ソースおよびターゲット)の設計」では、これらのアクションは転送処理アクションと呼ばれています。この章では、これらのアクションをターゲット処理アクションと呼びます。
注意:
後処理は、ファイル配信の後に実行されます。したがって、配信が成功して後処理が失敗した場合、「監視」ページの「ダッシュボード」タブの「アクティブな配信」ビューと「ファイル・ファインダ」ビューに表示されるステータスは異なります。具体的には、「アクティブな配信」ビューでは「完了」ステータスが表示されますが、「ファイル・ファインダ」ビューでは「失敗」ステータスが表示されます。
表3-1は、作成できるコールアウトのタイプをまとめたものです。
表3-1 コールアウトのタイプ
コールアウトのタイプ | インタフェース名 | ペイロードの変更 | ヘッダーおよびプロパティの変更 |
---|---|---|---|
前処理 |
PreCalloutPlugin |
使用可能 |
使用可能 |
後処理 |
PostCalloutPlugin |
不可 |
使用可能 |
カスタム・コールアウトの作成の概略手順は次のとおりです。
次の各項では、改行変換コールアウト例を使用してこれらの手順を詳しく説明します。改行(行末中断や行端(EOL)マーカーとも呼ばれる)は、テキストの行の末尾を示す特殊文字または特殊文字列です。UNIXオペレーティング・システムでは、DOS (およびWindows)オペレーティング・システムとは異なる改行文字を使用します。このコールアウトを使用すると、改行文字をDOSからUNIXへ、またはUNIXからDOSへ変換できます。
この項の内容は次のとおりです。
Javaコードでコールアウト・アクションを定義します。次の最低要件を満たす必要があります。
java.io.IOException
、java.io.InputStream
、java.io.OutputStream
およびjava.util.Map
の各クラスをインポートする必要があります。
com.oracle.tip.mft.engine.processor.plugin
パッケージ内のPluginOutput
クラスとPluginContext
クラスをインポートする必要があります。
com.oracle.callout
パッケージ内のPreCalloutPlugin
インタフェースまたはPostCalloutPlugin
インタフェースを実装する必要があります。
インタフェースの内容については、「PreCalloutPluginインタフェース」または「PostCalloutPluginインタフェース」を参照してください。
JARファイルにパッケージ化される必要があります。
複数のコールアウトを同じJARファイルに含めるか、個別のJARファイルにパッケージ化できます。
コールアウトでヘッダー変数を設定するには、次のようなコードを使用します。
context.getCustomPropertyMap().put("name", "value"); context.getTransportHeaderMap().put("name", "value");
コールアウトでペイロード・ファイル名前を変更するには、次のようなコードを使用します。
PluginOutput pOutput = new PluginOutput(); pOutput.setNewFileName("abc.xyz"); return pOutput;
コールアウトでソース前処理、ソース後処理、ターゲット前処理およびターゲット後処理の各種アクションを実行するには、次のようなコードを使用します。
if(message instanceof oracle.tip.mft.bean.SourceMessage){ // in case of source pre and post processing } else if(message instanceof oracle.tip.mft.bean.Instance){ // in case of target pre } else if(message instanceof oracle.tip.mft.bean.TargetMessage ){ // in case of target post }
コードをコンパイルするには、クラスパスにコアMFT JARファイルを指定して次のようなコマンドを使用します。
javac -classpath $MW_HOME/mft/modules/oracle.mft/core.jar <class>
JARファイルを作成するには、次のコマンドを使用します。
jar cf newlineConversion.jar
改行変換例のJavaクラスは、次のアクションを実行します。
コールアウトがペイロードを変更するように指定します。
Type
パラメータ値を受け入れ、コールアウトがDos2Unix
とUnix2Dos
のいずれであるかを指定します。
Type
値を指定しないとnullが返されます。
doLineConversion
メソッドを使用してペイロードの各行を、選択した改行文字で書き直します。
改行が変更されたペイロード・ファイルのコピーが返されます。
「例 - 改行変換コード」は、改行変換例のJavaクラス・コードを示しています。
package com.oracle.callout.sample; import java.io.BufferedReader; import java.io.BufferedWriter; import java.io.DataInputStream; import java.io.DataOutputStream; import java.io.IOException; import java.io.InputStream; import java.io.InputStreamReader; import java.io.OutputStream; import java.io.OutputStreamWriter; import java.util.Map; import oracle.tip.mft.engine.processsor.plugin.PluginContext; import oracle.tip.mft.engine.processsor.plugin.PluginOutput; import oracle.tip.mft.engine.processsor.plugin.PreCalloutPlugin; public class NewlineConversion implements PreCalloutPlugin { @Override public boolean isPayloadChangeRequired(PluginContext context, Map<String, String> calloutParams) { return true; } @Override public PluginOutput process(PluginContext context, InputStream input, OutputStream out, Map<String, String> calloutParams) { String type = calloutParams.get("Type"); boolean isDos = false; if ("Unix2Dos".equals(type)) { isDos = true; } doLineConversion(input, out, isDos); return new PluginOutput(); } @Override public PluginOutput process(PluginContext context, InputStream input, Map<String, String> calloutParams) { return null; } public static final String DOS_NEW_LINE = "\r\n"; public static final String UNIX_NEW_LINE = "\n"; private void doLineConversion(InputStream in, OutputStream out, boolean isDos) { String newLineChar = null; if (isDos) { newLineChar = DOS_NEW_LINE; } else { newLineChar = UNIX_NEW_LINE; } BufferedReader bufferIn = null; BufferedWriter bufferOut = null; try { DataInputStream dataIn = new DataInputStream(in); bufferIn = new BufferedReader(new InputStreamReader(dataIn)); DataOutputStream dataOut = new DataOutputStream(out); bufferOut = new BufferedWriter(new OutputStreamWriter(dataOut)); // For each line in the un-normalized file String line; while ((line = bufferIn.readLine()) != null) { // Write the original line plus the operating-system dependent // newline bufferOut.write(line); bufferOut.write(newLineChar); } } catch (Exception e) { throw new RuntimeException(e); } finally { try { bufferIn.close(); bufferOut.close(); } catch (IOException e) { throw new RuntimeException(e); } } } }
定義ファイルでMFT構成のコールアウト構造を指定します。定義ファイルは次の最低要件を満たす必要があります。
callout.xsd
スキーマ・ファイルで指定したXML形式に準拠している必要があります。スキーマ・ファイルの内容については、「コールアウト定義スキーマ」を参照してください。
複数のコールアウトを同じ定義ファイルに含めるか、個別の定義ファイルにパッケージ化できます。
デバッグが不十分な、無限ループを含むコールアウトが非常に長い時間実行されるのを防止するため、Callout
要素のtimeout
属性に値(秒単位)が指定されている必要があります。
Callout
要素のimplementationClass
属性は、パッケージ名などのJavaクラス名を参照する必要があります。
Callout
要素のlibraryName
属性は、JARファイル名を参照する必要があります。
Javaクラスに入力パラメータがある場合は、対応するParameter
要素を指定する必要があります。
「例 - 改行変換コールアウト定義ファイル」は、改行変換例のコールアウト定義ファイルを示しています。
例 - 改行変換コールアウト定義ファイル
<?xml version="1.0" encoding="UTF-8"?> <mft:Callouts xmlns:mft="http://xmlns.oracle.com/mft" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/mft callout.xsd "> <mft:Callout description="New line conversion" helpText="New line conversion" groupName="Source-pre,Target-pre" timeout="300" implementationClass="com.oracle.callout.sample.NewlineConversion" libraryName="newlineConversion.jar" name="New line conversion"> <mft:Parameter description="Type" mandatory="true" helpText="Type" name="Type" listValue="Dos2Unix,Unix2Dos" parameterType="string" defaultValue="Dos2Unix"/> </mft:Callout> </mft:Callouts>
JARファイルと定義ファイルを作成したら、それらのファイルをMFTコールアウト・ディレクトリにコピーする必要があります。このディレクトリのデフォルトの場所は次のとおりです。
FMW_HOME/user_projects/domains/soainfra/mft/callouts
この場所を確認するには、MFT構成を調べます。
このプロセスの手順は次のとおりです。
「管理」ページに移動します。
左側のナビゲーション・ペインで、「サーバー・プロパティ」をクリックします。
ページの上端付近にある「コールアウト・ディレクトリ」設定を調べます。
JARファイルと定義ファイルをMFTコールアウト・ディレクトリにコピーしたら、createCallouts
コマンドを使用してコールアウト定義をMFT構成にアップロードする必要があります。
このプロセスの手順は次のとおりです。
MFT WLSTコマンドの詳細は、SOA Suite WLSTコマンド・リファレンスのMFTのWLSTコマンドの要約およびMFTカスタムWLSTコマンドを参照してください。
コールアウトを作成してコールアウト定義をアップロードしたら、コールアウトをテストして設計どおりに機能することを確認する必要があります。
カスタム・コールアウトのテストの概略手順は次のとおりです。
注意:
createCallouts
コマンドを実行するときにMFTコンソールにログインした場合は、コールアウトをソースまたはターゲットに追加するには、事前にMFTコンソールからログアウトして再度ログインする必要があります。
ソースまたはターゲットのレポートにアクセスするには、「監視」ページに移動し、「ソース、転送およびターゲットのレポートの解釈」を参照してください。
改行変換コールアウトは、ソース・レポートの「ソース前処理」表または、ターゲット・レポートの「ターゲット前処理」表に表示されています。コールアウト・アクションが成功した場合は、どちらの表の「ステータス」列にも「処理済」と表示されます。
さらに、コールアウト・アクションが成功した場合は、レポートの「拡張」セクションの「メッセージ・プロパティ」フィールドにpayloadModified=yes
と表示されます。
詳細は、「ソース・レポート」または「ターゲット・レポート」を参照してください。
コールアウトを更新するときは次の点に留意してください。
コールアウトを作成または更新するときは、MFTサーバーの再起動は必要ありません。
Javaコードのみを変更してパラメータを変更しない場合は、必要な作業は新しいJARファイルをコールアウト・ディレクトリにコピーすることのみです。
定義ファイルを変更してパラメータを変更しない場合は、必要な作業はupdateCallouts
コマンドを使用して新しいコールアウト定義に再ロードすることのみです。
コールアウト・パラメータの追加、削除または変更を行った場合は、次の手順を実行する必要があります。
deleteCallout
コマンドを使用してコールアウトを削除します。
createCallouts
コマンドを使用してコールアウトを再作成します。
新しいコールアウト・バージョンを使用するようにソースまたはターゲットを再構成します。
MFT WLSTコマンドの詳細は、『SOA Suite WLSTコマンド・リファレンス』の「MFTのWLSTコマンドの要約」およびMFTコールアウト・コマンドに関する項を参照してください。
この項では、次のファイルの内容を示します。
「例 - PreCalloutPluginインタフェース」は、com.oracle.callout.PreCalloutPlugin
インタフェースのJavaコードを示しています。
例 - PreCalloutPluginインタフェース
public interface PreCalloutPlugin { /** * Depending on the return of this function output stream for changing the * pay load content will be passed. Only if the payload change is required * return true. * * @param context * @param calloutParams * @return */ public boolean isPayloadChangeRequired(final PluginContext context, final Map<String, String> calloutParams); /** * This function will be called only if the isPayloadChangesRequired returns * true. This method must write final pay load content to the output stream. * Any custom properties or the header properties can be set at the context * level. * * @param context * @param input * @param out * @param calloutParams * @return */ public PluginOutput process(final PluginContext context, final InputStream input, OutputStream out, final Map<String, String> calloutParams); /** * This function will be called only if the isPayloadChangesRequired returns * false. Any custom properties or the header properties can be set at the * context level. * * @param context * @param input * @param out * @param calloutParams * @return */ public PluginOutput process(final PluginContext context, final InputStream input, final Map<String, String> calloutParams); }
「例 - PostCalloutPluginインタフェース」は、com.oracle.callout.PostCalloutPlugin
インタフェースのJavaコードを示しています。
例 - PostCalloutPluginインタフェース
public interface PostCalloutPlugin { /** * Any custom properties or the header properties can be set at the * context level. * * @param context * @param input * @param out * @param calloutParams * @return */ public PluginOutput process(final PluginContext context, final InputStream input, final Map<String, String> calloutParams); }
callout.xsd
ファイルでは、コールアウト定義XMLファイルの形式を定義します。「例 - コールアウト定義スキーマ」はコンテンツを表示します。
例 - コールアウト定義スキーマ
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema targetNamespace="http://xmlns.oracle.com/mft" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:mft="http://xmlns.oracle.com/mft" elementFormDefault="qualified"> <xsd:element name="Callouts"> <xsd:complexType> <xsd:sequence> <xsd:element name="Callout" minOccurs="0" maxOccurs="unbounded"> <xsd:complexType> <xsd:sequence> <xsd:element minOccurs="0" maxOccurs="unbounded" ref="mft:Parameter"/> </xsd:sequence> <xsd:attribute name="name" use="required"> <xsd:simpleType> <xsd:restriction base="mft:non-empty-string"> <xsd:maxLength value="128"/> </xsd:restriction> </xsd:simpleType> </xsd:attribute> <!-- multiple values separated by comma are supported, possible values Source-pre, Target-pre, Target-post --> <xsd:attribute name="groupName" type="mft:non-empty-string" use="optional"/> <xsd:attribute name="implementationClass" type="mft:non-empty-string"/> <!-- jar name --> <xsd:attribute name="libraryName" type="mft:non-empty-string"/> <xsd:attribute name="timeout" type="xsd:integer" use="optional" default="30"/> <xsd:attribute name="description" type="mft:non-empty-string"/> <xsd:attribute name="helpText" type="mft:non-empty-string"/> </xsd:complexType> <xsd:unique name="Callout_UK"> <xsd:selector xpath="mft:Callout"/> <xsd:field xpath="@name"/> </xsd:unique> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="Parameter"> <xsd:complexType> <xsd:attribute name="name" type="mft:non-empty-string" use="required"/> <xsd:attribute name="parameterType" type="mft:parameterTypeLOV" use="required"/> <xsd:attribute name="basic" type="boolean" use="optional" default="false"/> <xsd:attribute name="mandatory" type="boolean" use="optional" default="false"/> <xsd:attribute name="hidden" type="boolean" use="optional" default="false"/> <!-- multiple values separated by comma is supported --> <xsd:attribute name="groupName" type="mft:non-empty-string" use="optional"/> <!-- sub-groups can have multiple values separated by comma. --> <xsd:attribute name="sub-groups" type="mft:non-empty-string" use="optional"/> <!-- VRule: defaultValue and parameterTypeLOV MUST match --> <xsd:attribute name="defaultValue" type="mft:non-empty-string" use="optional"/> <xsd:attribute name="listValue" type="mft:non-empty-string" use="optional"/> <xsd:attribute name="mapValue" type="mft:non-empty-string" use="optional"/> <!-- changed refValue from IDREF to non-empty-string as IDREF does not allow ",". In the future refValue can have value separated by ",". Ex: "xPathaParams, someOtherParams" --> <xsd:attribute name="refValue" type="mft:non-empty-string" use="optional"/> <!--attribute name="tpOverrideable" type="boolean" use="optional" default="true"/--> <xsd:attribute name="overrideLevel" type="mft:overrideLevelLOV" use="optional" default="all"/> <xsd:attribute name="displayName" type="mft:non-empty-string"/> <xsd:attribute name="description" type="mft:non-empty-string"/> <xsd:attribute name="helpText" type="mft:non-empty-string"/> </xsd:complexType> </xsd:element> <xsd:simpleType name="overrideLevelLOV"> <xsd:restriction base="string"> <xsd:enumeration value="admin"/> <xsd:enumeration value="tp"/> <xsd:enumeration value="host"/> <xsd:enumeration value="tpa"/> <xsd:enumeration value="all"/> </xsd:restriction> </xsd:simpleType> <xsd:simpleType name="non-empty-string"> <xsd:restriction base="string"> <xsd:minLength value="1"/> </xsd:restriction> </xsd:simpleType> <xsd:simpleType name="parameterTypeLOV"> <xsd:restriction base="string"> <xsd:enumeration value="float"/> <xsd:enumeration value="integer"/> <xsd:enumeration value="string"/> <xsd:enumeration value="boolean"/> <xsd:enumeration value="date"/> <xsd:enumeration value="SO"/> <xsd:enumeration value="MO"/> <xsd:enumeration value="credential"/> <xsd:enumeration value="list"/> <xsd:enumeration value="map"/> <xsd:enumeration value="ref"/> <xsd:enumeration value="hex"/> </xsd:restriction> </xsd:simpleType> </xsd:schema>
カスタム・コールアウト・アクションを検証できます。たとえば、チェックサムを検証する際に、コールアウト実装のプラグイン出力に例外オブジェクトを設定して検証できます。
public PluginOutput process(PluginContext context, InputStream input, Map<String, String> calloutParams) { PluginOutput res = new PluginOutput() ; boolean isValid = validateChecksum(context, input, calloutParams) ; if( ! isValid ){res.setException(new Exception("Checksum mismatch, corrupted payload.")) ; } return res ; }