5.6.5　Java呼出アクティビティ

(a)　CustomClassInterfaceMインターフェース

package jp.co.Hitachi.soft.csc.bp.receiver.ejb;
 
public interface CustomClassInterfaceM {
    public Object invoke(
        String processName,
        int version,
        String activityName,
        Object... inputData
    ) throws CSBUserException, CSBSystemException;
}

Javaクラスの内容について次に説明します。

引数

仮引数名	説明
processName	ビジネスプロセス名
version	ビジネスプロセスのバージョン
activityName	アクティビティ名
inputData	［Java呼出アクティビティ］ダイアログの［引数用割当変数］で指定した変数※

戻り値

［Java呼出アクティビティ］ダイアログの［戻り値用割当変数］に指定した変数に代入されます。

例外

throwされる例外がCSBUserExceptionか，CSBSystemExceptionかによって処理が異なります。また，この2つの例外以外の例外が発生した場合，処理が中断されます。この場合，プロセスの実行状態を永続化しているときには，ロールバックが実行されます。

CSBUserExceptionがthrowされた場合

Java呼出アクティビティにフォルト処理が設定されている場合，CSBUserExceptionがthrowされると，フォルトコネクションでフォルト処理として定義されているアクティビティが実行されます。

Java呼出アクティビティにフォルト処理が設定されていない場合，invokeJavaFaultが発生したものとして処理が進められます。

CSBUserExceptionのインターフェースを次に示します。

 package jp.co.Hitachi.soft.csc.bp;
 
 public class CSBUserException extends Exception {
     public CSBUserException() { super(); }
     public CSBUserException(String message) { super(message); }
 }

CSBSystemExceptionがthrowされた場合

CSBSystemExceptionがthrowされると，システム例外が発生したものとして処理が中断されます。このとき，プロセスの実行状態を永続化している場合には，ロールバックが実行されます。

CSBSystemExceptionのインターフェースを次に示します。

package jp.co.Hitachi.soft.csc.bp;
 
 public class CSBSystemException extends Exception {
     public CSBSystemException() { super(); }
     public CSBSystemException(String message) { super(message); }
     public CSBSystemException(String message, Throwable cause) {
         super(message, cause);
     }
     public CSBSystemException(Throwable cause) { super(cause); }
 }

(b)　CustomClassInterfaceインターフェース

package jp.co.Hitachi.soft.csc.bp.receiver.ejb;
 
public interface CustomClassInterface {
    public Object invoke(
        String processName,
        int version,
        String activityName,
        Object inputData
    ) throws CSBUserException, CSBSystemException;
}

ポイント

CustomClassInterfaceは，CustomClassInterfaceMの互換用インターフェースです。CustomClassInterfaceMを使用することを推奨します。

Javaクラスの内容について次に説明します。

引数

仮引数名	説明
processName	ビジネスプロセス名
version	ビジネスプロセスのバージョン
activityName	アクティビティ名
inputData	［Java呼出アクティビティ］ダイアログの［引数用割当変数］で指定した変数※

戻り値

［Java呼出アクティビティ］ダイアログの［戻り値用割当変数］に指定した変数に代入されます。

例外

throwされる例外がCSBUserExceptionか，CSBSystemExceptionかによって処理が異なります。またこの2つの例外以外の例外が発生した場合，処理が中断されます。このとき，プロセスの実行状態を永続化している場合には，ロールバックが実行されます。

CSBUserException，またはCSBSystemExceptionがthrowされた場合の処理については，「(a)　CustomClassInterfaceMインターフェース」の戻り値の説明を参照してください。

CSBUserExceptionおよびCSBSystemException以外の例外が発生した場合，処理が中断されます。このとき，プロセスの実行状態を永続化している場合には，ロールバックが実行されます。

注意事項

• ［Java呼出アクティビティ］ダイアログの［引数用割当変数］および［戻り値用割当変数］に指定する変数の型と，このインターフェースの引数および戻り値の型の対応を次に示します。

  ［引数用割当変数］および［戻り値用割当変数］の変数型	引数および戻り値の型
  boolean	java.lang.Boolean
  numeric	java.lang.Double
  string	java.lang.String
  XML	byte[]
  non-XML	byte[]
  any	byte[]

  上記の型以外を指定した場合，エラー（KDEC20030-E）になります。

