付録G.3 カスタム受付フレームワークのAPI

ここでは,カスタム受付フレームワークが提供するAPIについて説明します。

<この項の構成>
(1) カスタム受付フレームワークのAPIの呼び出し順序
(2) CSCMsgCustomServiceDeliveryFactoryクラス
(3) CSCMsgCustomServiceDeliveryインターフェース
(4) APIの使用例

(1) カスタム受付フレームワークのAPIの呼び出し順序

受付処理が,カスタム受付フレームワークのAPIを呼び出す順序を次の図に示します。

図G-3 カスタム受付フレームワークのAPIの呼び出し順序

[図データ]

  1. CSCMsgCustomServiceDeliveryFactoryクラスのnewInstanceメソッドを呼び出して,CSCMsgCustomServiceDeliveryFactoryオブジェクトを取得します。
  2. 1.で取得したCSCMsgCustomServiceDeliveryFactoryオブジェクトのcreateCSCMsgCustomServiceDeliveryメソッドを呼び出して,CSCMsgCustomServiceDeliveryオブジェクトを取得します。
  3. 2.で取得したCSCMsgCustomServiceDeliveryオブジェクトのinvokeXMLメソッドまたはinvokeBinaryメソッドを呼び出して,カスタム受付フレームワークに要求電文を渡します。

(2) CSCMsgCustomServiceDeliveryFactoryクラス

(a) 説明

CSCMsgCustomServiceDeliveryFactoryクラスは,CSCMsgCustomServiceDeliveryFactoryオブジェクトの生成,CSCMsgCustomServiceDeliveryオブジェクトの生成などの機能を提供するファクトリクラスです。

(b) 形式

package jp.co.Hitachi.soft.csc.msg.message.reception.custom;
public abstract class CSCMsgCustomServiceDeliveryFactory {
 public static CSCMsgCustomServiceDeliveryFactory newInstance();
 public CSCMsgCustomServiceDelivery createCSCMsgCustomServiceDelivery();
}

(c) メソッド

CSCMsgCustomServiceDeliveryFactoryクラスのメソッドを次の表に示します。

メソッド名機能
newInstanceメソッドCSCMsgCustomServiceDeliveryFactoryオブジェクトを生成します。
createCSCMsgCustomServiceDeliveryメソッドCSCMsgCustomServiceDeliveryオブジェクトを生成します。
newInstanceメソッド
説明
CSCMsgCustomServiceDeliveryFactoryオブジェクトを生成します。
形式

public static CSCMsgCustomServiceDeliveryFactory newInstance();

パラメタ
なし。
例外
なし。
戻り値
  • CSCMsgCustomServiceDeliveryFactory
    CSCMsgCustomServiceDeliveryFactoryオブジェクトを返却します。

 

createCSCMsgCustomServiceDeliveryメソッド
説明
CSCMsgCustomServiceDeliveryオブジェクトを生成します。
形式

public CSCMsgCustomServiceDelivery createCSCMsgCustomServiceDelivery();

パラメタ
なし。
例外
なし。
戻り値
  • CSCMsgCustomServiceDelivery
    CSCMsgCustomServiceDeliveryオブジェクトを返却します。

(3) CSCMsgCustomServiceDeliveryインターフェース

(a) 説明

カスタム受付の受付処理が,カスタム受付フレームワークと電文の受け渡しをするためのメソッドを提供します。また,開発環境で登録したカスタム受付ユーザファイルを取得するメソッドを提供します。

(b) 形式

package jp.co.Hitachi.soft.csc.msg.message.reception.custom;
public interface CSCMsgCustomServiceDelivery {
 public String invokeXML(String cscCorrelationID, String cscServiceOperationName,
     String msg) throws CSCMsgServerException;
 public String invokeXML(String cscCorrelationID, String msg)
     throws CSCMsgServerException;
 public byte[] invokeBinary(String cscCorrelationID, String cscServiceOperationName,
     int requestMessageLength, byte[] msg) throws CSCMsgServerException;
 public byte[] invokeBinary(String cscCorrelationID, int requestMessageLength,
     byte[] msg) throws CSCMsgServerException;
 public InputStream getUserFile(String fileName);
}

