Utilities#

jimble-util holds around 28,000 lines of tools brought over from the code this was ported from. This page is a map. Not an exhaustive list — what you use often, and where you get caught.

Data#

io.jimble.util.data.Data is a subclass of LinkedHashMap<String, Object>. Requests, SELECT results, and JSON are all handled with it (Request and response).

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 values are read and written by column (Column). The column versions follow the table-name nesting.

A value that is there but cannot be read throws DataConversionException. That means "abc", "1.5" as an int, an overflow, "yes" as a boolean (only true / false / 1 / 0 are read), and so on. getEnum also throws when nothing matches; if the value may be absent, use getEnumOptional(key, type). When you read user input with getInt and friends, run it through validation first. Read it unvalidated, hit the exception, and the answer is a 500.

• Reading as a different type (a list of numbers through getStringList, say) does not write back into the Data
• When you want a copy that cannot be changed, use readOnlyCopy() (writing to it throws UnsupportedOperationException)

JSON#

It is our own implementation (neither Jackson nor 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"));

Broken JSON throws JsonParseException (unchecked). Data.fromJsonString and Dson.decodes behave the same, and so does reading from a Reader or an InputStream. The exception says where the problem is (line 3, column 15 — written as 3 行 15 文字目). An empty string and "null" return null (no exception).

Leniency with a clear meaning is accepted; anything that would silently damage the data is refused (since 2.6.0; the reader is jimble-json).

There are limits. The JSON comes from outside, so going over one throws.

Reading into a type#

Beans, records, and Lists of them are filled while reading, without building a tree (Data) (since 2.7.0).

Order order = Dson.decodes(json, Order.class);                     // as before
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>>() {});  // a type with type arguments

• A record is built with its canonical constructor. Components missing from the JSON are null (0 / false for primitives)
• A Bean is built with its no-argument constructor, and each value goes through the setter if there is one, otherwise into the field (private fields of superclasses included)
• Unknown keys are skipped (no exception)
• Nested objects, List<Item>, Map<String, Item>, Optional, arrays, and type variables (TypeRef<Box<Item>>) are read as their types

Values are converted to the property's type. Anything that would change the value is refused.

A refusal throws JsonParseException (JsonException from Json.read) carrying which property ($.items[1].qty) and the line and column.

