12.2.3 JSON-XML変換APIの詳細
サービスプラットフォームが提供するJSON-XML変換APIは,パッケージ「jp.co.Hitachi.soft.csc.common.converter.json」に所属します。
- 〈この項の構成〉
(1) パッケージ「jp.co.Hitachi.soft.csc.common.converter.json」に所属するクラス
パッケージ「jp.co.Hitachi.soft.csc.common.converter.json」に所属するインターフェースおよびクラスの一覧を次に示します。
●インターフェース
インターフェース名 |
説明 |
---|---|
JsonXmlConverter |
JSON-XML変換を実行するAPIを提供するクラスのインターフェースです。 このクラスのAPIを使用することで,JSON-XML変換を実行できます。 |
JsonXmlConverterProperty |
JSON-XML変換ライブラリの設定を変更するインターフェースです。 |
●クラス
クラス名 |
説明 |
---|---|
JsonXmlConverterFactory |
JSON-XML変換クラスのファクトリクラスです。 JsonXmlConverterFactory.newInstance()の呼び出しインスタンスを生成してください。 |
●例外クラス
クラス名 |
説明 |
---|---|
DataConvertException |
|
(2) インターフェースの詳細
(a) JsonXmlConverterインターフェース
JSON-XML変換を実行するAPIを提供するクラスのインターフェースです。
このクラスのAPIを使用することで,JSON-XML変換を実行できます。
JSON-XML変換クラスのファクトリクラスのJsonXmlConverterFactory.newJsonXmlConverter()の呼び出しインスタンスを生成してください。
JSON-XML変換クラスは,複数のインスタンスを生成できます。
生成したインスタンスはマルチスレッドで使用できます。
- ●クラス定義
public interface JsonXmlConverter
- ●メソッド
-
JsonXmlConverterインターフェースのメソッドを次の表に示します。
表12‒24 JsonXmlConverterインターフェースのメソッド メソッド名
説明
json2Xml
JSONをXMLに変換するメソッドです。
引数に指定したJSON形式のデータ(String)を,XML形式のデータ(String)に変換します。
xml2Json
XMLをJSONに変換するメソッドです。
引数に指定したXML形式のデータ(String)を,JSON形式のデータ(String)に変換します。
- ●json2Xml
-
引数に指定したJSON形式のデータ(String)を,XML形式のデータ(String)に変換します。
- 形式
java.lang.String json2Xml (java.lang.String json) throws DataConvertException
- 引数
-
-
json
変換元のJSON形式のデータを指定します。
なお,null,空文字,およびnull文字列は指定できません。
-
- 戻り値
-
JSON形式のデータを変換したXML形式のデータを返します。
- 例外
-
DataConvertException:JSON-XML変換処理でエラーが発生した場合にスローされる例外
次の場合に例外(DataConvertException)をスローし,エラーメッセージ(KDEC11202-E)をメッセージログに出力します。
-
JSONデータがnullの場合
-
JSONデータが空の場合
-
JSONデータがnull文字列だけの場合
-
引数に指定したJSON形式のデータが不正などでJSON-XML変換処理の実行に失敗した場合
-
- ●xml2Json
-
引数に指定したXML形式のデータ(String)を,JSON形式のデータ(String)に変換します。
- 形式
java.lang.String xml2Json (java.lang.String xml) throws DataConvertException
- 引数
-
-
xml
変換元のXMLデータを指定します。
なお,null,および空文字は指定できません。
-
- 戻り値
-
XML形式のデータを変換したJSON形式のデータを返します。
- 例外
-
DataConvertException:JSON-XML変換処理中にエラーが発生した場合にスローされる例外
次の場合に例外をスローし,エラーメッセージ(KDEC11202-E)をメッセージログに出力します。
-
XMLデータがnullの場合
-
XMLデータが空の場合
-
引数に指定したXML形式のデータが不正などでJSON-XML変換処理の実行に失敗した場合
-
(b) JsonXmlConverterPropertyインターフェース
JSON-XML変換ライブラリの設定を変更するインターフェースです。
JsonXmlConverterFactory.createConverterProperties()でインスタンスを取得してください。
設定を変更後,JsonXmlConverterFactory.newJsonXmlConverter(JsonXmlConverterProperty)のパラメタに指定することで,変更した設定を反映することができます。
変更しなかった設定は,デフォルト値を使用します。
- ●クラス定義
public interface JsonXmlConverterProperty
- ●注意事項
-
設定を変更したインスタンスを再利用して,設定の変更やJSON-XML変換を実行しないでください。設定を変更したインスタンスを再利用した場合の動作は保証しません。
- ●メソッド
-
JsonXmlConverterPropertyインターフェースのメソッドを次の表に示します。
表12‒25 JsonXmlConverterPropertyインターフェースのメソッド メソッド名
説明
setArrayName
JSONの配列をXMLの繰り返し要素に変換する際の要素名を変更します。
setElementName
JSONの配列をXMLの繰り返し要素に変換する際に,XMLの繰り返し要素内の子要素名の一部に任意の名称を設定できます。
setObjectName
オブジェクトから始まるJSON形式データを,XML形式に変換する際の要素名に任意の名称を設定できます。
setSimpleElementName
XMLの繰り返し要素内の単純型要素名を設定します。
setTypeIncludeEnabled
JSONデータ型をtype属性に出力するかどうかを設定します。
- ●setArrayName
-
JSONからXMLに変換する際に設定します。
配列から始まるJSON形式データを,XML形式に変換する際の要素名に任意の名称を設定できます。
- 形式
void setArrayName (java.lang.String arrayName)
- 引数
-
-
arrayName
JSONの配列をXMLの繰り返し要素に変換する際に変更する要素名を指定します。
-
- 注意事項
-
-
NCNameとして使用できる文字列を指定してください。
-
次の場合は,デフォルトの要素名としてcsc-arrayを使用します。
・設定を変更しない場合
・要素名にnullまたは空文字を設定した場合
-
- ●setElementName
-
JSONからXMLに変換する際に設定します。
JSONの配列をXMLの繰り返し要素に変換する際に,XMLの繰り返し要素内の子要素名の一部に任意の名称を設定できます。
変換後の要素名は,「設定値+アンダースコア(_) +親要素名」となります。
- 形式
void setElementName (java.lang.String elementName)
- 引数
-
-
elementName
XMLの繰り返し要素内の子要素名を指定します。
-
- 注意事項
-
-
NCName書式に使用できる文字列を指定してください。
-
次の場合は,設定値にcsc-elementを使用します。
・設定を変更しない場合
・要素名にnullまたは空文字を設定した場合
-
- ●setObjectName
-
JSONからXMLに変換する際に設定します。
オブジェクトから始まるJSON形式データを,XML形式に変換する際の要素名に任意の名称を設定できます。
- 形式
void setObjectName (java.lang.String objectName)
- 引数
-
-
objectName
オブジェクトから始まるJSON形式データを,XML形式に変換する際の要素名に任意の名称を設定できます。
-
- 注意事項
-
-
NCNameとして使用できる文字列を指定してください。
-
次の場合は,デフォルトの要素名としてcsc-objectを使用します。
・設定を変更しない場合
・nullまたは空文字を設定した場合
-
- ●setSimpleElementName
-
JSONからXMLに変換する,またはXMLからJSONに変換する際の設定をします。
-
JSONからXMLに変換する場合
JSONの配列の中の単純型要素名に任意の名称を設定することができます。
-
XMLからJSONに変換する場合
XML解析時に,配列内の単純型要素名を判断するために使用します。
-
- 形式
void setSimpleElementName (java.lang.String simpleElementName)
- 引数
-
-
simpleElementName
XMLの繰り返し要素内の単純型要素名を指定します。
なお,単純型要素名の単純型とは,次のことを指します。
・string
・number
・"true"
・"false"
-
- 注意事項
-
-
NCName書式に使用できる文字列を指定してください。
-
設定項目を変更してJSONデータからXMLデータを作成し,そのXMLデータからJSONデータに変換する場合は,同じ名称を設定してください。
-
次の場合は,設定値にcsc-simpleを使用します。
・設定を変更しない場合
・要素名にnullまたは空文字を設定した場合
-
- ●setTypeIncludeEnabled
-
JSONデータ型をtype属性に出力するかどうかを設定します。
JSONからXMLに変換する際に設定します。
デフォルトはfalseです。
- 形式
void setTypeIncludeEnabled (boolean isTypeIncludeEnabled)
- 引数
-
-
isTypeIncludeEnabled
trueを設定すると,type属性にJSONデータ型を出力します。
falseを設定すると,type属性を出力しません。
-
(3) クラスの詳細
(a) JsonXmlConverterFactoryクラス
JSON-XML変換クラスのファクトリクラスです。
newInstance()の呼び出しインスタンスを生成してください。
変換定義を設定するクラスJsonXmlConverterPropertyの取得,およびJSON-XML変換を実行するAPIを提供するクラスJsonXmlConverterのインスタンスの生成ができます。
- ●クラス定義
public abstract class JsonXmlConverterFactory extends java.lang.Object
- ●コンストラクタ
-
JsonXmlConverterFactoryクラスのコンストラクタを次に示します。
JsonXmlConverterFactory ()
●JsonXmlConverterFactory
- 形式
public JsonXmlConverterFactory ()
- ●メソッド
-
JsonXmlConverterFactoryクラスのメソッドを次の表に示します。
表12‒26 JsonXmlConverterFactoryクラスのメソッド メソッド名
説明
createConverterProperties
JSON-XML変換クラスの変換定義を管理するクラスのインスタンスを取得します。
newInstance
JSON-XML変換クラスのファクトリクラスのインスタンスを生成します。
newJsonXmlConverter
JSON-XML変換クラスのインスタンスを生成します。
- ●createConverterProperties
-
JSON-XML変換クラスの変換定義を管理するクラスのインスタンスを取得します。
- 形式
public abstract JsonXmlConverterProperty createConverterProperties ()
- 戻り値
-
JSON-XML変換クラスの変換定義を管理するクラスを返します。
- 例外
-
ありません。
- ●newInstance
-
JSON-XML変換クラスのファクトリクラスのインスタンスを生成します。
- 形式
public static JsonXmlConverterFactory newInstance ()
- 戻り値
-
JSON-XML変換クラスのファクトリクラスのインスタンスを返します。
- 例外
-
ありません。
- ●newJsonXmlConverter(形式1)
-
JSON-XML変換クラスのインスタンスを生成します。
JSON-XML変換ライブラリ変換定義はデフォルト値を適用します。
JSON-XML変換クラスは,複数のインスタンスを生成できます。
生成したインスタンスはマルチスレッドで使用できます。
public abstract JsonXmlConverter newJsonXmlConverter () throws DataConvertException
- 戻り値
-
JSON-XML変換クラスのインスタンスを返します。
- 例外
-
DataConvertException:JSON-XML変換処理でエラーが発生した場合にスローされる例外
次の場合に例外をスローし,エラーメッセージ(KDEC11201-E)をメッセージログに出力します。
-
内部例外が発生した場合
-
- ●newJsonXmlConverter(形式2)
-
JSON-XML変換クラスのインスタンスを生成します。
JSON-XML変換クラスは,複数のインスタンスを生成できます。
生成したインスタンスはマルチスレッドで使用できます。
- 形式
public abstract JsonXmlConverter newJsonXmlConverter (JsonXmlConverterProperty property) throws DataConvertException
- 引数
-
-
property
JSON-XML変換ライブラリ変換定義
なお,nullを指定した場合はデフォルト値が適用されます。
-
- 戻り値
-
JSON-XML変換クラスのインスタンスを返します。
- 例外
-
DataConvertException:JSON-XML変換処理でエラーが発生した場合にスローされる例外
次の場合に例外をスローし,エラーメッセージ(KDEC11201-E)をメッセージログに出力します。
-
変換定義に設定した値が不正な場合
-
(4) 例外クラスの詳細
(a) DataConvertExceptionクラス
JSON-XML変換クラスの例外を扱うクラスです。
JSON-XML変換処理中に発生する例外を包括します。
変換定義に設定した値が不正な場合もこの例外がスローされます。
このクラスは,JSON-XML変換APIで発生した例外の情報,および例外の詳細メッセージを保持します。
- ●クラス定義
public class DataConvertException extends java.lang.Exception
- ●コンストラクタ
-
DataConvertExceptionクラスのコンストラクタを次の表に示します。
表12‒27 DataConvertExceptionクラスのコンストラクタ コンストラクタ名
説明
DataConvertException
- (形式1)
-
DataConvertExceptionインスタンスを生成し,例外の原因となるクラスを設定します。
- (形式2)
-
DataConvertExceptionインスタンスを生成し,詳細メッセージを設定します。
- (形式3)
-
DataConvertExceptionインスタンスを生成し,詳細メッセージと例外の原因となるクラスを設定します。
- ●DataConvertException(形式1)
-
DataConvertExceptionインスタンスを生成し,例外の原因となるクラスを設定します。
- 形式
public DataConvertException (java.lang.Exception e)
- 引数
-
-
e
例外の原因となるクラスを指定します。
-
- ●DataConvertException(形式2)
-
DataConvertExceptionインスタンスを生成し,詳細メッセージを設定します。
- 形式
public DataConvertException (java.lang.String errMsg)
- 引数
-
-
errMsg
詳細メッセージを指定します。
-
- ●DataConvertException(形式3)
-
DataConvertExceptionインスタンスを生成し,詳細メッセージと例外の原因となるクラスを設定します。
- 形式
public DataConvertException (java.lang.String errMsg, java.lang.Throwable e)
- 引数
-
-
errMsg
詳細メッセージを指定します。
-
e
例外の原因となるクラスを指定します。
-