ページの先頭行へ戻る
Interstage Application Server/Interstage Web Server Express Java EE運用ガイド(Java EE 6編)
FUJITSU Software

3.1.11 JAX-RSアプリケーションにおけるJSONデータの利用方法

3.1.11.1 JSONデータの概要

JSONデータはテキストデータで示されます。JSONデータの内容は、JSONオブジェクト、JSON配列によって構成されます。

JSONオブジェクトとJSON配列

JSONデータ内の名前と値のペアをJSONメンバーと本書では、表記します。

さらに、JSONメンバーの一つ以上の集合を、以降JSONオブジェクトと表記します。また、順序を持った一つ以上の値の集合をJSON配列と表記します。

JSONオブジェクトに含まれるJSONメンバーの名前部分は文字列で表現されます。

JSONオブジェクトとJSON配列は値については、「JSONデータにおける値」で説明します。

JSONデータは、JSONオブジェクトもしくはJSON配列を最上位の構成要素とします。この表現方式の詳細はRFC4627を参照してください。

JSONデータにおける値

JSONオブジェクトとJSON配列は値を持ちますが、この値は文字列、数値、真偽値、null値、JSONオブジェクト、JSON配列によって表現されます。

それぞれに指定可能な値の詳細はRFC4627を参照してください。

本書では、JSONデータの値をその内容によって以下のように表記します。

  1. 文字列で表現されているものをJSON文字列

  2. 数値で表現されているものをJSON数値

  3. 真偽値で表現されているものをJSON真偽値

  4. null値で表現されているものをJSON null値

また、JSONデータの値は上記の表現に加え、以下の表現も可能です。

  1. JSONオブジェクト

  2. JSON配列

つまり、JSON文字列/JSON数値/JSON真偽値/JSON null値の配列や、複数の種類の値を組み合わせたJSONデータの表現が可能です。(以下のJSONデータの例を参照してください。)

JSONデータがJSONオブジェクトによって表現される例

以下の例1、例2は同じデータとして扱われます。

例1

{"name":"Fujitsu,Taro","age":20," authority1":true,"authority2":false,"note":null}

例2

{
  "name":"Fujitsu,Taro",
  "age":20,
  "authority1":true,
  "authority2":false,
  "note":null
}

JSONデータがJSON配列によって表現される例

[2,3,5,7,11,13,17,19,23,29]

JSONデータが、JSON配列を値に含むJSONオブジェクトによって表現される例

{"color":["red","blue","white","green","black"],"amount":[10,5,0,3,6]}

3.1.11.2 JSONデータの利用方法

JSONデータを解析しJavaオブジェクトに変換するデシリアライズ機能、および、JavaオブジェクトをJSONデータに変換するシリアライズ機能があります。

デシリアライズ:

受信したJSONデータをアプリケーションに渡すJavaオブジェクトに変換すること

シリアライズ:

アプリケーションが返り値として返却するJavaオブジェクトを送信時にJSONデータに変換すること

JAX-RSアプリケーションにてJSONのシリアライズ/デシリアライズ機能を利用するためには、従来のJAX-RSアプリケーションの作成方法に加えて、以下の指定を行う必要があります。

これらの処理に必要な情報を説明します。

1)JSONデータのシリアライズ/デシリアライズ指定

シリアライズ/デシリアライズを行うために、JAX-RSアプリケーション中のApplicationサブクラスに @com.fujitsu.interstage.javaee.ws.rs.JSONMappingを指定する必要があります。

@JSONMappingの指定例

import javax.ws.rs.core.Application;
import javax.ws.rs.ApplicationPath;
import com.fujitsu.interstage.javaee.ws.rs.JSONMapping;

@ApplicationPath("/*")
@JSONMapping
public class JsonApp extends Application {
}

2)MIME型の指定

JAX-RSアプリケーションにて取り扱うJSONデータのMIMEデータ型を指定します。そのために、リソースメソッドの@Consumesや@Producesにて"application/json"の指定を行う必要があります。

