Java標準に最も近い？org.jsonライブラリ徹底解説 – 基本から応用まで

org.json、またはJSON-Javaとしても知られるこのライブラリは、JSONの生みの親であるDouglas Crockford氏によって作成された、JavaでJSONデータを扱うためのリファレンス実装です。 その出自から、JavaにおけるJSON実装の元祖とも言える存在です。

主な役割は、JSONテキストとJavaオブジェクト（JSONObject, JSONArray）との間の変換です。 これにより、Javaアプリケーション内でJSONデータを直感的に生成、解析、操作することが可能になります。

他のライブラリとの比較

Javaの世界には、org.json以外にも有名なJSONライブラリが存在します。代表的なものにJacksonやGsonがあります。

org.jsonは、高機能さやパフォーマンスの面ではJacksonに及ばない場合がありますが、そのシンプルさと手軽さから、基本的なJSON操作を素早く実装したい場合に非常に有効な選択肢となります。

ライセンスに関する注意点

org.jsonライブラリは「The JSON License」という独自のライセンスを採用しています。 このライセンスには「The Software shall be used for Good, not Evil.（本ソフトウェアは善のために利用されなければならず、悪のために利用してはならない）」という一文が含まれています。 この条項の解釈は曖昧であり、一部ではオープンソースの定義に合致しないという議論もあります。 商用利用や嚴密なライセンス管理が求められるプロジェクトで利用する際には、この点を十分に認識しておく必要があります。

org.jsonライブラリを利用するためには、まずプロジェクトにライブラリを追加する必要があります。ここでは、代表的なビルドツールであるMavenとGradleを使った導入方法を解説します。

Mavenを使用する場合

Mavenプロジェクトでは、pom.xmlファイルに以下の依存関係を追加します。バージョンはMaven Centralなどで最新のものを確認して指定することをお勧めします。

<!-- pom.xml -->
<dependencies> <dependency> <groupId>org.json</groupId> <artifactId>json</artifactId> <version>20240303</version> <!-- 執筆時点での最新バージョンの一つ --> </dependency>
</dependencies>

Gradleを使用する場合

Gradleプロジェクトでは、build.gradleファイルに以下の依存関係を記述します。

// build.gradle
dependencies { implementation 'org.json:json:20240303' // 執筆時点での最新バージョンの一つ
}

JSONObjectは、JSONオブジェクト（{ "key": "value" } の形式）を表現する中心的なクラスです。 これはJavaのMapに似たキーと値のペアのコレクションで、キーはユニークな文字列である必要があります。

JSONObjectの生成と値の追加 (put)

JSONObjectのインスタンスを生成し、put()メソッドを使ってキーと値を追加します。値には文字列、数値、真偽値、null、さらには別のJSONObjectやJSONArrayも指定できます。

