サービスプラットフォームが提供するデータ変換アクティビティに相当する機能です。データ変換APIでは，入力としてデータ変換前の電文を受け取り，出力としてデータ変換後の電文を返します。

(a)　データ形式

データ変換APIでは，データ変換前，およびデータ変換後の電文のデータ形式にXMLとバイナリを指定できます。

データ変換前，およびデータ変換後のデータ形式の組み合わせのパターンを次に示します。

• XML→XML
• XML→バイナリ
• バイナリ→XML
• バイナリ→バイナリ

(b)　データ変換前とデータ変換後の電文の数量関係

データ変換APIではデータ変換前とデータ変換後の電文が1対1となるデータ変換だけをサポートします。データ変換アクティビティで指定できるN対1のデータ変換については，データ変換APIでサポートしていません。

(c)　キャッシュの利用

データ変換APIを使用したデータ変換でも，データ変換定義で使用するフォーマット定義，およびデータ変換定義のキャッシュ機能を利用できます。定義情報がキャッシュされている場合，キャッシュを利用してデータ変換をします。また，データ変換時にキャッシュされていない定義情報が指定された場合は，データ変換の際にキャッシュとして登録されます。

キャッシュ処理の詳細については，「11.1.2(2)　キャッシュ操作」を参照してください。

(d)　データ変換基盤がサポートする機能の利用

データ変換基盤で実装されている機能は，データ変換APIを使用したデータ変換でも使用することができます。ただし，次の機能については制限事項があります。

• キャッシュ処理
  データ変換APIを使用したデータ変換では，バイナリフォーマット定義およびデータ変換定義だけがキャッシュの対象となります。XML電文オブジェクト，およびXML Schemaはキャッシュの対象にできません。
  キャッシュ処理の詳細については，「11.1.2(2)　キャッシュ操作」を参照してください。
  
• XML Schemaの指定
  要求電文，および応答電文のデータ形式がXMLの場合，データ変換ではXML Schemaを使用しません。データ変換のメソッドの引数にXML Schemaの定義ファイルが指定されても参照しません。また，XML Schemaのキャッシュも登録されません。ただし，データ変換のメソッドの引数に，定義ファイルの種別，およびキャッシュ名の指定は必要です。
  

データ変換APIでは，cscprecacheコマンドに相当するフォーマット定義，およびデータ変換定義のキャッシュ処理を実現するAPIを提供します。データ変換で使用するフォーマット定義，およびデータ変換定義の定義情報を事前にキャッシュすることで，初回のリクエスト処理の性能向上を実現できます。

(a)　キャッシュ名

定義情報のキャッシュは，キャッシュの種別ごとに一意となるキャッシュ名で管理されます。定義情報を登録および使用する場合は，データ変換APIの呼び出し元で必ずキャッシュ名を指定します。キャッシュ名で使用できる文字種は，半角英数字，アンダーバー（_），アットマーク（@），ハイフン（-），およびドル記号（$）です。最大文字列長は128バイトです。

(b)　キャッシュの登録対象

データ変換APIでは，次の定義情報をキャッシュできます。

• バイナリフォーマット定義
• データ変換定義（XSLTスタイルシート）

(c)　キャッシュの保存方法

データ変換APIのキャッシュの保存方法を次の図に示します。

図11-2　キャッシュの保存方法

キャッシュの上限数，および生存期間は次のとおりです。

●キャッシュの上限数

キャッシュの上限数はデータ変換APIのシステムプロパティで管理されます。

データ変換APIのシステムプロパティの詳細については，「11.1.2(4)　プロパティの変更」を参照してください。

●キャッシュの生存期間

登録されたキャッシュは，キャッシュの登録数が上限数に達するまで保持されます。キャッシュがあふれた場合，最後に参照されてから最も時間の経過しているキャッシュが削除されます。

(d)　キャッシュ操作の機能概要

データ変換APIのキャッシュ操作では，次の機能が利用できます。

• キャッシュの登録
• キャッシュの存在確認
• キャッシュの削除
• キャッシュ名の一覧取得
• キャッシュの一括削除

以降で，それぞれの機能について説明します。

●キャッシュの登録

フォーマット定義，およびデータ変換定義の定義情報をキャッシュします。

• 登録されていないキャッシュにこの機能を使用する場合
  キャッシュを新規に登録します。
  
