第8章 API共通リファレンス
8.4 ステータス情報
8.4.7 置換クレンジング
注意
クレンジング関数が正常終了した場合だけ呼び出してください。正常終了でない場合の動作は不定です。
呼び出し形式
int iqreplace_cleanser_getStatusCode ( const IQREPLACE_CLEANSING_STATUS status, int index,
int groupID, int *code, char *message,
size_t messageBufferSize, void *reserve
);
パラメーターの説明
const IQREPLACE_CLEANSING_STATUS status 【IN】
置 換 ク レ ン ジ ン グ の ス テ ー タ ス 情 報 格 納 用 イ ン ス タ ン ス を 指 定 し ま す 。iqreplace_cleanser_createStatus関 数 で 取 得 し た
IQREPLACE_CLEANSING_STATUSインスタンスを指定します。
NULLを指定した場合、エラーとなります。
int index 【IN】
-1を指定してください。
詳細は「8.4.1 ステータス情報の構造と取得方法」を参照してください。
int groupID 【IN】
取得するステータス情報のIDを指定します。
指定する値については「8.4.7 置換クレンジング」を参照してください。
int *code 【OUT】
処理情報の数値を格納する領域を指定します。
取得呼び出し時のパラメーターをチェックする目的でNULLを指定することができます。NULLを指定した場合、処理情報値は取 得されません。
格納される値については「8.4.7 置換クレンジング」を参照してください。
char *message 【OUT】
復帰値に対応したメッセージを格納する領域のアドレスを指定します。領域は呼出元が確保する必要があります。
格納されるメッセージについては「8.3.5 置換クレンジングの復帰値／例外一覧」を参照してください。文字列はNULLターミネート されます。
メッセージは最長で1023バイトです(NULLターミネートは含みません)。
NULLを指定した場合、メッセージは取得されません。
size_t messageBufferSize 【IN】
messageパラメーターで与えられる領域の大きさをバイト数で指定します。
0を指定した場合はメッセージは取得されません。
指定されたバイト数がメッセージを格納するのに十分な大きさでない場合、可能な限り書き込みます。メッセージは途中で切れます が、NULLターミネート文字列になることは保証されます。
void *reserve 【IN】
予約域です。NULLを指定します。NULL以外を指定した場合はエラーになります。
復帰値
正常終了した場合は0で復帰します。エラーが発生した場合は0以外で復帰します。
復帰値の詳細は「8.3.5 置換クレンジングの復帰値／例外一覧」を参照してください。
パラメーターの説明
IQREPLACE_CLEANSER_HANDLE handle 【IN】
置換クレンジングのハンドルを指定します。iqreplace_cleanser_initialize関数で取得したIQREPLACE_CLEANSER_HANDLEを指 定します。
const char *mapName 【IN】
置換クレンジングサービス設定ファイルで定義した置換定義名称を指定します。
置換クレンジングサービス設定ファイルについては、「運用ガイド クレンジング編」の「5.2.4 置換クレンジングサービス設定ファイ ル」を参照してください。
ENCODING_TYPE encoding 【IN】
クレンジングする文字列のエンコーディングを指定します。
指定できる値はENCODING_TYPEを参照してください。
注意
mapNameパラメーターで指定した置換辞書のエンコーディングと異なるエンコーディングを指定した場合はエラーになります。
置換辞書については「クレンジングサービスの設定ファイル」を参照してください。
const char *source 【IN】
クレンジングする文字列が格納された領域のアドレスを指定します。文字列はNULLターミネートされている必要があります。
クレンジング可能な文字列は最長で10KBです(NULLターミネートは含みません)。
NULLを指定した場合、エラーとなります。
const IQREPLACE_CLEANSING_OPTION *option 【IN】
動作オプションを格納した領域のアドレスを指定します。
オプションの詳細はIQREPLACE_CLEANSING_OPTIONを参照してください。
char *result 【OUT】
クレンジング後の文字列を格納する領域のアドレスを指定します。領域は呼出元が確保する必要があります。
クレンジング後の文字列が格納されます。文字列はNULLターミネートされます。
置換後の文字列は最長で10KBです (NULLターミネートは含みません) 。 NULLを指定した場合、エラーになります。
size_t resultBufferSize 【IN】
resultパラメーターで与えられる領域の大きさをバイト数で指定します。
指定されたバイト数がクレンジング後の文字列を格納するのに十分な大きさでない場合、エラーになります。
クレンジング後の文字列長の目安は「3.5.4 クレンジング結果文字列長の計算式」を参照してください。
IQREPLACE_CLEANSING_STATUS status 【OUT】
置換クレンジングのステータス情報格納用インスタンスを指定します。
iqreplace_cleanser_createStatus数で取得したIQREPLACE_CLEANSING_STATUSインスタンスまたはNULLを指定します。
インスタンスを指定した場合、ステータス情報が格納されます。
NULLを指定した場合、ステータス情報は取得されません。
ステータス情報の詳細は「8.4.7 置換クレンジング」を参照してください。
char *message 【OUT】
復帰値に対応したメッセージを格納する領域のアドレスを指定します。領域は呼出元が確保する必要があります。
格納されるメッセージについては「8.3.5 置換クレンジングの復帰値／例外一覧」を参照してください。文字列はNULLターミネート されます。
メッセージは最長で1023バイトです(NULLターミネートは含みません)。 NULLを指定した場合、メッセージは取得されません。
size_t messageBufferSize 【IN】
messageパラメーターで与えられる領域の大きさをバイト数で指定します。
0を指定した場合はメッセージは取得されません。
指定されたバイト数がメッセージを格納するのに十分な大きさでない場合、可能な限り書き込みます。メッセージは途中で切れます が、NULLターミネート文字列になることは保証されます。
void *reserve 【IN】
予約域です。NULLを指定します。NULL以外を指定した場合はエラーになります。
復帰値
正常終了した場合は0で復帰します。エラーが発生した場合は0以外で復帰します。
復帰値の詳細は「8.3.5 置換クレンジングの復帰値／例外一覧」を参照してください。
3.5.4 クレンジング結果文字列長の計算式
各クレンジング機能を呼び出した場合、以下の計算式で求められる出力領域を確保しておくことで安全にクレンジングできます。
指定オプション 最大出力バイト数
部分一致 (入力データバイト数)*(置換辞書の置換先文字列カラムの最大文字数)*4+1
完全一致 前方一致 後方一致
(入力データバイト数)+(置換辞書の置換先文字列カラムの最大文字数)*4+1
第 4 章 Java API を利用したアプリケーション開発
本章では、Information Quality Java APIを利用したアプリケーション開発方法を説明します。
4.1 動作環境
Java (*1) ベンダ Oracle、富士通
エディション／バージョン J2SE 5.0 または Java SE 6
環境変数 (*2) ISIQ_HOME
Java VM引数 (*2) -Djava.library.path=%ISIQ_HOME%\bin
クラスパス J2SE 5.0の場合、%ISIQ_HOME%\lib\j2se5\cleanser.jar Java SE 6の場合、%ISIQ_HOME%\lib\cleanser.jar
*1 製品が32ビット版の場合、32ビット版が必要です。製品が64ビット版の場合、64ビット版が必要です。
*2 実行時のみ必要(コンパイル時は不要)
注意
・ あらかじめ「第1章 開発前に知っておくべきこと」を参照しておいてください。
・ プロセス起動方法によっては、システムの環境変数を引き継がない場合があります。JavaプロセスからISIQ_HOMEが参照できるよ うにしてください。
4.2 利用方法
以下のサンプルプログラム（指定文字列を全角統一する）を用いて、APIの利用方法を説明します。
注意
サンプルプログラムは、APIの利用方法を概説するためのものです。
ユーザーアプリケーションに、サンプルコードをそのまま組み込まないでください。
ユーザーアプリケーションの仕様／要件に合わせ、適切に設計／コーディングし直してください。
import com.fujitsu.informationquality.cleansing.api.*;
/** クレンジング処理のサンプルである。 */
public class Sample {
/** メイン。 */
public static void main(String[] _args) {
try {
execCharCleanser("1234567890クレンジング");
}
catch(UnsatisfiedLinkError e) {
System.err.println("環境が正しくありません。java.library.path, ISIQ_HOME等を確認してください。");
e.printStackTrace();
} }
/** 指定文字列を基本クレンジングする。 */
private static void execCharCleanser(String _target) throws UnsatisfiedLinkError
{
CharCleanser cleanser = null;
try {
// (1) クレンジング処理機能プロバイダへの接続を開く...4.2.1参照 cleanser = new CharCleanser();
cleanser.open();
// (2) クレンジング実行...4.2.2参照 CharCleansingResult result = cleanser.formatCharWidth(_target, CharCleansingOption.CharWidthType.FULL);
// (3) クレンジング結果確認...4.2.3参照 if(null != result.getResult())
System.out.println("(入力 / 結果 = " + _target + " / " + result.getResult() + ")");
else
System.out.println("クレンジングできませんでした。");
System.out.println(result.getStatusMap());
}
catch (IQException e) { erroutIQException(e);
} finally { try {
// (4) クレンジング処理機能プロバイダへの接続を閉じる...4.2.4参照 if(null != cleanser) cleanser.close();
}
catch (IQException e) {
System.err.println("--- exception in finally block start ---");
erroutIQException(e);
System.err.println("--- exception in finally block end ---");
} } }
/** IQExceptionを標準エラーに書き出す。 */
private static void erroutIQException(IQException _excp) {
// (5) 例外処理...4.2.5参照 System.err.println("[" + _excp.getCode() + "] " + _excp.getMessage());
_excp.printStackTrace();
} }
4.2.1 (1) クレンジング処理機能プロバイダへの接続を開く
クレンジング機能を利用するためには、最初にクレンジング処理機能プロバイダへの接続を開く必要があります。
接続を開くには、ICleanserConnectorインタフェースを実装する各種クレンザクラスを利用します。
クレンザクラスの一覧は以下のとおりです。
基本クレンジング機能を利用する場合 CharCleanser 住所クレンジング機能を利用する場合 JAddressCleanser 氏名クレンジング機能を利用する場合 JPersonalNameCleanser 法人名クレンジング機能を利用する場合 JCorporateNameCleanser 置換クレンジング機能を利用する場合 ReplaceCleanser
参考
・ 本章では、クレンジング機能を提供するクラス(上記クラス)を「クレンザクラス」と呼び、そのインスタンスを「クレンザインスタンス」と呼 ぶこととします。
・ 動作環境に違反(java.library.path、ISIQ_HOMEの指定に誤りがある、など)すると、java.lang.UnsatisfiedLinkErrorが発生します。
・ 住所/氏名/法人名/置換クレンジング処理機能プロバイダに接続を開くと、住所/氏名/法人名/置換クレンジングサービスへの接続 を行います。ただし、クレンジングサービスの利用可能接続数には上限があります。
また、通信プラットフォームの仕様にも接続数上限/接続閉鎖後の待機時間があり、接続を閉じても、待機時間中は接続数を圧迫 します。
詳細は、「運用ガイド クレンジング編」の「5.3.1 APIからの利用数について」を参照してください。
4.2.2 (2) クレンジング実行
「4.2.1 (1) クレンジング処理機能プロバイダへの接続を開く」で準備したクレンザインスタンスを利用して、クレンジング処理を行います。
クレンジング機能のバリエーションについては、「4.2.6 各クレンジング機能固有の利用方法」および、各種クレンザクラスのJava APIリ ファレンスを参照してください。
4.2.3 (3) クレンジング結果確認
「4.2.2 (2) クレンジング実行」のクレンジング処理結果を確認し、目的に応じて利用します。
クレンジング処理結果オブジェクト(ICleansingResultを実装するクラスオブジェクト)には、以下が含まれています。
クレンジング処理本来の結果オブジェクト : ICleansingResult#getResult()
クレンザクラスが返すクレンジング結果オブジェクトについては、「4.2.6 各クレンジング機能固有の利用方法」および、各種クレンザクラ スのJava APIリファレンスを参照してください。
参考
クレンジング処理が正常終了しても、ICleansingResult#getResult()がnullを返す場合があります。
例) 住所/氏名/法人名クレンジングメソッドに、住所/氏名/法人名として解析できない文字列を指定した場合 ICleansingResult#getResult()の返却値にアクセスする前には、nullチェックを行ってください。
クレンジング処理および結果のステータスマップ : ICleansingResult#getStatusMap()
クレンジング処理や処理結果に対する補足情報(=ステータス)のマップオブジェクトです。ステータスマップから、知りたいステータスを取り出して、判定等に使用します。
ステータスマップは、key=ステータスカテゴリ, value=ステータス値 の構造になっています。ステータスカテゴリは、各種クレンザクラスに よって異なります。一覧は以下のとおりです。
基本クレンザの場合 CharCleansingStatusCategory 住所クレンザの場合 JAddressCleansingStatusCategory 氏名クレンザの場合 JPersonalNameCleansingStatusCategory 法人名クレンザの場合 JCorporateNameCleansingStatusCategory 置換クレンザの場合 ReplaceCleansingStatusCategory
参考
ステータスについては、「8.4 ステータス情報」を参照してください。