(c) メソッド

CSCMsgCustomServiceDeliveryインターフェースのメソッドを次の表に示します。

メソッド名機能
invokeXMLメソッド(形式1)指定されたオペレーション名のサービスに対してXML電文のメッセージを送信し,その応答を返します。
invokeXMLメソッド(形式2)※1デフォルトのオペレーション名のサービスに対してXML電文のメッセージを送信し,その応答を返します。
invokeBinaryメソッド(形式1)指定されたオペレーション名のサービスに対してバイナリ電文のメッセージを送信し,その応答を返します。
invokeBinaryメソッド(形式2)※2デフォルトのオペレーション名のサービスに対してバイナリ電文のメッセージを送信し,その応答を返します。
getUserFileメソッド開発環境で登録したカスタム受付ユーザファイルのInputStreamを返します。
注※1
invokeXMLメソッド(形式1)のオペレーション名を省略した場合と同等のメソッドです。
注※2
invokeBinaryメソッド(形式1)のオペレーション名を省略した場合と同等のメソッドです。

 

invokeXMLメソッド(形式1)
説明
指定されたオペレーション名のサービスに対してXML電文のメッセージを送信し,その応答を返します。
形式

public String invokeXML(String cscCorrelationID,
   String cscServiceOperationName, String msg)
   throws CSCMsgServerException;

パラメタ
  • cscCorrelationID(クライアント相関ID)
    クライアント相関IDは,サービスリクエスタからの要求電文を一意に識別するための相関識別子です。
    クライアント相関IDが次の制限に従っていない場合,CSCMsgServerException例外をスローします。
    ・サイズ:255文字以内
    ・使用できる文字:半角の英数字,アンダーライン(_),ピリオド(.)およびハイフン(-)
    クライアント相関IDは,サービスリクエスタからの要求電文と,HCSCサーバで管理している実行履歴やログおよびトレースを対応づけるために使用します。したがって,HCSCサーバに送信した要求電文ごとに異なるIDを指定する必要があります。
    クライアント相関IDを省略する場合,nullまたは空文字列("")を指定します。
  • cscServiceOperationName(オペレーション名)
    オペレーション名は,要求先のサービス名に対するオペレーション名です。
    オペレーション名は,開発環境で定義したサービス部品のオペレーション名を指定します。
    オペレーション名が次の制限に従っていない場合,CSCMsgServerException例外をスローします。
    ・サイズ:255バイト以内
    ・使用できる文字:XMLSchemaのNCName定義文字
    カスタム受付定義画面で定義していないオペレーション名を指定した場合,CSCMsgServerException例外をスローします。
    オペレーション名を省略する(デフォルトのオペレーション名を使用する)場合,nullまたは空文字列("")を指定します。
  • msg(ユーザ電文)
    ユーザ電文は,サービスリクエスタからの要求電文(XML形式)です。
    要求電文がない場合,nullまたは空文字列("")を指定します。
例外
  • CSCMsgServerException
    次の場合にスローします。
    ・メソッドのパラメタに不正な値が指定された場合
    ・要求電文および応答電文のデータ変換でエラーが発生した場合
    ・要求先のサービス部品でエラーが発生した場合
戻り値
  • String
    ・通信モデルが同期の場合
     サービス部品の実行要求に対する応答電文(XML形式)を返却します。
     応答電文がない場合,nullを返却します。
    ・通信モデルが非同期の場合
     nullを返却します。

 

invokeXMLメソッド(形式2)
説明
デフォルトのオペレーション名のサービスに対してXML電文のメッセージを送信し,その応答を返します。
形式

public String invokeXML(String cscCorrelationID, String msg)
   throws CSCMsgServerException;

