ユーティリティ#

jimble-util には移送元から持ってきた道具が 約 28,000 行入っています。 ここは地図です。網羅ではなく「よく使うもの」と「引っかかるところ」を並べます。

Data#

io.jimble.util.data.Data は LinkedHashMap<String, Object> の派生です。 リクエストも SELECT の結果も JSON もこれで扱います（リクエストとレスポンス）。

Data data = new Data();
data.putData(SITE_ID, 1L);
data.putData(SITE_NAME, "俺的まとめ");

Data site = data.getData("site");

assertEquals(1L, site.getLong("id"));
assertEquals("俺的まとめ", site.getString("name"));

DB の値は列（Column）で読み書きします。列版はテーブル名のネストを辿ります。

あるのに読めない値は DataConversionException です。"abc"、int に "1.5"、桁あふれ、真偽に "yes"（読めるのは true / false / 1 / 0 だけ）などです。 getEnum も一致しなければ例外で、無くてよいなら getEnumOptional(key, 型) を使います。 利用者の入力を getInt などで読むなら、**先にバリデーションを通してください。**通さずに読んで例外になると 500 です。

• 型を変えて読んでも（数の一覧を getStringList で読むなど）、元の Data には書き戻しません
• 書き換えられない写しが要るときは readOnlyCopy()（書き込むと UnsupportedOperationException）

JSON#

自前実装です（Jackson も Gson も使っていません）。

Data nested = new Data();
nested.put("title", "記事タイトル");

Data data = new Data();
data.put("name", "俺的まとめ");
data.put("count", 3);
data.put("feed", nested);
data.put("tags", List.of("あ", "い"));

String json = data.getJsonString();
Data restored = Data.fromJsonString(json);

assertEquals("俺的まとめ", restored.getString("name"));
assertEquals(3, restored.getInt("count"));
assertEquals("記事タイトル", restored.getData("feed").getString("title"));
assertEquals(List.of("あ", "い"), restored.getStringList("tags"));

壊れた JSON は JsonParseException（非検査）です。Data.fromJsonString も Dson.decodes も、Reader や InputStream から読んでも同じです。 例外には、どこがおかしいか（3 行 15 文字目）が載ります。空文字と "null" は null を返します（例外にしません）。

意味がはっきりしているゆるさは受け付け、データを黙って壊すものは断ります（2.6.0 から。読み手は jimble-json）。

**上限があります。**外から来た JSON を読むので、超えたら例外にします。

型に読む#

Bean・record・それらの List は、木（Data）を作らずに読みながら入れます（2.7.0 から）。

Order order = Dson.decodes(json, Order.class);                     // これまでどおり
List<Item> items = Dson.decodes(json, List.class, Item.class);

Order order = Json.read(json, Order.class);                        // jimble-json
List<Item> items = Json.read(json, new TypeRef<List<Item>>() {});  // 型の引数を持つ型

• record は正準のコンストラクタで作ります。JSON に無いコンポーネントは null（プリミティブは 0 / false）です
• Bean は引数の無いコンストラクタで作り、setter があれば setter で、無ければフィールドに入れます（親クラスの private フィールドにも入れます）
• 知らないキーは読み飛ばします（例外にしません）
• 入れ子・List<Item>・Map<String, Item>・Optional・配列・型変数（TypeRef<Box<Item>>）も、型どおりに読みます

値は項目の型にします。値が変わってしまうものは断ります。

断るときは JsonParseException（Json.read は JsonException）で、どの項目か（$.items[1].qty）と行・文字の位置が載ります。

user_name を userName の項目に入れたいときは、JsonReadOptions.builder().snakeCaseKeys(true) を渡します （Dson では Configration#setDefaultFieldDelimiterChar()）。

書き出し#

日時などの型は、次の形で書きます（2.7.0 から。それまでは Date と LocalDateTime 以外を書くと、JSON が {} になったり途中で切れたりしていました）。

• Bean のキーは宣言した順です（2.7.0 から。それまでは JVM を起動するたびに順番が変わることがありました）
• 循環参照は、2回目を {} / [] と書いて続けます（2.6 までと同じ）
• **入れ子は 512 段まで書きます。**超えたら書かず、Dson.encodes は空文字を返してエラーをログに出します（2.6 までは 50 段を超えたところを、黙って {} / [] にしていました）

時差を残したいとき・循環で例外にしたいとき・型ごとに書き方を変えたいときは、jimble-json の Json.write(value, options) を使います。

JsonWriteOptions options = JsonWriteOptions.builder()
	.keepOffset(true)                 // Date / Instant / OffsetDateTime などを 2026-10-24T19:00:00+09:00 の形で
	.cycle(JsonCycle.THROW)           // 循環参照は例外（どこで循環したかが載る。Json.write の既定）
	.typeWriter(Money.class, (value, out) -> out.string(((Money) value).format()))
	.build();

String json = Json.write(value, options);

型変換#

jimble-converter の Converter.convert(値, 変換先.class) が入口です（2.7.0 から。jimble のほかのモジュールに依存しません）。 Bean ↔ Map ↔ List ↔ record ↔ プリミティブ・日時のあいだを変換します。 Data からは data.convertClass(MyBean.class) や getIntList などの getter で、中身は同じものです。 変換できなければ非検査例外です（throws も catch も要りません）。

Order order = Converter.convert(map, Order.class);
List<Item> items = Converter.convert(rows, new TypeRef<List<Item>>() {});

ConverterOptions options = ConverterOptions.builder()
	.rejectUnknownKeys(true)          // 知らないキーで断る
	.zone(ZoneId.of("Asia/Tokyo"))    // 時差の無い日時を補う時間帯
	.typeConverter(Money.class, value -> Money.parse(value.toString()))  // 型ごとの変換を足す
	.build();