• すでに登録されているキャッシュにこの機能を使用する場合
  キャッシュを更新します。
  

キャッシュの登録処理でXML Schemaが指定された場合は，メソッド引数不正エラーが発生します。

●キャッシュの存在確認

フォーマット定義，およびデータ変換定義の定義情報がキャッシュされているかどうか確認します。キャッシュの存在確認の結果は真偽値で返します。キャッシュの存在確認処理でXML Schemaが指定された場合はメソッド引数不正エラーが発生します。

●キャッシュの削除

キャッシュの登録機能によって登録された定義情報のキャッシュを削除します。登録されていないキャッシュに対してこの機能を使用すると，キャッシュの削除処理をしないで正常終了します。キャッシュの削除処理でXML Schemaが指定された場合はメソッド引数不正エラーが発生します。

●キャッシュ名の一覧取得

フォーマット定義，およびデータ変換定義のキャッシュ名の一覧を取得します。キャッシュ名の一覧は，Set<String>型で返します。キャッシュ名の順序性は保証されません。キャッシュが登録されていない場合は，空のSetを返します。また当処理でXML Schemaが指定された場合はメソッド引数不正エラーが発生します。

●キャッシュの一括削除

フォーマット定義，およびデータ変換定義の定義情報のキャッシュをすべて削除します。キャッシュが登録されていない場合は，キャッシュの削除処理をしないで正常終了します。

データ変換APIではデータ変換に必要な設定（キャッシュやプロパティ）を複数保持できます。この設定を保持する単位を変換グループと呼びます。変換グループを使用することで，データ変換の設定（キャッシュやプロパティ）を業務ごとに管理できます。変換グループに設定された情報は，J2EEサーバを停止するか，変換グループを破棄するまで保持されます。変換グループはグループ名で識別します。グループ名はJ2EEサーバで一意とする必要があります。

データ変換APIを使用する場合は，最初のデータ変換APIの呼び出し元で任意のグループ名を指定し，データ変換やキャッシュ操作を行うオブジェクトを取得してから設定してください。

データ変換APIの変換グループごとの設定の保存イメージを次の図に示します。

図11-3　グループごとのキャッシュの保存イメージ

(a)　グループ名

グループ名で使用できる文字種は，半角英数字，アンダーバー（_），アットマーク（@），ハイフン（-），およびドル記号（$）です。最大文字列長は32バイトです。

(b)　変換グループに関する機能

データ変換APIの変換グループで使用できる機能を次に示します。

• 変換グループの取得
• 変換グループの削除

それぞれの機能について説明します。

●変換グループの取得

指定された変換グループ名の変換グループを取得します。指定された変換グループが登録されていない場合は，新規に生成します。

●変換グループの削除

指定された変換グループ名の変換グループを削除します。変換グループが存在しない場合は，変換グループの削除処理をしないで，正常終了します。

データ変換API，およびデータ変換基盤の動作はシステムプロパティで変更できます。システムプロパティはusrconf.properties（J2EEサーバ用ユーザプロパティファイル）に指定します。

ここでは，データ変換APIのシステムプロパティについて説明します。

データ変換基盤で定義しているシステムプロパティの詳細については，マニュアル「サービスプラットフォーム リファレンス」の「3.14　データ変換コマンドとバイナリパースコマンドで利用するファイル」を参照してください。

usrconf.propertiesの詳細については，マニュアル「アプリケーションサーバ リファレンス 定義編(サーバ定義)」の「2.4　usrconf.properties（J2EEサーバ用ユーザプロパティファイル）」，および，マニュアル「サービスプラットフォーム システム構築・運用ガイド」の「2.3.9　J2EEサーバ用ユーザプロパティファイル（usrconf.properties）を設定する」を参照してください。

　

データ変換APIが定義するシステムプロパティを次に示します。

表11-1　データ変換APIが定義するシステムプロパティ

