Implementation:Apache Paimon TimeUtils
| Knowledge Sources | |
|---|---|
| Domains | Time Management, Utilities |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
TimeUtils provides utilities for parsing and formatting time intervals as Java Duration objects from human-readable strings.
Description
TimeUtils is a utility class offering comprehensive support for parsing duration strings in various formats and units. The primary method parseDuration() accepts strings in format "{length value}{time unit label}" such as "123ms", "5 minutes", or "2h", supporting seven time units: days (d, day), hours (h, hour), minutes (m, min, minute), seconds (s, sec, second), milliseconds (ms, milli, millisecond), microseconds (µs, micro, microsecond), and nanoseconds (ns, nano, nanosecond). If no unit is specified, milliseconds are assumed as the default.
The parser is case-insensitive and accepts both singular and plural forms of unit labels, supporting abbreviations and full names. It performs strict validation including numeric overflow detection (values must fit in a long) and unknown unit rejection with helpful error messages listing all recognized units. An alternative overload parseDuration(long number, String unitLabel) allows programmatic construction from separated numeric and unit values.
TimeUtils also provides formatting utilities: getStringInMillis() converts Duration to millisecond strings, and formatWithHighestUnit() produces human-readable output using the lowest granularity unit that doesn't lose precision (e.g., "60000ms" becomes "1 min", while "3601s" stays as seconds to preserve precision). The implementation uses Java 8's java.time.Duration and ChronoUnit for accurate temporal arithmetic, avoiding legacy java.util.Date pitfalls. An internal TimeUnit enum manages the mapping between string labels and ChronoUnit values, with utility methods for bidirectional conversion.
Usage
Use TimeUtils for parsing configuration values that specify timeouts, intervals, or durations in human-readable formats, and for formatting durations in logs or user interfaces. It provides consistent duration handling across Paimon's configuration system.
Code Reference
Source Location
- Repository: Apache_Paimon
- File: paimon-api/src/main/java/org/apache/paimon/utils/TimeUtils.java
Signature
public class TimeUtils {
public static Duration parseDuration(String text)
public static Duration parseDuration(long number, String unitLabel)
public static String getStringInMillis(final Duration duration)
public static String formatWithHighestUnit(Duration duration)
}
Import
import org.apache.paimon.utils.TimeUtils;
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| text | String | For string parsing | Duration string like "5s", "100ms", "2 hours" |
| number | long | For programmatic | Numeric duration value |
| unitLabel | String | For programmatic | Time unit label |
| duration | Duration | For formatting | Java Duration object to format |
Outputs
| Name | Type | Description |
|---|---|---|
| Duration | Duration | Parsed Java Duration object |
| Formatted string | String | Human-readable duration string |
Usage Examples
// Parse duration strings
Duration fiveSeconds = TimeUtils.parseDuration("5s");
Duration twoMinutes = TimeUtils.parseDuration("2 minutes");
Duration hundredMillis = TimeUtils.parseDuration("100ms");
Duration oneHour = TimeUtils.parseDuration("1h");
Duration threeHundredMs = TimeUtils.parseDuration("300"); // defaults to ms
// Case-insensitive parsing
Duration d1 = TimeUtils.parseDuration("5S");
Duration d2 = TimeUtils.parseDuration("5 SECONDS");
Duration d3 = TimeUtils.parseDuration("5 Second"); // all equivalent
// All supported units
Duration days = TimeUtils.parseDuration("7d");
Duration hours = TimeUtils.parseDuration("24 hours");
Duration minutes = TimeUtils.parseDuration("30min");
Duration seconds = TimeUtils.parseDuration("45sec");
Duration millis = TimeUtils.parseDuration("1000ms");
Duration micros = TimeUtils.parseDuration("500µs");
Duration nanos = TimeUtils.parseDuration("100ns");
// Programmatic duration creation
Duration timeout = TimeUtils.parseDuration(30, "seconds");
Duration interval = TimeUtils.parseDuration(5, "minutes");
// Format as milliseconds string
Duration dur = Duration.ofSeconds(5);
String millis = TimeUtils.getStringInMillis(dur); // "5000ms"
// Format with highest appropriate unit
Duration oneMin = Duration.ofMillis(60000);
String formatted1 = TimeUtils.formatWithHighestUnit(oneMin); // "1 min"
Duration complex = Duration.ofHours(1).plusSeconds(1);
String formatted2 = TimeUtils.formatWithHighestUnit(complex); // "3601 s"
// Uses seconds to preserve precision
Duration twoHours = Duration.ofHours(2);
String formatted3 = TimeUtils.formatWithHighestUnit(twoHours); // "2 h"
// Configuration usage example
public class Config {
private Duration timeout;
public void setTimeout(String timeoutString) {
this.timeout = TimeUtils.parseDuration(timeoutString);
}
public long getTimeoutMillis() {
return timeout.toMillis();
}
}
Config config = new Config();
config.setTimeout("30s");
long millis = config.getTimeoutMillis(); // 30000
// Validation and error handling
try {
Duration invalid = TimeUtils.parseDuration("abc");
} catch (NumberFormatException e) {
System.err.println("Invalid number format");
}
try {
Duration unknown = TimeUtils.parseDuration("5xyz");
} catch (IllegalArgumentException e) {
System.err.println("Unknown time unit: " + e.getMessage());
// Error message includes list of valid units
}
// Large values
Duration largeDuration = TimeUtils.parseDuration("999999999999999999");
// Throws IllegalArgumentException if overflow
// Usage in timeouts
Duration connectTimeout = TimeUtils.parseDuration("10s");
Duration readTimeout = TimeUtils.parseDuration("30s");
client.setConnectTimeout(connectTimeout.toMillis());
client.setReadTimeout(readTimeout.toMillis());
// Usage in scheduling
Duration interval = TimeUtils.parseDuration("5 minutes");
scheduler.scheduleAtFixedRate(
task,
0,
interval.toMillis(),
TimeUnit.MILLISECONDS
);
// Pretty printing for logs
Duration elapsed = calculateElapsedTime();
String readable = TimeUtils.formatWithHighestUnit(elapsed);
System.out.println("Operation completed in " + readable);