MIMEデータ型の指定例

    @POST
    @Consumes("application/json")
    @Produces("application/json")
    public Result process(Input input){
    …
    }

3)JSONデータの変換先/変換元の指定

JSONデータとの変換を行うJavaクラスを指定するには、JSONデータの最上位要素であるJSONオブジェクトまたはJSON配列と変換可能な、以下のJavaクラスのうちのいずれかをリソースメソッドの引数または返り値の型として宣言する必要があります。

上記のクラスの内部要素(Java Beanのメンバや配列の要素など)には、その他のJava型も利用可能です。利用できるJavaクラスとJSONデータとの変換規則の詳細は、「3.1.11.3 シリアライズ規則」の「表3.1 シリアライズ規則(JSONオブジェクト)」、「表3.2 シリアライズ規則(JSON配列)」、「3.1.11.4 デシリアライズ規則」の「表3.4 デシリアライズ規則(JSONオブジェクト)」、「表3.5 デシリアライズ規則(JSON配列)」を参照してください。

3.1.11.3 シリアライズ規則

シリアライズに利用可能なJava型とJSONデータの対応規則を以下の3つの表にて説明します。

表中のJava型欄にはシリアライズする際のJava型を記載しています。JSONデータ欄にはシリアライズの結果として生成されるJSONデータを、シリアライズ規則欄にはJava型の値からシリアライズされるJSONデータの例や、シリアライズの条件、注意事項を記載します。

表3.1 シリアライズ規則(JSONオブジェクト)」、「表3.2 シリアライズ規則(JSON配列)」は、JSONオブジェクトもしくはJSON配列にシリアライズ可能なJava型を記載しています。シリアライズを行う場合は、この型のJavaクラスをリソースメソッドの返り値に指定する必要があります。

Javaオブジェクト内のメンバとなるJava型には、「表3.1 シリアライズ規則(JSONオブジェクト)」、「表3.2 シリアライズ規則(JSON配列)」、「表3.3 シリアライズ規則(その他メンバ)」で記載するものが使用可能です。

表3.1 シリアライズ規則(JSONオブジェクト)

Java型

JSONデータ

シリアライズ規則(Java型→JSONデータ)

Java Bean(任意のクラス)

JSONオブジェクト

・publicフィールド→JSONメンバー
・プロパティ→JSONメンバー
・同名のpublicフィールドとプロパティが存在している場合は、プロパティが優先されます。
・空のBean(publicフィールドもプロパティがない)の場合はJsonMappingExceptionが発生します。

・JSONオブジェクト内のJSONメンバーは順不同にてシリアライズを行います。

JSON null値

・null→JSON null値

java.util.Map<String, ?>

(型引数に指定できるものは、プリミティブ型を除く本書で説明するJava型のみとなります)

JSONオブジェクト

・マップ→JSONオブジェクト

・空マップ→空のJSONオブジェクト

JSON null値

・null→JSON null値

表3.2 シリアライズ規則(JSON配列)

Java型

JSONデータ

シリアライズ規則(Java型→JSONデータ)

java.util.List<?>

(型引数に指定できるものは、プリミティブ型を除く本書で説明するJava型のみとなります)

JSON配列

・配列→JSON配列

・空リスト→空のJSON配列

JSON null値

・null→JSON null値

表3.3 シリアライズ規則(その他メンバ)

Java型

JSONデータ

シリアライズ規則(Java型→JSONデータ)

boolean

JSON真偽値

・true→true
・false→false

byte

JSON数値

以下の範囲でシリアライズが行われます。

・Byte.MIN_VALUE~Byte.MAX_VALUE

double

JSON数値

以下の範囲でシリアライズが行われます。

・Double.MIN_VALUE~Double.MAX_VALUE

float

JSON数値

以下の範囲でシリアライズが行われます。

・Float.MIN_VALUE~Float.MAX_VALUE

int

JSON数値

以下の範囲でシリアライズが行われます。

・Integer.MIN_VALUE~Integer.MAX_VALUE

long

JSON数値

以下の範囲でシリアライズが行われます。

・Long.MIN_VALUE~Long.MAX_VALUE

