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

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

〈この項の構成〉

(1)　カスタム受付フレームワークのAPIの呼び出し順序
(2)　CSCMsgCustomServiceDeliveryFactoryクラス
(3)　CSCMsgCustomServiceDeliveryインターフェース
(4)　APIの使用例
(5)　注意事項

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

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

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

CSCMsgCustomServiceDeliveryFactoryクラスのnewInstanceメソッドを呼び出して，CSCMsgCustomServiceDeliveryFactoryオブジェクトを取得します。
1.で取得したCSCMsgCustomServiceDeliveryFactoryオブジェクトのcreateCSCMsgCustomServiceDeliveryメソッドを呼び出して，CSCMsgCustomServiceDeliveryオブジェクトを取得します。
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 byte[] invokeXML(String cscCorrelationID,
      String cscServiceOperationName, byte[] msg)
      throws CSCMsgServerException;
  public String invokeXML(String cscCorrelationID, String msg)
      throws CSCMsgServerException;
  public byte[] invokeXML(String cscCorrelationID, byte[] 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）	指定されたオペレーション名のサービスに対してバイト配列型のXML電文のメッセージを送信し，その応答を返します。応答も，バイト配列型になります。
invokeXMLメソッド（形式3）^※1	デフォルトのオペレーション名のサービスに対してXML電文のメッセージを送信し，その応答を返します。
invokeXMLメソッド（形式4）^※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または空文字列（""）を指定します。

nullまたは空文字（""）を指定してデータ変換などで変更しない場合，ビジネスプロセスに空の電文を渡します。

例外

CSCMsgServerException

次の場合にスローします。

・メソッドのパラメタに不正な値が指定された場合

・要求電文および応答電文のデータ変換でエラーが発生した場合

・要求先のサービス部品でエラーが発生した場合

戻り値

String

・通信モデルが同期の場合

　サービス部品の実行要求に対する応答電文（XML形式）を返却します。

　応答電文がない場合，nullを返却します。

・通信モデルが非同期の場合

　nullを返却します。

invokeXMLメソッド（形式2）

説明

指定されたオペレーション名のサービスに対して，バイト配列型のXML電文のメッセージを送信し，その応答を返します。応答も，バイト配列型になります。

ユーザ電文をバイト配列型で扱うカスタム受付の場合，このメソッドを使用することで，String型への変換処理を省くことができます。

形式

public byte[] invokeXML(String cscCorrelationID,
    String cscServiceOperationName, byte[] 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を指定します。

nullまたは空文字（""）を指定してデータ変換などで変更しない場合，ビジネスプロセスに空の電文を渡します。

例外

CSCMsgServerException

次の場合にスローします。

・メソッドのパラメタに不正な値が指定された場合

・要求電文および応答電文のデータ変換でエラーが発生した場合

・要求先のサービス部品でエラーが発生した場合

戻り値

byte[]

・通信モデルが同期の場合

　サービス部品の実行要求に対する応答電文（XML形式）を返却します。

　応答電文がない場合，nullを返却します。

・通信モデルが非同期の場合

　nullを返却します。

invokeXMLメソッド（形式3）

説明

デフォルトのオペレーション名のサービスに対して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または空文字列（""）を指定します。

nullまたは空文字（""）を指定してデータ変換などで変更しない場合，ビジネスプロセスに空の電文を渡します。

例外

CSCMsgServerException

次の場合にスローします。

・メソッドのパラメタに不正な値が指定された場合

・要求電文および応答電文のデータ変換でエラーが発生した場合

・要求先のサービス部品でエラーが発生した場合

戻り値

String

・通信モデルが同期の場合

　サービス部品の実行要求に対する応答電文（XML形式）を返却します。

　応答電文がない場合，nullを返却します。

・通信モデルが非同期の場合

　nullを返却します。

invokeXMLメソッド（形式4）

説明

デフォルトのオペレーション名のサービスに対して，バイト配列型のXML電文のメッセージを送信し，その応答を返します。応答も，バイト配列型になります。

ユーザ電文をバイト配列型で扱うカスタム受付の場合，このメソッドを使用することで，String型への変換処理を省くことができます。

形式

public byte[] invokeXML(String cscCorrelationID, byte[] msg)
    throws CSCMsgServerException;

パラメタ

cscCorrelationID（クライアント相関ID）

クライアント相関IDは，サービスリクエスタからの要求電文を一意に識別するための相関識別子です。

クライアント相関IDが次の制限に従っていない場合，CSCMsgServerException例外をスローします。

・サイズ：255文字以内

・使用できる文字：半角の英数字，アンダーバー（_），ピリオド（.）およびハイフン（-）

クライアント相関IDは，サービスリクエスタからの要求電文と，HCSCサーバで管理しているログおよびトレースを対応づけるために使用します。したがって，HCSCサーバに送信した要求電文ごとに異なるIDを指定する必要があります。

クライアント相関IDを省略する場合，nullまたは空文字列（""）を指定します。
msg（ユーザ電文）

ユーザ電文は，サービスリクエスタからの要求電文（XML形式）です。

要求電文がない場合，nullを指定します。

nullまたは空文字（""）を指定してデータ変換などで変更しない場合，ビジネスプロセスに空の電文を渡します。

例外

CSCMsgServerException

次の場合にスローします。

・メソッドのパラメタに不正な値が指定された場合

・要求電文および応答電文のデータ変換でエラーが発生した場合

・要求先のサービス部品でエラーが発生した場合

戻り値

byte[]

・通信モデルが同期の場合

　サービス部品の実行要求に対する応答電文（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バイトのバイト配列を指定します。

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バイトのバイト配列を指定します。

nullまたは0バイトのバイト配列を指定してデータ変換などで変更しない場合，ビジネスプロセスに空の電文を渡します。

例外

CSCMsgServerException

次の場合にスローします。

・メソッドのパラメタに不正な値が指定された場合

・要求電文および応答電文のデータ変換でエラーが発生した場合

・要求先のサービス部品でエラーが発生した場合

戻り値

byte[]

・通信モデルが同期の場合

　サービス部品の実行要求に対する応答電文（バイナリ形式）を返却します。

　応答電文がない場合，nullを返却します。

・通信モデルが非同期の場合

　nullを返却します。

getUserFileメソッド

説明

パラメタに指定されたファイル名のカスタム受付ユーザファイルを読み込んで，ファイルの内容をストリームとして返します。

このメソッドは，カスタム受付ユーザファイルのファイル形式に関係なく，ストリームとしてファイルの内容をそのまま返します。このメソッドの呼び出し元で，ファイル形式に応じて処理してください（Propertiesクラスのloadメソッドでプロパティファイルとして読み込むなど）。

このメソッドで取得したストリームは，使用後に，呼び出し元で閉じてください。

形式

public InputStream getUserFile(String fileName);

パラメタ

fileName

カスタム受付ユーザファイルのファイル名です。

開発環境でカスタム受付を定義するときに登録したカスタム受付ユーザファイルのファイル名を指定します。

使用できる文字は任意です。

例外

なし。

戻り値

InputStream

カスタム受付ユーザファイルのストリームを返却します。

パラメタに指定したファイル名のファイルが見つからなかった場合はnullを返却します。

ページの先頭へ

(4)　APIの使用例

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

MyReception.java

package com.example.sample.reception.ejb;
 
import javax.ejb.EJBObject;
 
/**
 * 受付処理(Stateless Session Bean)の実装例(Remoteインターフェース)
 */
public interface MyReception extends EJBObject {
  public String invoke(String cscCorrelationID, String cscServiceOperationName, String msg) throws RemoteException;
}

MyReceptionHome.java

package com.example.sample.reception.ejb;
 
import java.rmi.RemoteException;
 
import javax.ejb.CreateException;
import javax.ejb.EJBHome;
 
/**
 * 受付処理(Stateless Session Bean)の実装例(Homeインターフェース)
 */
public interface MyReceptionHome extends EJBHome {
  public MyReception create() throws RemoteException, CreateException;
}

MyReceptionBean.java

package com.example.sample.reception.ejb;
 
import java.rmi.RemoteException;
 
import javax.ejb.CreateException;
import javax.ejb.EJBException;
import javax.ejb.SessionBean;
import javax.ejb.SessionContext;
 
import jp.co.Hitachi.soft.csc.msg.message.reception.CSCMsgServerException;
import jp.co.Hitachi.soft.csc.msg.message.reception.custom.CSCMsgCustomServiceDelivery;
import jp.co.Hitachi.soft.csc.msg.message.reception.custom.CSCMsgCustomServiceDeliveryFactory;
 
/**
 * 受付処理(Stateless Session Bean)の実装例(Beanクラス)
 */
public class MyReceptionBean implements SessionBean {
  private static final CSCMsgCustomServiceDeliveryFactory factory =
      CSCMsgCustomServiceDeliveryFactory.newInstance();
  private CSCMsgCustomServiceDelivery delivery;
  private SessionContext context;
 
  public MyReceptionBean() {
  }
 
  public void ejbActivate() throws EJBException, RemoteException {
  }
 
  public void ejbCreate() throws CreateException {
    // CSCMsgCustomServiceDeliveryオブジェクトを生成
    delivery = factory.createCSCMsgCustomServiceDelivery();
  }
 
  public void ejbPassivate() throws EJBException, RemoteException {
  }
 
  public void ejbRemove() throws EJBException, RemoteException {
    // CSCMsgCustomServiceDeliveryオブジェクトを破棄
    delivery = null;
  }
 
  public String invoke(final String cscCorrelationID, final String cscServiceOperationName, final String msg) {
    try {
      // カスタム受付フレームワークを呼び出す
      final String response = delivery.invokeXML(cscCorrelationID, cscServiceOperationName, msg);
      return response;
    } catch (CSCMsgServerException e) {
      // カスタム受付フレームワークの例外をキャッチ
      // 例外処理を実装すること
    }
  }
 
  public void setSessionContext(final SessionContext sc) throws EJBException {
    context = sc;
  }
}

ページの先頭へ

(5)　注意事項

カスタム受付フレームワークのAPIを呼び出す際は，カスタム受付が開始状態である必要があります。
カスタム受付の開始操作を実行後，開始状態になるまでの間にカスタム受付フレームワークのAPIを呼び出した場合はエラーが発生します。

ページの先頭へ

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

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

(2) CSCMsgCustomServiceDeliveryFactoryクラス

(a) 説明

(b) 形式

(c) メソッド

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

(a) 説明

(b) 形式

(c) メソッド

(4) APIの使用例

(5) 注意事項

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

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

(2)　CSCMsgCustomServiceDeliveryFactoryクラス

(a)　説明

(b)　形式

(c)　メソッド

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

(a)　説明

(b)　形式

(c)　メソッド

(4)　APIの使用例

(5)　注意事項