パラメタ
  • cscCorrelationID(クライアント相関ID)
    クライアント相関IDは,サービスリクエスタからの要求電文を一意に識別するための相関識別子です。
    クライアント相関IDが次の制限に従っていない場合,CSCMsgServerException例外をスローします。
    ・サイズ:255文字以内
    ・使用できる文字:半角の英数字,アンダーライン(_),ピリオド(.)およびハイフン(-)
    クライアント相関IDは,サービスリクエスタからの要求電文と,HCSCサーバで管理している実行履歴やログおよびトレースを対応づけるために使用します。したがって,HCSCサーバに送信した要求電文ごとに異なるIDを指定する必要があります。
    クライアント相関IDを省略する場合,nullまたは空文字列("")を指定します。
  • msg(ユーザ電文)
    ユーザ電文は,サービスリクエスタからの要求電文(XML形式)です。
    要求電文がない場合,nullまたは空文字列("")を指定します。
例外
  • CSCMsgServerException
    次の場合にスローします。
    ・メソッドのパラメタに不正な値が指定された場合
    ・要求電文および応答電文のデータ変換でエラーが発生した場合
    ・要求先のサービス部品でエラーが発生した場合
戻り値
  • String
    ・通信モデルが同期の場合
     サービス部品の実行要求に対する応答電文(XML形式)を返却します。
     応答電文がない場合,nullを返却します。
    ・通信モデルが非同期の場合
     nullを返却します。

 

invokeBinaryメソッド(形式1)
説明
指定されたオペレーション名のサービスに対してバイナリ電文のメッセージを送信し,その応答を返します。
形式

public byte[] invokeBinary(String cscCorrelationID,
   String cscServiceOperationName, int requestMessageLength, byte[] msg)
   throws CSCMsgServerException;

パラメタ
  • cscCorrelationID(クライアント相関ID)
    クライアント相関IDは,サービスリクエスタからの要求電文を一意に識別するための相関識別子です。
    クライアント相関IDが次の制限に従っていない場合,CSCMsgServerException例外をスローします。
    ・サイズ:255文字以内
    ・使用できる文字:半角の英数字,アンダーライン(_),ピリオド(.)およびハイフン(-)
    クライアント相関IDは,サービスリクエスタからの要求電文と,HCSCサーバで管理している実行履歴やログおよびトレースを対応づけるために使用します。したがって,HCSCサーバに送信した要求電文ごとに異なるIDを指定する必要があります。
    クライアント相関IDを省略する場合,nullまたは空文字列("")を指定します。
  • cscServiceOperationName(オペレーション名)
    オペレーション名は,要求先のサービス名に対するオペレーション名です。
    オペレーション名は,開発環境で定義したサービス部品のオペレーション名を指定します。
    オペレーション名が次の制限に従っていない場合,CSCMsgServerException例外をスローします。
    ・サイズ:255バイト以内
    ・使用できる文字:XMLSchemaのNCName定義文字
    ユーザ定義受付定義画面で定義していないオペレーション名を指定した場合,CSCMsgServerException例外をスローします。
    オペレーション名を省略する(デフォルトのオペレーション名を使用する)場合,nullまたは空文字列("")を指定します。
  • requestMessageLength(ユーザ電文長)
    ユーザ電文長は,要求電文の長さです。
    ユーザ電文長が次の制限に従っていない場合,CSCMsgServerException例外をスローします。
    ・0以上の整数値
    ・ユーザ電文(msgパラメタ)のバイト長以下の整数値
    要求電文がない場合,0を指定します。
    また,ユーザ電文(msgパラメタ)のバイト長より小さい値を指定した場合,要求電文の長さとして,ユーザ電文長(requestMessageLengthパラメタ)に指定した値を使用します。つまり,サービス部品に渡す要求電文には,ユーザ電文(msgパラメタ)のユーザ電文長(requestMessageLengthパラメタ)+1バイト目以降は含まれません。
  • msg(ユーザ電文)
    ユーザ電文は,サービスリクエスタからの要求電文(バイナリ形式)です。
    要求電文がない場合,nullまたは0バイトのバイト配列を指定します。
例外
  • CSCMsgServerException
    次の場合にスローします。
    ・メソッドのパラメタに不正な値が指定された場合
    ・要求電文および応答電文のデータ変換でエラーが発生した場合
    ・要求先のサービス部品でエラーが発生した場合