short

JSON数値

以下の範囲でシリアライズが行われます。

・Short.MIN_VALUE~Short.MAX_VALUE

java.lang.Boolean

JSON真偽値

・true→true
・false→false

JSON null値

・null→JSON null値

java.lang.Byte

JSON数値

以下の範囲でシリアライズが行われます。

・Byte.MIN_VALUE~Byte.MIN_VALUE

JSON null値

・null→JSON null値

java.lang.Character

JSON文字列

・文字→JSON文字列

JSON null値

・null→JSON null値

java.lang.Double

JSON数値

以下の範囲でシリアライズが行われます。

・Double.MIN_VALUE~Double.MAX_VALUE

JSON null値

・null→JSON null値

java.lang.Float

JSON数値

以下の範囲でシリアライズが行われます。

・Float.MIN_VALUE~Float.MAX_VALUE

JSON null値

・null→JSON null値

java.lang.Integer

JSON数値

以下の範囲でシリアライズが行われます。

・Integer.MIN_VALUE~Integer.MAX_VALUE

JSON null値

・null→JSON null値

java.lang.Long

JSON数値

以下の範囲でシリアライズが行われます。

・Long.MIN_VALUE~Long.MAX_VALUE

JSON null値

・null→JSON null値

java.lang.Short

JSON数値

以下の範囲でシリアライズが行われます。

・Short.MIN_VALUE~Short.MAX_VALUE

JSON null値

・null→JSON null値

java.lang.String

JSON文字列

・文字列→JSON文字列

・以下の文字は\(%x5C)でエスケープされます。

・"(%x22)→\"
・\(%x5C)→\\
・/(%x2F)→\/
・backspace(%x62)→\b
・form feed(%x66)→\f
・line feed(%x6E)→\n
・carriage return(%x72)→\r
・tab(%x74)→\t

JSON null値

・null→JSON null値

3.1.11.4 デシリアライズ規則

JSONデータのデシリアライズを行うには、対応するJava型を用意する必要があります。その対応規則を以下の6つの表にて説明します。

表中のJSONデータ欄にはデシリアライズの対象とするJSONデータ、Java型欄にはデシリアライズする際のJSONデータに対応するJava型、デシリアライズ規則欄にはJSONデータからJavaオブジェクトにデシリアライズされたJavaオブジェクトの例や、デシリアライズの条件、注意事項を記載します。

表3.4 デシリアライズ規則(JSONオブジェクト)」、「表3.5 デシリアライズ規則(JSON配列)」は、JSONオブジェクトもしくはJSON配列からデシリアライズ可能なJava型を記載しています。デシリアライズを行う場合は、この型のJavaクラスをリソースメソッドの引数に指定する必要があります。

JSONオブジェクト、JSON配列中のメンバのデシリアライズ規則については「表3.4 デシリアライズ規則(JSONオブジェクト)」、「表3.5 デシリアライズ規則(JSON配列)」、「表3.6 デシリアライズ規則(JSON文字列)」、「表3.7 デシリアライズ規則(JSON数値)」、「表3.8 デシリアライズ規則(JSON真偽値)」、「表3.9 デシリアライズ規則(JSON null値)」を参照してください。

表3.4 デシリアライズ規則(JSONオブジェクト)

JSONデータ

Java型

デシリアライズ規則(JSONデータ→Java型)

JSONオブジェクト

Java Bean

(任意のクラス)

・JSONメンバー→publicフィールドまたはプロパティ

※JSONメンバーの名前と、publicフィールドまたはプロパティの名前が一致している必要があります。
・同名のpublicフィールドとプロパティが存在している場合は、プロパティが優先されます。
・空のBean(publicフィールドもプロパティがない)の場合はJsonMappingExceptionが発生します。
・getterのみのBeanは、同名のフィールド値が定義されていればそのフィールドがpublic以外であっても値が設定されます。

・JSONメンバーの名前に一致するpublicフィールドとプロパティのいずれもが存在しない場合、JsonMappingExceptionが発生します。

java.util.Map<String, ?>