キー名称	デフォルト値	説明
csc.dt.formatdef.maxcache.num.<グループ名>	2,147,483,647	バイナリフォーマット定義をキャッシュできる数を1〜2,147,483,647の整数で指定します。このプロパティの指定値は，バイナリフォーマット定義のキャッシュの上限値となります。 設定値はデフォルト値を推奨します。
csc.dt.transformdef.maxcache.num.<グループ名>	2,147,483,647	データ変換定義をキャッシュできる数を1〜2,147,483,647の整数で指定します。 設定値はデフォルト値を推奨します。
csc.dt.telegram.undefined.characterCode.<グループ名>	ERROR	バイナリデータの文字コード変換処理で未定義の文字コードが検出された際の動作を，ERRORまたはREPLACEのどちらかの値で指定します。 ERRORを指定した場合，検出時にエラーとなり処理を終了します。 REPLACEを指定した場合，未定義部分の文字コードを空白の文字コードに置換して処理します。
csc.dt.codeTable.rootPath.<グループ名>	<サービスプラットフォームのインストールディレクトリ >\\CSC\\userlib\\codetables	Code Converterで使用するコード変換テーブル格納パスのルートパスを絶対パスで指定します。ディレクトリ区切りは「/」または「\\」を使用します。存在しないディレクトリまたはファイルを設定した場合，グループの生成に失敗します。
csc.dt.debugtrace	OFF	デバッグ情報の出力有無をONまたはOFFのどちらかの値を指定します。 ONを指定した場合，デバッグ情報を出力します。 OFFを指定した場合，デバッグ情報を出力しません。 未定義，未設定，または不正な値を設定した場合，デフォルト値を使用します。
csc.dt.debugtrace.filepath	<サービスプラットフォームのログ出力ディレクトリ>\\csc	デバッグ情報の出力先パスを絶対パスで指定します。 ディレクトリ区切りは「/」または「\\」を使用します。 未定義，未設定，または存在しないディレクトリを指定した場合，デフォルト値を使用します。 デフォルトの出力先のディレクトリが存在しない場合に作成されます。 csc.dt.debugtraceでONを指定した場合だけ有効となります。
csc.dt.debugtrace.filenum	4	デバッグ情報ファイルの最大面数を1〜16の整数で指定します。 未定義，未設定，または不正な値を設定した場合，デフォルト値を使用します。 csc.dt.debugtraceでONを指定した場合だけ有効となります。
csc.dt.debugtrace.filesize	20971524	デバッグ情報ファイルの1面当たりの最大サイズを4,096〜2,147,483,647（単位：バイト）の整数で指定します。 未定義，未設定，または不正な値を設定した場合，デフォルト値を使用します。 csc.dt.debugtraceでONを指定した場合だけ有効となります。
csc.dt.pool.DocumentBuilder.initialSize	0	DOMパーサプールを作成するときの初期割り当て数を0〜2,147,483,647の整数で指定します。 0を指定すると，J2EEサーバの起動時にDocumentBuilderプールは生成されません。
csc.dt.pool.DocumentBuilder.maxSize	64	DOMパーサの最大プール数を0〜2,147,483,647の整数で指定します。 HCSCサーバ内のすべてのリクエスト受付の最大実行数と，データ変換APIから実行されるリクエストの最大実行数の総和以上の値を指定します。

　

データ変換APIでは，データ変換やキャッシュ操作で障害が発生した場合，メッセージログにメッセージを出力し，データ変換API専用の例外クラスのオブジェクトをスローします。また，データ変換基盤でトレース情報を性能解析トレースへ出力します。

データ変換API専用の例外クラスの詳細については，「11.1.3(5)　例外クラスの詳細」を参照してください。

データ変換APIで出力するログおよびトレースの種類について説明します。

(a)　メッセージログ

データ変換APIを操作するときのインフォメーション情報や障害時のエラー情報をメッセージログへ出力します。

メッセージログの詳細については，マニュアル「サービスプラットフォーム システム構築・運用ガイド」の「7.4.1　メッセージログ」を参照してください。

(b)　性能解析トレース

データ変換基盤の性能解析トレースを出力します。データ変換の前後で出力される0x9A43および0x9A44のイベントIDの付加情報（OPT（ASCII））に，要求電文，応答電文，およびデータ変換定義のキャッシュ名を出力します。

データ変換基盤の性能解析トレースの取得ポイントの詳細については，マニュアル「サービスプラットフォーム システム構築・運用ガイド」の「7.4.3　性能解析トレース」を参照してください。データ変換基盤のイベントIDおよび付加情報を使用した性能解析の調査方法については，「11.1.6　データ変換時のボトルネックの特定」を参照してください。