• 利用するJavaクラスのインターフェースはcscbp_ejb.jarに含まれます。そのため，コンパイルするときには，cscbp_ejb.jarをクラスパスに追加する必要があります。Eclipseのビルドパスにcscbp_ejb.jarが存在しないときは，<インストールディレクトリ>\CSC\lib\cscbp_ejb.jarをビルドパスに追加してください。

• Javaプログラムでは，呼び出しごとにデフォルトコンストラクタでインスタンスが生成されます。そのため，インスタンスにデータを保持することはできません。

(a)　フォルト処理を実行する場合の定義

フォルト処理の定義手順を次に示します。

1. フォルトが発生するアクティビティとフォルト処理を実行するアクティビティをキャンバスに配置し，詳細を定義します。

   フォルト処理を実行するアクティビティは複数定義できます。

   アクティビティの配置方法については，「5.4.1　アクティビティを配置する」を参照してください。各アクティビティの定義方法の詳細については，「5.6　アクティビティの定義」を参照してください。

2. フォルトコネクションを利用してフォルトが発生するアクティビティとフォルト処理を実行するアクティビティを連結します。

   アクティビティの連結方法については，「5.4.2(2)　連結の設定方法」を参照してください。また，フォルトコネクションを利用できるアクティビティについては，「5.4.2(5)　アクティビティの連結条件」を参照してください。

3. 連結線をダブルクリックします。

   ［フォルト処理の割当］ダイアログが表示されます。

   ［フォルト処理の割当］ダイアログの入力・表示内容の詳細については，マニュアル「サービスプラットフォーム リファレンス」の「1.4.6　フォルト処理の割当ダイアログ」を参照してください。なお，フォルト処理に割り当てられる変数はメッセージ型（XML）だけです。メッセージ型（non-XMLおよびany）は割り当てられません。

4. フォルト処理の条件を定義します。

   フォルトの対象となる変数と，フォルトが発生した場合に処理する連絡先のアクティビティを，それぞれ［割当変数］および［遷移先］ドロップダウンリストで指定します。

   定義していないフォルトが発生した場合のフォルト処理を設定する場合，［割当変数］ドロップダウンリストで「catch-all」を選択します。

5. ［OK］ボタンをクリックします。

(b)　フォルト処理の定義で使用するフォルト電文を定義するスキーマファイル

フォルト電文を定義するスキーマファイルの格納先を次に示します。

<サービスプラットフォームのインストールディレクトリ>\CSC\schema\fault\cscinvokejavafault.xsd

フォルト電文を定義するスキーマファイルを次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema elementFormDefault="qualified"
            targetNamespace="http://www.msg.csc.soft.Hitachi.co.jp/cscBpJava"
            xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="fault">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="exception-name"       type="xsd:string"/>
        <xsd:element name="exception-message"    type="xsd:string"/>
        <xsd:element name="exception-error-code" type="xsd:string"/>
        <xsd:element name="exception-detail"     type="xsd:string"/>
        <xsd:element name="scope-name"           type="xsd:string"/>
        <xsd:element name="activity-name"        type="xsd:string"/>
        <xsd:element name="activity-type"        type="xsd:string"/>
        <xsd:element name="process-instance-id"  type="xsd:string"/>
        <xsd:element name="root-ap-info"         type="xsd:string"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>

設定できる要素を次に示します。

exception-name

例外名（完全修飾クラス名）を設定します。

exception-message^※

例外情報（CSBUserException.getMessage()で取得した情報）を設定します。

exception-error-code^※

CSBUserExceptionのerrorCodeに設定した情報（ユーザが任意に設定できる情報）を設定します。

exception-detail^※

CSBUserExceptionのdetailに設定した情報（ユーザが任意に設定できる情報）を設定します。

scope-name

Java呼出アクティビティが所属するスコープ名を設定します。

activity-name

フォルトが発生したアクティビティ名を設定します。

activity-type

フォルトが発生したアクティビティの型名を設定します。

