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データの値をその内容によって以下のように表記します。
文字列で表現されているものをJSON文字列
数値で表現されているものをJSON数値
真偽値で表現されているものをJSON真偽値
null値で表現されているものをJSON null値
また、JSONデータの値は上記の表現に加え、以下の表現も可能です。
JSONオブジェクト
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]}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.util.Map<String,?>クラス
java.util.List<?>クラス
上記のクラスの内部要素(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配列)」を参照してください。
シリアライズに利用可能なJava型とJSONデータの対応規則を以下の３つの表にて説明します。
表中の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 シリアライズ規則(その他メンバ)」で記載するものが使用可能です。
Java型 | JSONデータ | シリアライズ規則（Java型→JSONデータ） |
|---|---|---|
Java Bean(任意のクラス) | JSONオブジェクト | ・publicフィールド→JSONメンバー ・JSONオブジェクト内のJSONメンバーは順不同にてシリアライズを行います。 |
JSON null値 | ・null→JSON null値 | |
java.util.Map<String, ?> （型引数に指定できるものは、プリミティブ型を除く本書で説明するJava型のみとなります） | JSONオブジェクト | ・マップ→JSONオブジェクト ・空マップ→空のJSONオブジェクト |
JSON null値 | ・null→JSON null値 |
Java型 | JSONデータ | シリアライズ規則（Java型→JSONデータ） |
|---|---|---|
java.util.List<?> （型引数に指定できるものは、プリミティブ型を除く本書で説明するJava型のみとなります） | JSON配列 | ・配列→JSON配列 ・空リスト→空のJSON配列 |
JSON null値 | ・null→JSON null値 |
Java型 | JSONデータ | シリアライズ規則（Java型→JSONデータ） |
|---|---|---|
boolean | JSON真偽値 | ・true→true |
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 |
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)→\" |
JSON null値 | ・null→JSON null値 |
JSONデータのデシリアライズを行うには、対応するJava型を用意する必要があります。その対応規則を以下の６つの表にて説明します。
表中の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値)」を参照してください。
JSONデータ | Java型 | デシリアライズ規則（JSONデータ→Java型） |
|---|---|---|
JSONオブジェクト | Java Bean (任意のクラス) | ・JSONメンバー→publicフィールドまたはプロパティ ※JSONメンバーの名前と、publicフィールドまたはプロパティの名前が一致している必要があります。 ・JSONメンバーの名前に一致するpublicフィールドとプロパティのいずれもが存在しない場合、JsonMappingExceptionが発生します。 |
java.util.Map<String, ?> （総称型でサポートする型引数はプリミティブ型を除く本書で説明するJava型のみとなります） | ・空のJSONオブジェクト→空マップ ・JSONオブジェクト→マップ |
JSONデータ | Java型 | デシリアライズ規則（JSONデータ→Java型） |
|---|---|---|
JSON配列 | java.util.List<?> （総称型でサポートする型引数はプリミティブ型を除く本書で説明するJava型のみとなります） | ・JSON配列→リスト ・空のJSON配列→空リスト |
JSONデータ | Java型 | デシリアライズ規則（JSONデータ→Java型） |
|---|---|---|
JSON文字列 | java.lang.String | ・JSON文字列が文字列になりますが、エスケープ(\;%x5C)された文字は以下に示すとおりとなります。 ・\f→form feed(%x66) ・\n→line feed(%x6E) |
JSONデータ | Java型 | デシリアライズ規則（JSONデータ→Java型） |
|---|---|---|
JSON数値 | boolean | ・0→false |
byte | 以下の範囲でデシリアライズが行われます。 ・Byte.MIN_VALUE～Byte.MAX_VALUE | |
char | 以下の範囲でデシリアライズが行われます。 ・0～65535は対応するUNICODE文字になります。 | |
double | 以下の範囲でデシリアライズが行われます。 ・Double.MIN_VALUE～Double.MAX_VALUE | |
float | 以下の範囲でデシリアライズが行われます。 ・Float.MIN_VALUE～Float.MAX_VALUE | |
int | 以下の範囲でデシリアライズが行われます。 ・Integer.MIN_VALUE～Integer.MAX_VALUE | |
long | 以下の範囲でデシリアライズが行われます。 ・Long.MIN_VALUE～Long.MAX_VALUE | |
short | 以下の範囲でデシリアライズが行われます。 ・Short.MIN_VALUE～Short.MAX_VALUE | |
java.lang.Boolean | ・0→false | |
java.lang.Byte | 以下の範囲でデシリアライズが行われます。 ・Byte.MIN_VALUE～Byte.MAX_VALUE | |
java.lang.Character | 以下の範囲でデシリアライズが行われます。 ・0～65535は対応するUNICODE文字になります。 | |
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 | |
java.lang.Long | 以下の範囲でデシリアライズが行われます。 ・Long.MIN_VALUE～Long.MAX_VALUE | |
java.lang.Short | 以下の範囲でデシリアライズが行われます。 ・Short.MIN_VALUE～Short.MAX_VALUE | |
java.lang.String | ・JSON数値→文字列 |
JSONデータ | Java型 | デシリアライズ規則（JSONデータ→Java型） |
|---|---|---|
JSON真偽値 | boolean | ・true→true |
java.lang.Boolean | ・true→true | |
java.lang.String | ・JSON真偽値→文字列 |
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 |
本機能を提供するライブラリは以下のとおりです。
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
本機能のデシリアライズは、UTF-8でエンコーディングされたJSONデータを対象に行われます。したがって、クライアント側から送出するJSONデータはUTF-8とする必要があります。
また、シリアライズはJSONデータをUTF-8でエンコードします。
JAX-RSアプリケーションにてシリアライズ／デシリアライズを行うコーディング例を記載します。
Java BeanとJSONオブジェクトを変換する例
java.util.Map<String,?>クラスとJSONオブジェクトを変換する例
上記a,bについてのコーディング例を以下に記載を示します。
例
a. Java BeanとJSONオブジェクトを変換する例
本コーディング例では、JSONオブジェクトとJava Beanの変換を行う２つのリソースメソッドを定義しています。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
// オブジェクトの内容で更新し、更新後のオブジェクトを返却する処理
}
}ｂ. 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オブジェクトからキーに応じた値を取り出し、その値で更新する処理
}
}