(総称型でサポートする型引数はプリミティブ型を除く本書で説明するJava型のみとなります)

・空のJSONオブジェクト→空マップ

・JSONオブジェクト→マップ

表3.5 デシリアライズ規則(JSON配列)

JSONデータ

Java型

デシリアライズ規則(JSONデータ→Java型)

JSON配列

java.util.List<?>

(総称型でサポートする型引数はプリミティブ型を除く本書で説明するJava型のみとなります)

・JSON配列→リスト

・空のJSON配列→空リスト

表3.6 デシリアライズ規則(JSON文字列)

JSONデータ

Java型

デシリアライズ規則(JSONデータ→Java型)

JSON文字列

java.lang.String

・JSON文字列が文字列になりますが、エスケープ(\;%x5C)された文字は以下に示すとおりとなります。
・\"→"(%x22)
・\\→\(%x5C)
・\/→/(%x2F)
・\b→backspace(%x62)

・\f→form feed(%x66)

・\n→line feed(%x6E)
・\r→carriage return(%x72)
・\t→tab(%x74)
・\uXXXX→UNICODE文字

表3.7 デシリアライズ規則(JSON数値)

JSONデータ

Java型

デシリアライズ規則(JSONデータ→Java型)

JSON数値

boolean

・0→false
・0.0→false
・上記以外はtrueになります。

byte

以下の範囲でデシリアライズが行われます。

・Byte.MIN_VALUE~Byte.MAX_VALUE
・上記以外はJsonMappingExceptionが発生します。

char

以下の範囲でデシリアライズが行われます。

・0~65535は対応するUNICODE文字になります。
・上記以外はJsonMappingExceptionが発生します。

double

以下の範囲でデシリアライズが行われます。

・Double.MIN_VALUE~Double.MAX_VALUE
・上記の範囲外の数値の場合は、その値の最小値、または最大値になります。

float

以下の範囲でデシリアライズが行われます。

・Float.MIN_VALUE~Float.MAX_VALUE
・上記の範囲外の数値の場合は、その値の最小値、または最大値になります。

int

以下の範囲でデシリアライズが行われます。

・Integer.MIN_VALUE~Integer.MAX_VALUE
・上記以外はJsonMappingExceptionが発生します。

long

以下の範囲でデシリアライズが行われます。

・Long.MIN_VALUE~Long.MAX_VALUE
・上記以外はJsonMappingExceptionが発生します。

short

以下の範囲でデシリアライズが行われます。

・Short.MIN_VALUE~Short.MAX_VALUE
・上記以外はJsonMappingExceptionが発生します。

java.lang.Boolean

・0→false
・0.0→false
・上記以外はtrueになります。

java.lang.Byte

以下の範囲でデシリアライズが行われます。

・Byte.MIN_VALUE~Byte.MAX_VALUE
・上記以外はJsonMappingExceptionが発生します。

java.lang.Character

以下の範囲でデシリアライズが行われます。

・0~65535は対応するUNICODE文字になります。
・上記以外はJsonMappingExceptionが発生します。

java.lang.Double

以下の範囲でデシリアライズが行われます。

・Double.MIN_VALUE~Double.MAX_VALUE
・上記の範囲外の数値の場合は、その値の最小値、または最大値になります。

java.lang.Float

以下の範囲でデシリアライズが行われます。

・Float.MIN_VALUE~Float.MAX_VALUE
・上記の範囲外の数値の場合は、その値の最小値、または最大値になります。

java.lang.Integer

以下の範囲でデシリアライズが行われます。

・Integer.MIN_VALUE~Integer.MAX_VALUE
・上記以外はJsonMappingExceptionが発生します。

java.lang.Long

以下の範囲でデシリアライズが行われます。

・Long.MIN_VALUE~Long.MAX_VALUE
・上記以外はJsonMappingExceptionが発生します。

java.lang.Short

以下の範囲でデシリアライズが行われます。

・Short.MIN_VALUE~Short.MAX_VALUE
・上記以外はJsonMappingExceptionが発生します。

java.lang.String