アクティビティの型名には，javaを設定してください。

process-instance-id

プロセスインスタンス識別子を設定します。

root-ap-info

ルートアプリケーション情報を設定します。

注※

CSBUserExceptionに要素と対応する情報が設定されていない場合，空要素（空タグ）が設定されます。

(a)　getProperties

filePathで指定した，外部プロパティファイルを必要に応じて読み込み，keyで指定する文字列にマッピングされているGroupIDに分類されたすべてのプロパティを保持するMapを返します。

Map型返り値の各エントリのkeyはプロパティパス，valueはプロパティ値を保持しています。

一度読み込んだ外部プロパティファイルは，処理の高速化のため次回以降の再読み込みを抑制するためキャッシングします。

API仕様

APIの仕様を次の表に示します。

表5‒14　getPropertiesのAPI仕様

#	項目	値
1	パッケージ	jp.co.Hitachi.soft.csc.dt.api.propertiesutil
2	クラス	CSCCustomGroupedProperties
3	メソッド	getProperties
4	引数1	filePath 外部プロパティファイルのパス
5	引数1の型	java.lang.String
6	引数2	keyword 取得対象キーワード
7	引数2の型	java.lang.String
8	戻り値	keywordにマッピングされたグループに属するプロパティのMap
9	戻り値の型	java.util.Map<java.lang.String, java.lang.String>

記述例を次に示します。

public static Map<String,String> getProperties(String filePath, String keyword)
    throws FileNotFoundException,
           IOException,
           SecurityException,
           CSCExtAPIInvalidFileContentsException,
           CSCExtAPIInvalidGroupIDException,
           CSCExtAPIInvalidEscapeSequenceException,
           CSCExtAPIDuplicateMappingStringException,
           CSCExtAPIUnclosedQuotedStringException,
           CSCExtAPIUnknownGroupIDException,
           CSCExtAPIInvalidPropertyPathException,
           CSCExtAPIIllegalArgumentException,
           CSCExtAPIKeyNotFoundException,
           CSCExtAPIOrphanedStringException;

障害対策

getPropertiesメソッドでは，次の表に示すエラーが発生するおそれがあります。エラーを検出した場合は，次の表に示す例外をスローして処理を中断します。

表5‒15　getPropertiesの障害および例外クラス

障害内容	例外クラス
指定された外部プロパティファイルが存在しません。	FileNotFoundException
指定された外部プロパティファイルの読み込み中に入出力エラーが発生しました。	IOException
指定された外部プロパティファイルの読み込み中にセキュリティエラーが発生しました。	SecurityException
指定された外部プロパティファイル内に不正なUnicodeエスケープシーケンスが存在します。	CSCExtAPIInvalidFileContentsException
GroupIDが不正です。	CSCExtAPIInvalidGroupIDException
MappingStringまたはPropertyValueに不正なエスケープシーケンスが存在します。	CSCExtAPIInvalidEscapeSequenceException
グループマッピング部に重複したMappingStringが存在します。	CSCExtAPIDuplicateMappingStringException
MappingStringまたはPropertyValueの引用符が閉じられていません。	CSCExtAPIUnclosedQuotedStringException
MappingStringまたはPropertyValueの引用符が閉じたあとに不適切な文字が存在しています。	CSCExtAPIOrphanedStringException
プロパティ部に未定義のGroupIDが指定されています。	CSCExtAPIUnknownGroupIDException
PropertyPath内のパス要素がXML要素名として不正です。	CSCExtAPIInvalidPropertyPathException
次のどちらかのエラーが発生しています。 filePathまたはkeywordがnullの場合 filePathが空文字列の場合	CSCExtAPIIllegalArgumentException
keywordに合致するMappingStringが存在しません。	CSCExtAPIKeyNotFoundException

注

CSCExtAPIで始まる例外クラスはすべてjp.co.Hitachi.soft.csc.dt.api.propertiesutil.exceptionパッケージに属し，jp.co.Hitachi.soft.csc.dt.api.propertiesutil.exception.CSCExtAPIException抽象クラスを継承します。

キャッシュ

