付録A.3 カスタム受付フレームワークのAPI
ここでは,カスタム受付フレームワークが提供するAPIについて説明します。
- 〈この項の構成〉
(1) カスタム受付フレームワークのAPIの呼び出し順序
受付処理が,カスタム受付フレームワークの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を返します。 |
- 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電文のメッセージを送信し,その応答を返します。応答も,バイト配列型になります。
ユーザ電文をバイト配列型で扱うカスタム受付の場合,このメソッドを使用することで,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を指定します。
-
- 例外
-
-
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または空文字列("")を指定します。
-
- 例外
-
-
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を指定します。
-
- 例外
-
-
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バイトのバイト配列を指定します。
-
- 例外
-
-
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)形式で実装する場合の実装例を次に示します。
-
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を呼び出した場合はエラーが発生します。