・JSON数値→文字列

表3.8 デシリアライズ規則(JSON真偽値)

JSONデータ

Java型

デシリアライズ規則(JSONデータ→Java型)

JSON真偽値

boolean

・true→true
・false→false

java.lang.Boolean

・true→true
・false→false

java.lang.String

・JSON真偽値→文字列

表3.9 デシリアライズ規則(JSON null値)

JSONデータ

Java型

デシリアライズ規則(JSONデータ→Java型)

JSON null値

java.lang.Boolean

・null→null

java.lang.Byte

・null→null

java.lang.Double

・null→null

java.lang.Float

・null→null

java.lang.Integer

・null→null

java.lang.Long

・null→null

java.lang.Short

・null→null

java.lang.String

・null→null

Bean(任意のクラス)

・null→null

java.util.Map<String, ?>

(総称型でサポートする型引数はプリミティブ型を除く本書で説明するJava型のみとなります)

・null→null

java.util.List<?>

(総称型でサポートする型引数はプリミティブ型を除く本書で説明するJava型のみとなります)

・null→null

3.1.11.5 ライブラリモジュール

本機能を提供するライブラリは以下のとおりです。

C:\Interstage\F3FMisje6\glassfish\modules\jersey-core.jar

/opt/FJSVisje6/glassfish/modules/jersey-core.jar

本機能を利用する実装クラスのコンパイルでは、javacコマンドに以下のオプションを指定してください。

-classpath C:\Interstage\F3FMisje6\glassfish\modules\jersey-core.jar

-classpath /opt/FJSVisje6/glassfish/modules/jersey-core.jar

3.1.11.6 エンコーディング

本機能のデシリアライズは、UTF-8でエンコーディングされたJSONデータを対象に行われます。したがって、クライアント側から送出するJSONデータはUTF-8とする必要があります。

また、シリアライズはJSONデータをUTF-8でエンコードします。

3.1.11.7 コーディング例

JAX-RSアプリケーションにてシリアライズ/デシリアライズを行うコーディング例を記載します。

  1. Java BeanとJSONオブジェクトを変換する例

  2. java.util.Map<String,?>クラスとJSONオブジェクトを変換する例

上記a,bについてのコーディング例を以下に記載を示します。

a. Java BeanとJSONオブジェクトを変換する例

本コーディング例では、JSONオブジェクトとJava Beanの変換を行う2つのリソースメソッドを定義しています。HTTP GETリクエストの場合はqueryメソッドが、HTTP POSTリクエストの場合はupdateメソッドが呼び出されます。

  • Userクラス

    public class User {
        private Integer    userId;
        private String     userName;
        private Integer    age;
        private boolean    administrator;
    
        public Integer getUserId() {
            return userId;
        }
        public void setUserId(Integer userId) {
            this.userId = userId;
        }
    
        public String getUserName() {
            return userName;
        }
        public void setUserId(Integer userId) {
            this.userId = userId;
        }
    ・・・
    }
  • Usersクラス

    @Path("/user")
    public class Users {
        @Path("/{id}")
        @GET
        @Produces("application/json")
        public User query(@PathParam("id")Integer userId) {
           ・・・
           // userIdで指定されたIDのUserオブジェクトを返却する処理
        }
        @Path("/{id}")
        @POST
        @Produces("application/json")
        @Consumes("application/json")
        public User update (User updateData,@PathParam("id")Integer userId) {
           ・・・
           // userIdで指定されたIDのUserオブジェクトをupdateData
           // オブジェクトの内容で更新し、更新後のオブジェクトを返却する処理
        }
    }

b. java.util.Map<String,?>クラスを利用する例

本コーディング例では、JSONオブジェクトとjava.util.Map<String,String>クラスの変換を行うリソースメソッドを定義しています。

@Path("/Map")
public class JsonResource {
    @POST
    @Consumes("application/json")
    @Produces("application/json")
    public Map<String, String> process(Map<String, String> inputData) {
    ・・・
   //inputDataオブジェクトからキーに応じた値を取り出し、その値で更新する処理
    }
}