getPropertiesメソッド呼び出し時に実行する，外部プロパティファイルの読込処理はキャッシングします。そのため，同じ外部プロパティファイルを使用する2回目以降のgetPropertiesメソッドの処理性能は向上します。

キャッシュはJ2EEサーバの起動中，保持されます。そのため，J2EEサーバ起動中にすでに読み込まれた外部プロパティファイルに変更を加えても，内容は反映されません。変更内容を反映するには，J2EEサーバを再起動する必要があります。

キャッシュはAPIおよびカスタムファンクションで共通です。APIを利用して読み込んだ外部プロパティファイルのキャッシュは，カスタムファンクションでも有効です。また，カスタムファンクションで読み込んだ外部プロパティファイルのキャッシュは，APIでも有効です。

配置

Javaクラスから利用できるAPIは，既存のcscdt_api.jarにパッケージングして提供します。

(b)　外部プロパティファイルの設定

APIおよびカスタムファンクションを利用するには，外部プロパティファイルが必要です。

外部プロパティファイルは，ISO8859-1エンコーディングされたjava.util.Properties形式で作成します。定義ファイルの入力形式の詳細については，マニュアル「サービスプラットフォーム リファレンス」の「6.2　定義ファイルの入力形式」を参照してください。

外部プロパティファイルは，次の部から構成されます。

• グループマッピング部

• プロパティ部

各部の出現順序，出現回数は問いません。グループマッピング部の規則に従った行はグループマッピング部，プロパティ部の規則に従った行はプロパティ部として，APIおよびカスタムファンクションに正しく認識されます。

グループマッピング部

プロパティを分類するグループの定義と，グループにマッピングする文字列の対応を定義します。

グループマッピング部は，次の形式で定義します。

GroupID = [MappingString[,][,MappingString…]]

GroupID

GroupIDは，英数字およびアンダースコアで構成された任意の文字列です。ただし，先頭文字に数字を指定することはできません。

重複したGroupIDは，java.util.Propertiesの仕様によって除去されるため検出できません。重複したGroupIDを指定した場合の動作はサポートの対象外となります。

MappingString

MappingStringは，コンマ（,）で区切った文字列をGroupIDにマッピングすることを指示します。MappingStringが省略された場合は，空文字列をGroupIDにマッピングすることを指示します。

MappingStringは次に示す規則に従って記述します。

• MappingStringは，外部プロパティファイル内で一意になるように指定してください。重複したMappingStringを検出すると，APIまたはカスタムファンクションはエラー終了します。

• MappingStringの次の文字は取り除かれます。

  ・先頭のスペース

  ・末尾のスペース

  ・ダブルクォーテーション（"）

  そのため，「abc」，「△abc」，「abc△」，「"abc"」は，すべて「abc」として定義されます。正確に「abc△」を指定したい場合は，「"abc△"」とダブルクォーテーション（"）で囲む必要があります。

• MappingString内にコンマ（,），円マーク（¥），ダブルクォーテーション（"）を含める場合は，例外を除き，それぞれ「¥¥,」，「¥¥¥¥」，「¥¥"」とエスケープする必要があります。プロパティファイルのエスケープ仕様によって，「¥」は「¥¥」と記述する必要があるため，すべての1文字の「¥」を「¥¥」と2文字で記述します。

  例えば「"ABC"」を指定する場合は「¥¥"ABC¥¥"」，「Co.,LTD.」を指定する場合は，「Co.¥¥,LTD.」と記述します。

• MappingString全体を「"」で囲んだ場合はコンマ（,）をエスケープする必要はありません。例えば，「"Co., LTD."」「"Co.¥¥, LTD."」「Co.¥¥, LTD.」はすべて「Co.,LTD.」と解釈されます。

• MappingString全体を「"」で囲まない場合（先頭文字が「"」でない場合）は，「"」をエスケープする必要はありません。例えば，「A"B」および「A¥¥"B」は「A"B」と解釈されます。また，「AB"」および「AB¥¥"」は「AB"」と解釈されます。

グループマッピング部の記述例を次に示します。

●有効なグループマッピングの記述例

Group1 = 
Group2 = aaa, bbb

Group1には空文字列を，Group2には「aaa」と「bbb」をマッピングをすることを指示します。