To put user_name into a userName property, pass JsonReadOptions.builder().snakeCaseKeys(true) (Configration#setDefaultFieldDelimiterChar() for Dson).

Writing#

Date-time and other types are written like this (since 2.7.0; before that, anything other than Date and LocalDateTime turned the JSON into {} or cut it off midway).

• Bean keys come out in declaration order (since 2.7.0; before that, the order could change each time the JVM started)
• A cyclic reference writes {} / [] the second time and carries on (as in 2.6)
• Nesting is written up to 512 levels. Beyond that nothing is written; Dson.encodes returns an empty string and logs an error (up to 2.6, anything past 50 levels silently became {} / [])

To keep offsets, to throw on a cycle, or to change how a type is written, use Json.write(value, options) from jimble-json:

JsonWriteOptions options = JsonWriteOptions.builder()
	.keepOffset(true)                 // Date / Instant / OffsetDateTime and so on as 2026-10-24T19:00:00+09:00
	.cycle(JsonCycle.THROW)           // throw on a cycle, with where it happened (the default for Json.write)
	.typeWriter(Money.class, (value, out) -> out.string(((Money) value).format()))
	.build();

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

Type conversion#

Converter.convert(value, Target.class) from jimble-converter is the way in (since 2.7.0; it depends on no other jimble module). It converts between Beans, Maps, Lists, records, primitives, and date-times. From a Data, use data.convertClass(MyBean.class) or getters such as getIntList; they are the same machinery underneath. When it cannot convert, it throws an unchecked exception (no throws or catch needed).

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

ConverterOptions options = ConverterOptions.builder()
	.rejectUnknownKeys(true)          // refuse unknown keys
	.zone(ZoneId.of("Asia/Tokyo"))    // time zone for date-times without an offset
	.typeConverter(Money.class, value -> Money.parse(value.toString()))  // add a conversion for a type
	.build();
Order strict = Converter.convert(map, Order.class, options);

int qty = Converter.convert("abc", int.class, ConverterOptions.LENIENT);  // unreadable values become 0 / null (for CSV and the like)

The rules are the same as for reading JSON into a type.

• Anything that would change the value throws (ConversionException, carrying which property: $.items[1].qty): 1.5 → int, overflow, "abc" → int, an enum name that does not exist, an impossible date, a date with something extra at the end
• Leniency with a clear meaning is accepted: surrounding blanks, full-width digits, "1,234", 1.0 → int, true → 1, "yes" / "on" → true ("no" / "off" → false), "2024年01月15日" and "2024/1/5 9:00" (one-digit month, day or hour) → a date
• A Bean is filled through its setter when there is one (private fields of superclasses included; never static / transient fields). A record is built with its canonical constructor
• Unknown keys are skipped
• Date-times convert between Date, LocalDate, LocalDateTime, Instant, OffsetDateTime, and so on. Offsets such as Z and +09:00 are honoured (values without one use the server's time zone)
• A value that already has the target type is returned as is, without copying
• A circular reference throws (cycleToNull(true) turns it into null at that point)
• Class / InetAddress / Pattern / File / Path are never built from a string (outside text could trigger class loading, DNS lookups, ReDoS, or file access). Add a typeConverter if you need one

Moving off Convertor#

Convertor / IConvertor / ConvertorConfigKeys / PropertyUtil in io.jimble.util.convertor are deprecated in 2.7.0 (their behaviour is unchanged; underneath they use Converter).

Convertor keeps some of the old leniency that Converter does not have. Check these when you move to Converter:

• A List / Map that already has the target type is still copied (Converter returns it as is)
• JSON text is parsed ("[1,2]" → List<Integer>, "{...}" → Data; Converter does not parse JSON, so read it with Dson.decodes first)
• A Map becomes the list of its values, and a list or Map becomes its first value as a string (Converter throws)
• A circular reference becomes null at that point (Converter throws by default)

Converters added with Convertor.addConvertor, date formats passed in a Configration (CONVERT_STRING_TO_DATE / CONVERT_DATE_TO_STRING), and XML Documents still go through the previous converters when called from Convertor / Data.

HTTP client#

A thin wrapper over the JDK's HttpClient, with a class per method.

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

if (res.isError) {
	Log.error(res.errorException, "could not fetch");
	return;
}

Data json = res.getContentJson();

• POST is HttpPostExecutor. addBodyForm(name, value) / setBodyJson(data)
• Add even one file and it becomes multipart (addBodyForm(name, file, contentType))
• The proxy is setProxy(new HttpProxy(host, port, id, pass))
• It does not throw. Check isError

• Redirects are not followed from https to http (since 2.2.3). The target host is not checked, so if you check URLs against an allow-list before fetching, use setEnableRedirect(false)
• A body read into memory is capped at 50MiB after decompression (setMaxResponseSize(bytes)); above that the body is not read

CSV#

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

It reads a line at a time (it does not put the whole file in memory). For writing, CsvWriter#writeLine(Object...). CsvReader / CsvWriter throw no checked exceptions. A read or write failure is an UncheckedIOException.

A BOM (the one Excel puts on UTF-8 CSV files) is dropped when reading, as long as the encoding is a UTF one. If there is a BOM, the file is read in the encoding the BOM says (ask for UTF-8 and get a UTF-16LE BOM, and it is read as UTF-16LE). Pass a Reader and a single leading BOM character is dropped.

To write a BOM, use setWithBom(true) (for Excel to open a UTF-8 CSV correctly). It only has an effect for UTF encodings; with Shift_JIS and the like it does nothing.

Values starting with = + - @, a tab or CR (and the full-width ＝＋－＠) are written with a leading ' (since 2.2.3). Excel runs such cells as formulas, so a user-supplied =HYPERLINK(...) would run on the machine of whoever opened the CSV. Values that read as numbers (-5 and so on) are left alone. Turn it off with setEscapeFormula(false).

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

XML#

XmlParser.parse(file) turns it into a tree of XmlData (all of it goes in memory). XML with a DOCTYPE is not parsed (it returns null, so external entities cannot read files). To build one, XmlBuilder.build(xmlData) (it throws no checked exception).

Hashing and encryption#

Key-value stored in the DB#

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

The rest#