12.2.3　JSON-XML変換APIの詳細

(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属性を出力しません。

(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）をメッセージログに出力します。

• 変換定義に設定した値が不正な場合

(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

  例外の原因となるクラスを指定します。