Group1 = aaa,
Group2 = bbb, ccc

Group1には「aaa」と空文字列を，Group2には「bbb」と「ccc」をマッピングすることを指示します。

●不正なグループマッピングの記述例

Group1 = aaa,
Group2 = bbb,

Group1には「aaa」と空文字列を，Group2には「bbb」と空文字列をマッピングすることを指示していますが，空文字列が重複しているのでエラーとなります。

プロパティ部

プロパティパスとプロパティ値の対を定義します。

プロパティパスの接頭子（ピリオド（.）で区切られた最初の文字列要素）は，グループの分類に使用します。

プロパティパスの接頭子を除いた部分は，プロパティのキーとして利用します。データ変換アクティビティから利用できるカスタムファンクションでは，ピリオド（.）で区切られた各文字列をXMLノードとした階層構造に展開します。

プロパティ部は，次の形式で定義します。

GroupID.PropertyPath = PropertyValue

GroupID

GroupIDは，グループマッピング部で定義したGroupIDを指定します。

PropertyPath

PropertyPathは，プロパティのパスを定義します。ピリオド（.）は，セパレータとして使用します。各パス要素は，XML要素名の規則に従って指定します。ただし，パス要素にピリオド（.）を含める場合は「¥¥.」とエスケープする必要があります。

また，java.util.Propertiesは，等号（=），コロン（:），および空白文字を，キーと値のセパレータと認識するため，パス要素にコロン（:）を含める場合は，「¥:」とエスケープする必要があります。

PropertyValue

PropertyValueは，GroupID，PropertyPathに対応するプロパティ値を定義します。

PropertyValueは，次の規則に従って記述します。コンマ（,）のエスケープが不要なこと以外はMappingStringの記述規則と同じです。

• PropertyValueの次の文字は取り除かれます。

  ・先頭のスペース

  ・末尾のスペース

  ・ダブルクォーテーション（"）

  そのため，「abc」，「△abc」，「abc△」，「"abc"」は，すべて「abc」として定義されます。正確に「abc△」を指定したい場合は，「"abc△"」とダブルクォーテーション（"）で囲む必要があります。

• PropertyValue内に円マーク（¥），ダブルクォーテーション（"）を含める場合は，それぞれ「¥¥¥¥」「¥¥"」とエスケープする必要があります。例えば，「"ABC"」を指定する場合は「¥¥"ABC¥¥"」，「C:¥Program Files」を指定する場合は「C:¥¥¥¥Program Files」と記述する必要があります。

外部プロパティファイルの定義例

外部プロパティファイルの定義例を次に示します。

# GROUP MAPPING PART
production = PROD, Production Environment, 本番環境
development = DEV, Development Environment, 開発環境
# PROPERTY PART
production.static_host = https://tp1server.hoge.com
production.static_port = 10100
development.static_host = https://testserver.fuga.com
development.static_port = 10200
development.elmA.elmB = SomeValue

この定義例では，productionグループのキーとして「PROD」，「Production Environment」または「本番環境」を定義し，developmentグループのキーとして「DEV」，「Development Environment」または「開発環境」を定義しています。

また，プロパティ部のGroupIDとプロパティの関係は次のようになっています。

表5‒16　定義例のグループとプロパティの関係

GroupID	PropertyPath	PropertyValue
production	static_host	https://tp1server.hoge.com
	static_port	10100
development	static_host	https://testserver.fuga.com
	static_port	10200
	elmA.elmB	SomeValue

(c)　外部プロパティファイルの動作

データ変換アクティビティから利用できるカスタムファンクションの利用例を基に，外部プロパティファイルがどのように動作するかを次に示します。

図5‒12　外部プロパティファイルの動作

1. APIの引数として渡された文字列に合致するMappingStringを検索し，対応するGroupIDを取得します。

2. 1.で取得したGroupIDで始まるプロパティを取得対象として選択します。

3. 2.で選択したプロパティのそれぞれについて，PropertyPathをパス要素に分解し，各要素をノードとしたXML階層を作成します。

4. 3.で作成したノードの値として，PropertyValueを設定します。