import org.json.JSONObject;
public class JsonObjectExample { public static void main(String[] args) { // 空のJSONObjectを生成 JSONObject user = new JSONObject(); // putメソッドでキーと値を追加 user.put("name", "Taro Yamada"); user.put("age", 30); user.put("isMarried", true); user.put("email", JSONObject.NULL); // null値を表現 // ネストしたJSONObjectを追加 JSONObject address = new JSONObject(); address.put("prefecture", "Tokyo"); address.put("city", "Shinjuku"); user.put("address", address); // JSON文字列として出力 System.out.println(user.toString()); }
}

実行結果:

{"address":{"city":"Shinjuku","prefecture":"Tokyo"},"name":"Taro Yamada","isMarried":true,"age":30,"email":null}

toString()メソッドを使うと、作成したオブジェクトをJSON形式の文字列に変換できます。 整形して出力したい場合は、toString(int indentFactor)メソッドを使用します。

// インデント幅を2に指定して整形出力
System.out.println(user.toString(2));

整形された実行結果:

{ "address": { "city": "Shinjuku", "prefecture": "Tokyo" }, "name": "Taro Yamada", "isMarried": true, "age": 30, "email": null
}

値の取得 (get, opt)

値を取得するには、get()系のメソッドやopt()系のメソッドを使用します。

• get<Type>(): 指定したキーの値を取得します。キーが存在しない場合や型が異なる場合にはJSONExceptionがスローされます。
• opt<Type>(): 指定したキーの値を取得します。キーが存在しない場合は、その型のデフォルト値（文字列なら空文字、数値なら0、真偽値ならfalseなど）を返します。例外が発生しないため、より安全に値を取得できます。

import org.json.JSONObject;
import org.json.JSONException;
public class JsonGetValueExample { public static void main(String[] args) { String jsonString = "{\"name\":\"Taro Yamada\",\"age\":30,\"address\":{\"city\":\"Shinjuku\"}}"; JSONObject user = new JSONObject(jsonString); // --- get系メソッド --- try { String name = user.getString("name"); int age = user.getInt("age"); JSONObject address = user.getJSONObject("address"); String city = address.getString("city"); System.out.println("Name: " + name); System.out.println("Age: " + age); System.out.println("City: " + city); // 存在しないキーにアクセスすると例外が発生 // String email = user.getString("email"); } catch (JSONException e) { System.err.println("JSONの解析中にエラーが発生しました: " + e.getMessage()); } // --- opt系メソッド --- // 存在しないキーでもデフォルト値を返す String email = user.optString("email", "N/A"); // デフォルト値を指定 double height = user.optDouble("height"); // デフォルトはNaN System.out.println("Email: " + email); System.out.println("Height: " + height); }
}

キーの存在確認と値の削除

• has(String key): 指定したキーが存在するかどうかをbooleanで返します。
• isNull(String key): 指定したキーの値がJSONObject.NULLであるかどうかを返します。
• remove(String key): 指定したキーとそれに対応する値を削除します。

JSONObject person = new JSONObject("{\"name\":\"Jiro Tanaka\",\"age\":null}");
// キーの存在確認
if (person.has("name")) { System.out.println("nameキーは存在します。");
}
// null値の確認
if (person.isNull("age")) { System.out.println("ageの値はnullです。");
}
// キーの削除
person.remove("age");
System.out.println("削除後のJSON: " + person.toString());

JSONArrayは、JSON配列（[ "value1", 123, true ] の形式）を表現するクラスです。 これはJavaのListやVectorのように、順序付けられた値のコレクションです。

JSONArrayの生成と値の追加 (put)

JSONArrayのインスタンスを生成し、put()メソッドで値を追加します。値はJSONObjectと同様に様々な型を指定できます。

import org.json.JSONArray;
import org.json.JSONObject;
public class JsonArrayExample { public static void main(String[] args) { // 空のJSONArrayを生成 JSONArray hobbies = new JSONArray(); // putメソッドで値を追加 hobbies.put("Programming"); hobbies.put("Reading"); hobbies.put("Movies"); // JSONObjectも追加可能 JSONObject book = new JSONObject(); book.put("title", "JSON in Java"); book.put("pages", 200); hobbies.put(book); // JSON配列文字列として出力 System.out.println(hobbies.toString(2)); }
}

実行結果:

[ "Programming", "Reading", "Movies", { "pages": 200, "title": "JSON in Java" }
]

値の取得とループ処理

値はインデックスを指定して取得します。get()系やopt()系のメソッドが用意されている点はJSONObjectと同様です。 配列の要素数はlength()メソッドで取得できます。

import org.json.JSONArray;
import org.json.JSONObject;
public class JsonArrayGetExample { public static void main(String[] args) { String jsonString = "[\"Programming\",\"Reading\",{\"title\":\"JSON in Java\",\"pages\":200}]"; JSONArray hobbies = new JSONArray(jsonString); // インデックスで値を取得 String firstHobby = hobbies.getString(0); System.out.println("最初の趣味: " + firstHobby); JSONObject book = hobbies.getJSONObject(2); String title = book.getString("title"); System.out.println("本のタイトル: " + title); System.out.println("--- 趣味一覧 ---"); // forループで全要素にアクセス for (int i = 0; i < hobbies.length(); i++) { // 型が混在している可能性があるため、Objectとして取得 Object value = hobbies.get(i); if (value instanceof String) { System.out.println("String: " + value); } else if (value instanceof JSONObject) { System.out.println("JSONObject: " + ((JSONObject) value).getString("title")); } } }
}

既存のJSON形式の文字列をJavaオブジェクトとして扱いたい場合、つまり「パース」したい場合は、JSONObjectやJSONArrayのコンストラクタにその文字列を渡すのが最も簡単な方法です。

文字列からJSONObjectへのパース

波括弧 {} で囲まれたJSONオブジェクト文字列は、JSONObjectのコンストラクタに渡すことでパースできます。

import org.json.JSONObject;
import org.json.JSONException;
public class ParseObjectExample { public static void main(String[] args) { String jsonStr = "{\"id\":1, \"productName\":\"Laptop\", \"price\":150000, \"available\":true}"; try { JSONObject product = new JSONObject(jsonStr); // 文字列をコンストラクタに渡す System.out.println("商品ID: " + product.getInt("id")); System.out.println("商品名: " + product.getString("productName")); System.out.println("価格: " + product.getInt("price")); } catch (JSONException e) { // JSONの形式が不正な場合に例外がスローされる System.err.println("JSONパースエラー: " + e.getMessage()); } }
}

文字列からJSONArrayへのパース

角括弧 [] で囲まれたJSON配列文字列は、JSONArrayのコンストラクタに渡すことでパースできます。

import org.json.JSONArray;
import org.json.JSONException;
public class ParseArrayExample { public static void main(String[] args) { String jsonStr = "[{\"city\":\"Tokyo\"}, {\"city\":\"Osaka\"}, {\"city\":\"Nagoya\"}]"; try { JSONArray cities = new JSONArray(jsonStr); // 文字列をコンストラクタに渡す System.out.println("都市の数: " + cities.length()); System.out.println("最初の都市: " + cities.getJSONObject(0).getString("city")); } catch (JSONException e) { System.err.println("JSONパースエラー: " + e.getMessage()); } }
}

JSONTokenerを使ったパース

JSONTokenerは、文字列やストリームからJSONのトークンを一つずつ解析するためのクラスです。 JSONObjectやJSONArrayは内部的にこのJSONTokenerを使用しています。通常はコンストラクタに文字列を渡す方法で十分ですが、より低レベルな操作が必要な場合に利用できます。

import org.json.JSONObject;
import org.json.JSONTokener;
public class TokenerExample { public static void main(String[] args) { String jsonStr = "{\"name\": \"Hanako Sato\", \"age\": 25}"; JSONTokener tokener = new JSONTokener(jsonStr); JSONObject person = new JSONObject(tokener); System.out.println(person.getString("name")); }
}

org.jsonは、Javaのオブジェクト（特にJavaBeansパターンのPOJO）をJSONObjectに変換する便利な機能も提供します。

JavaオブジェクトからJSONObjectへ

POJO（Plain Old Java Object）のインスタンスをJSONObjectのコンストラクタに渡すと、そのオブジェクトのpublicなgetterメソッド名からキーを推測し、その戻り値を値とするJSONObjectが生成されます。

変換対象のPOJOクラス:

public class UserBean { private String name; private int age; private boolean isActive; // publicなgetterメソッドが重要 public String getName() { return name; } public void setName(String name) { this.name = name; } public int getAge() { return age; } public void setAge(int age) { this.age = age; } public boolean isActive() { // 真偽値の場合は isXxx() も可 return isActive; } public void setActive(boolean active) { isActive = active; }
}

変換を実行するコード:

import org.json.JSONObject;
public class PojoToJsonExample { public static void main(String[] args) { UserBean userBean = new UserBean(); userBean.setName("Shiro Suzuki"); userBean.setAge(45); userBean.setActive(false); // POJOインスタンスをコンストラクタに渡す JSONObject jsonObject = new JSONObject(userBean); System.out.println(jsonObject.toString(2)); }
}

実行結果:

{ "name": "Shiro Suzuki", "active": false, "age": 45
}

JSONObjectからJSON文字列へ

これは既出ですが、JavaオブジェクトからJSON文字列への変換は、まずオブジェクトをJSONObjectに変換し、そのtoString()メソッドを呼び出すことで実現できます。

安全な値取得のための `opt`系メソッドの活用

前述の通り、opt系のメソッドはキーが存在しない場合に例外をスローせず、デフォルト値を返します。これにより、コードの可読性を上げ、不要なtry-catchブロックを減らすことができます。

// getを使用した場合（例外処理が必要）
String name;
try { name = json.getString("name");
} catch (JSONException e) { name = "Default Name";
}
// optを使用した場合（1行で記述可能）
String name = json.optString("name", "Default Name");

数値の扱いに関する注意点

org.jsonは内部的に数値をNumberクラスとして扱います。get()メソッドで数値を取得すると、その値に応じてInteger, Long, Double, BigDecimalなどの型で返されることがあります。特に大きな数値や小数点以下の桁数が多い数値を扱う場合は、意図しない型変換に注意が必要です。確実な型で取得したい場合は、getInt(), getDouble()などの型指定メソッドや、getBigDecimal()を使用することが推奨されます。

スレッドセーフティ

JSONObjectとJSONArrayはスレッドセーフではありません。 複数のスレッドから同時に同じインスタンスを変更しようとすると、データが破壊されたり、予期せぬ動作を引き起こしたりする可能性があります。マルチスレッド環境で共有インスタンスを扱う場合は、synchronizedブロックを使用するなどして、開発者自身が排他制御を行う必要があります。

パフォーマンスに関する考察

org.jsonは、そのシンプルさから小〜中規模のJSONデータを扱うのには十分なパフォーマンスを発揮します。しかし、非常に大きなJSONファイル（数MB以上）をパースする場合や、ミリ秒単位の処理速度が求められるような高頻度のAPIレスポンス処理などでは、ストリーミングAPIをサポートしているJacksonなどのライブラリの方がメモリ効率や処理速度の面で有利になることがあります。プロジェクトの要件に応じて適切なライブラリを選択することが重要です。

エラーハンドリングの再確認

繰り返しになりますが、外部から受け取ったJSON文字列をパースする際には、それが常に正しい形式であるとは限りません。JSONExceptionを適切にキャッチし、エラーが発生した場合の代替処理（デフォルト値を返す、エラーログを出力する、ユーザーに通知するなど）を明確に実装しておくことは、堅牢なアプリケーションを構築する上で不可欠です。

本記事では、JavaでJSONを扱うための基本的なライブラリであるorg.jsonについて、その概要から環境構築、JSONObjectとJSONArrayの基本的な操作、JSON文字列のパース、Javaオブジェクトとの変換、そして応用的な使い方や注意点に至るまで、幅広く解説しました。

org.jsonは、その軽量さと学習コストの低さから、多くの場面で迅速にJSON処理を実装するための強力なツールとなります。特に、複雑なマッピングや最高のパフォーマンスが要求されない限り、そのシンプルさは大きな利点となるでしょう。

一方で、より高度なデータバインディング機能やパフォーマンス、あるいは厳密なライセンス準拠が求められる場合は、JacksonやGsonといった他の選択肢も視野に入れるべきです。

この記事が、あなたのJavaプロジェクトにおけるJSON処理の一助となれば幸いです。