戻り値
  • byte[]
    ・通信モデルが同期の場合
     サービス部品の実行要求に対する応答電文(バイナリ形式)を返却します。
     応答電文がない場合,nullを返却します。
    ・通信モデルが非同期の場合
     nullを返却します。

 

invokeBinaryメソッド(形式2)
説明
デフォルトのオペレーション名のサービスに対してバイナリ電文のメッセージを送信し,その応答を返します。
形式

public byte[] invokeBinary(String cscCorrelationID,
   int requestMessageLength, byte[] msg)
   throws CSCMsgServerException;

パラメタ
  • cscCorrelationID(クライアント相関ID)
    クライアント相関IDは,サービスリクエスタからの要求電文を一意に識別するための相関識別子です。
    クライアント相関IDが次の制限に従っていない場合,CSCMsgServerException例外をスローします。
    ・サイズ:255文字以内
    ・使用できる文字:半角の英数字,アンダーライン(_),ピリオド(.)およびハイフン(-)
    クライアント相関IDは,サービスリクエスタからの要求電文と,HCSCサーバで管理している実行履歴やログおよびトレースを対応づけるために使用します。したがって,HCSCサーバに送信した要求電文ごとに異なるIDを指定する必要があります。
    クライアント相関IDを省略する場合,nullまたは空文字列("")を指定します。
  • requestMessageLength(ユーザ電文長)
    ユーザ電文長は,要求電文の長さです。
    ユーザ電文長が次の制限に従っていない場合,CSCMsgServerException例外をスローします。
    ・0以上の整数値
    ・ユーザ電文(msgパラメタ)のバイト長以下の整数値
    要求電文がない場合,0を指定します。
    また,ユーザ電文(msgパラメタ)のバイト長より小さい値を指定した場合,要求電文の長さとして,ユーザ電文長(requestMessageLengthパラメタ)に指定した値を使用します。つまり,サービス部品に渡す要求電文には,ユーザ電文(msgパラメタ)のユーザ電文長(requestMessageLengthパラメタ)+1バイト目以降は含まれません。
  • msg(ユーザ電文)
    ユーザ電文は,サービスリクエスタからの要求電文(バイナリ形式)です。
    要求電文がない場合,nullまたは0バイトのバイト配列を指定します。
例外
  • CSCMsgServerException
    次の場合にスローします。
    ・メソッドのパラメタに不正な値が指定された場合
    ・要求電文および応答電文のデータ変換でエラーが発生した場合
    ・要求先のサービス部品でエラーが発生した場合
戻り値
  • byte[]
    ・通信モデルが同期の場合
     サービス部品の実行要求に対する応答電文(バイナリ形式)を返却します。
     応答電文がない場合,nullを返却します。
    ・通信モデルが非同期の場合
     nullを返却します。

 

getUserFileメソッド
説明
パラメタに指定されたファイル名のカスタム受付ユーザファイルを読み込んで,ファイルの内容をストリームとして返します。
このメソッドは,カスタム受付ユーザファイルのファイル形式に関係なく,ストリームとしてファイルの内容をそのまま返します。このメソッドの呼び出し元で,ファイル形式に応じて処理してください(Propertiesクラスのloadメソッドでプロパティファイルとして読み込むなど)。
このメソッドで取得したストリームは,使用後に,呼び出し元で閉じてください。
形式

public InputStream getUserFile(String fileName);

パラメタ
  • fileName
    カスタム受付ユーザファイルのファイル名です。
    開発環境でカスタム受付を定義するときに登録したカスタム受付ユーザファイルのファイル名を指定します。
    使用できる文字は任意です。
例外
なし。
戻り値
  • InputStream
    カスタム受付ユーザファイルのストリームを返却します。
    パラメタに指定したファイル名のファイルが見つからなかった場合はnullを返却します。

(4) APIの使用例

カスタム受付フレームワークのAPIを利用して,受付処理をEJB(Stateless Session Bean)形式で実装する場合の実装例を次に示します。