Order strict = Converter.convert(map, Order.class, options);

int qty = Converter.convert("abc", int.class, ConverterOptions.LENIENT);  // 読めない値を 0 / null に（CSV など）

決まりは JSON を型に読む ときと同じです。

• 値が変わってしまうものは例外です（ConversionException。どの項目か $.items[1].qty が載ります）。1.5 → int、桁あふれ、"abc" → int、無い enum の名前、ありえない日付、後ろに余分のある日付
• 意味がはっきりしているゆるさは受け付けます。前後の空白、全角の数字、"1,234"、1.0 → int、true → 1、"yes" / "on" → true（"no" / "off" は false）、"2024年01月15日"・"2024/1/5 9:00"（月・日・時が 1 桁）→ 日付
• Bean には setter があれば setter で入れます（親クラスの private フィールドにも入れます。static / transient には入れません）。record は正準のコンストラクタで作ります
• 知らないキーは飛ばします
• 日時は Date・LocalDate・LocalDateTime・Instant・OffsetDateTime などのあいだで変換します。Z や +09:00 の時差は読みます（時差の無いものはサーバーの時間帯）
• 型が合っている値は、写さずにそのまま返します
• 循環参照は例外です（cycleToNull(true) で、そこを null に）
• 文字から Class / InetAddress / Pattern / File / Path は作りません（外から来た文字で、クラスの読み込み・DNS・ReDoS・ファイルへの到達を起こせるため）。要るなら typeConverter で足します

Convertor から移る#

io.jimble.util.convertor の Convertor / IConvertor / ConvertorConfigKeys / PropertyUtil は 2.7.0 で deprecated です（動きは変わりません。中身は Converter です）。

Convertor には、Converter に無い、これまでのままのゆるさが残っています。Converter に移すときは、次を確かめてください。

• 型が合っている List / Map も写しを返す（Converter はそのまま返す）
• JSON の文字を読む（"[1,2]" → List<Integer>、"{...}" → Data。Converter は JSON を読まないので、Dson.decodes で読んでから渡す）
• Map → 一覧は値の一覧、一覧・Map → 文字は先頭の値（Converter は例外）
• 循環参照はそこを null にする（Converter の既定は例外）

Convertor.addConvertor で足した変換器・Configration に渡した日付の書式（CONVERT_STRING_TO_DATE / CONVERT_DATE_TO_STRING）・XML の Document は、Convertor / Data からは、これまでの変換器で変換します。

HTTP クライアント#

JDK の HttpClient の薄いラッパで、メソッドごとにクラスがあります。

HttpGetExecutor res = new HttpGetExecutor()
	.setUrl("https://example.com/api")
	.addHeader("Accept", "application/json")
	.setTimeout(5000)
	.execute();

if (res.isError) {
	Log.error(res.errorException, "取得に失敗しました");
	return;
}

Data json = res.getContentJson();

• POST は HttpPostExecutor。addBodyForm(name, value) / setBodyJson(data)
• ファイルを1つでも足すと multipart になります（addBodyForm(name, file, contentType)）
• プロキシは setProxy(new HttpProxy(host, port, id, pass))
• 例外を投げません。isError を見てください

• リダイレクトは、https から http へは追いません（2.2.3 から。それまでは追っていました）。追う先のホストは確かめないので、 URL を許可リストで確かめてから取りにいくなら setEnableRedirect(false) にしてください
• メモリに読む本文は、解いたあとの大きさで 50MiB までです（setMaxResponseSize(バイト)）。超えたら本文を読みません

CSV#

try (CsvReader reader = new CsvReader(new File("in.csv"))) {
	while (reader.next()) {
		String name = reader.getString("name");
	}
}

1行ずつ読みます（全部メモリに載せません）。書くほうは CsvWriter#writeLine(Object...)。 CsvReader / CsvWriter は検査例外を投げません。読み書きの失敗は UncheckedIOException です。

BOM（Excel が書き出す UTF-8 の CSV に付くもの）は、文字コードが UTF 系なら読むときに落とします。 BOM があれば、その BOM が示す文字コードで読みます（UTF-8 と指定しても、UTF-16LE の BOM なら UTF-16LE）。 Reader を渡したときは、先頭の BOM を1文字だけ落とします。

書くときに BOM を付けるなら setWithBom(true) です（Excel に UTF-8 の CSV を開かせるとき）。 文字コードが UTF 系のときだけ効き、Shift_JIS などでは何もしません。

= + - @・タブ・CR（全角の ＝＋－＠ も）で始まる値は、先頭に ' を付けて書きます（2.2.3 から）。 Excel はこれらで始まるセルを数式として動かすので、利用者が入れた =HYPERLINK(...) などが、CSV を開いた人の手元で動きました。 数値として読める値（-5 など）には付けません。付けたくなければ setEscapeFormula(false) です。

try (CsvWriter writer = new CsvWriter(new File("out.csv"), "UTF-8").setWithBom(true)) {
	writer.writeLine("名前", "数");
}

XML#

XmlParser.parse(file) で XmlData の木にします（全部メモリに載ります）。 DOCTYPE を含む XML は解析しません（null を返します。外部の実体でファイルを読ませないため）。 組み立ては XmlBuilder.build(xmlData)（検査例外は投げません）。

ハッシュと暗号#

DB に置く key-value#

DBValue.set(db, "last_imported_at", "2026-09-07");
String value = DBValue.getString(db, "last_imported_at", "");

そのほか#