Package org.apache.juneau.marshall.utils

Class Iso8601Utils

java.lang.Object

org.apache.juneau.marshall.utils.Iso8601Utils

public final class Iso8601Utils
extends Object

Centralized ISO 8601 formatting and parsing utility for date/time and Duration types.

Provides the built-in serialization format for Temporal, Calendar, Date, XMLGregorianCalendar, and Duration objects.

See Also:

• Marshalling

Method Summary

Modifier and Type	Method	Description
static String	format(Object value, ClassMeta<?> type, TimeZone timeZone)	Formats a date/time or Duration value to its ISO 8601 string representation.
static String	formatAsDate(Object value, ClassMeta<?> type, TimeZone timeZone)	Formats a date/time value as an ISO date (date-only, for OpenAPI 'date' format).
static String	formatAsDateTime(Object value, ClassMeta<?> type, TimeZone timeZone)	Formats a date/time value as an ISO date-time (for OpenAPI 'date-time' format).
static String	formatCalendar(Object value, ClassMeta<?> sourceType, CalendarFormat format, TimeZone timeZone)	Formats a Calendar or XMLGregorianCalendar value using the supplied wire format.
static String	formatDate(Date value, ClassMeta<?> sourceType, DateFormat format, TimeZone timeZone)	Formats a Date value using the supplied wire format.
static String	formatDuration(Duration value, DurationFormat format)	Formats a Duration value using the supplied wire format.
static String	formatPeriod(Period value, PeriodFormat format)	Formats a Period value using the supplied wire format.
static String	formatTemporal(TemporalAccessor value, ClassMeta<?> sourceType, TemporalFormat format, TimeZone timeZone)	Formats a TemporalAccessor value using the supplied wire format.
static <T> T	fromEpochMillis(long epochMillis, ClassMeta<T> targetType, TimeZone timeZone)	Converts epoch milliseconds to the target date/time type.
static <T> T	parse(String iso8601, ClassMeta<T> targetType, TimeZone timeZone)	Parses an ISO 8601 string into the specified date/time target type.
static <T> T	parseCalendar(String iso8601, ClassMeta<T> targetType, CalendarFormat formatHint, TimeZone timeZone)	Parses an ISO 8601 wire value into a Calendar or XMLGregorianCalendar.
static <T> T	parseDate(String iso8601, ClassMeta<T> targetType, DateFormat formatHint, TimeZone timeZone)	Parses an ISO 8601 wire value into a Date.
static Duration	parseDuration(String iso8601, DurationFormat formatHint)	Parses an ISO 8601 / numeric wire value into a Duration.
static Period	parsePeriod(String value, PeriodFormat formatHint)	Parses an ISO 8601 / numeric wire value into a Period.
static <T> T	parseTemporal(String iso8601, ClassMeta<T> targetType, TemporalFormat formatHint, TimeZone timeZone)	Parses an ISO 8601 wire value into the specified Temporal subtype.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

format

public static String format(Object value,
 ClassMeta<?> type,
 TimeZone timeZone)

Formats a date/time or Duration value to its ISO 8601 string representation.

Convenience dispatcher that uses default per-type wire formats; callers that need format-aware output should use the per-type helpers directly: formatDate(java.util.Date, org.apache.juneau.marshall.ClassMeta<?>, org.apache.juneau.marshall.DateFormat, java.util.TimeZone), formatCalendar(java.lang.Object, org.apache.juneau.marshall.ClassMeta<?>, org.apache.juneau.marshall.CalendarFormat, java.util.TimeZone), formatTemporal(java.time.temporal.TemporalAccessor, org.apache.juneau.marshall.ClassMeta<?>, org.apache.juneau.marshall.TemporalFormat, java.util.TimeZone), formatDuration(java.time.Duration, org.apache.juneau.marshall.DurationFormat), formatPeriod(java.time.Period, org.apache.juneau.marshall.PeriodFormat).

Parameters:

value - The value to format. null returns null (consistent with the per-type helpers).

type - The class metadata for the value (used for selecting the appropriate formatter for Temporal types).

timeZone - The session time zone (used when the value lacks zone info).

Returns:

The ISO 8601 string representation, or null if value is null.

formatDuration

public static String formatDuration(Duration value,
 DurationFormat format)

Formats a Duration value using the supplied wire format.

Parameters:

value - The value to format. null returns null.

format - The duration wire format. May be null (defaults to DurationFormat.ISO_8601_WITH_DAYS).

Returns:

The formatted value, or null if value is null.

formatPeriod

public static String formatPeriod(Period value,
 PeriodFormat format)

Formats a Period value using the supplied wire format.

Parameters:

value - The value to format. null returns null.

format - The period wire format. May be null (defaults to PeriodFormat.ISO_8601).

Returns:

The formatted value, or null if value is null.

formatDate

public static String formatDate(Date value,
 ClassMeta<?> sourceType,
 DateFormat format,
 TimeZone timeZone)

Formats a Date value using the supplied wire format.

java.sql.Date, java.sql.Time, and java.sql.Timestamp subclasses all dispatch through DateFormat.format(Date, ZoneId) just like Date.

Parameters:

value - The value to format. null returns null.

sourceType - The class metadata for the value (currently unused, kept for symmetry with the parse helper).

format - The date wire format. May be null (defaults to DateFormat.ISO_LOCAL_DATE_TIME).

timeZone - The session time zone (used as the default zone).

Returns:

The formatted value, or null if value is null.

formatCalendar

public static String formatCalendar(Object value,
 ClassMeta<?> sourceType,
 CalendarFormat format,
 TimeZone timeZone)

Formats a Calendar or XMLGregorianCalendar value using the supplied wire format.

XMLGregorianCalendar values always emit XMLGregorianCalendar.toXMLFormat() regardless of the configured format — mirroring the parse-side rule and the historical wire output. Calendar (including GregorianCalendar) values are formatted using the supplied CalendarFormat.

Parameters:

value - The value to format. Must be a Calendar or XMLGregorianCalendar. null returns null.

sourceType - The class metadata for the value (currently unused, kept for symmetry with the parse helper).

format - The calendar wire format. May be null (defaults to CalendarFormat.ISO_OFFSET_DATE_TIME).

timeZone - The session time zone (used as the default zone when the value lacks zone info).

Returns:

The formatted value, or null if value is null.

formatTemporal

public static String formatTemporal(TemporalAccessor value,
 ClassMeta<?> sourceType,
 TemporalFormat format,
 TimeZone timeZone)

Formats a TemporalAccessor value using the supplied wire format.

Parameters:

value - The value to format. Must be a Temporal subtype. null returns null.

sourceType - The class metadata for the value (currently unused, kept for symmetry with the parse helper).

format - The temporal wire format. May be null (defaults to TemporalFormat.DEFAULT).

timeZone - The session time zone (used as the default zone when the value lacks zone info).

Returns:

The formatted value, or null if value is null.

formatAsDate

public static String formatAsDate(Object value,
 ClassMeta<?> type,
 TimeZone timeZone)

Formats a date/time value as an ISO date (date-only, for OpenAPI 'date' format).

Parameters:

value - The value to format. null returns null.

type - The class metadata.

timeZone - The session time zone.

Returns:

The ISO date string, or null if value is null.

formatAsDateTime

public static String formatAsDateTime(Object value,
 ClassMeta<?> type,
 TimeZone timeZone)

Formats a date/time value as an ISO date-time (for OpenAPI 'date-time' format).

Parameters:

value - The value to format. null returns null.

type - The class metadata.

timeZone - The session time zone.

Returns:

The ISO date-time string, or null if value is null.

parse

public static <T> T parse(String iso8601,
 ClassMeta<T> targetType,
 TimeZone timeZone)

Parses an ISO 8601 string into the specified date/time target type.

Dispatches to the appropriate per-type parser based on the target's ClassMeta category: parseDate, parseCalendar, parseTemporal, parseDuration, or parsePeriod — each using its default wire format.

Type Parameters:

T - The target type.

Parameters:

iso8601 - The ISO 8601 string to parse. null returns null.

targetType - The target class metadata.

timeZone - The session time zone (used for types that need a default zone).

Returns:

The parsed object, or null if iso8601 is null or the target type is not a recognized date/time/duration/period type.

parseDuration

public static Duration parseDuration(String iso8601,
 DurationFormat formatHint)

Parses an ISO 8601 / numeric wire value into a Duration.

Handles ISO 8601 forms ("PT1H", "-PT30M", "PT-6H", "PT1.5S", …) as well as the bare-number wire forms produced by DurationFormat.MILLIS, DurationFormat.SECONDS, DurationFormat.NANOS, and DurationFormat.HOCON (e.g. "500ms", "1.5s").

The formatHint disambiguates bare integer strings that could be milliseconds, nanos, or seconds — for all other numeric or ISO forms the input is self-describing and the hint is ignored.

Parameters:

iso8601 - The wire value to parse. null or empty returns null.

formatHint - The duration wire format used to disambiguate bare integer inputs. May be null (defaults to DurationFormat.MILLIS).

Returns:

The parsed Duration, or null if iso8601 is null or empty.

parsePeriod

public static Period parsePeriod(String value,
 PeriodFormat formatHint)

Parses an ISO 8601 / numeric wire value into a Period.

Handles standard ISO 8601 period strings ("P1Y2M3D", …) as well as the bare-integer wire form produced by PeriodFormat.DAYS.

Parameters:

value - The wire value to parse. null or empty returns null.

formatHint - The period wire format used to interpret bare integers. May be null (defaults to PeriodFormat.DAYS).

Returns:

The parsed Period, or null if value is null or empty.

parseCalendar

public static <T> T parseCalendar(String iso8601,
 ClassMeta<T> targetType,
 CalendarFormat formatHint,
 TimeZone timeZone)

Parses an ISO 8601 wire value into a Calendar or XMLGregorianCalendar.

Dispatches by target type:

• XMLGregorianCalendar targets always use DatatypeFactory.newXMLGregorianCalendar(String) and ignore formatHint.
• Calendar / GregorianCalendar targets honor formatHint when set to anything other than CalendarFormat.NOT_SET or CalendarFormat.ISO_OFFSET_DATE_TIME; the default path uses content-based formatter autodetection.

Type Parameters:

T - The target type.

Parameters:

iso8601 - The wire value to parse. null returns null.

targetType - The target class metadata. Must represent a Calendar or XMLGregorianCalendar.

formatHint - The calendar wire format. May be null (treated as CalendarFormat.NOT_SET).

timeZone - The session time zone (used as the default zone when the wire value lacks zone info).

Returns:

The parsed value, or null if iso8601 is null or the target is not a recognized calendar type.

parseDate

public static <T> T parseDate(String iso8601,
 ClassMeta<T> targetType,
 DateFormat formatHint,
 TimeZone timeZone)

Parses an ISO 8601 wire value into a Date.

Honors formatHint when set to anything other than DateFormat.NOT_SET or DateFormat.ISO_LOCAL_DATE_TIME; the default path uses content-based formatter autodetection.

Only direct Date targets are produced — java.sql.* subclasses fall through to null, matching the original dispatch.

Type Parameters:

T - The target type.

Parameters:

iso8601 - The wire value to parse. null returns null.

targetType - The target class metadata. Must represent Date.

formatHint - The date wire format. May be null (treated as DateFormat.NOT_SET).

timeZone - The session time zone (used as the default zone when the wire value lacks zone info).

Returns:

The parsed Date, or null if iso8601 is null or the target is not exactly Date.

parseTemporal

public static <T> T parseTemporal(String iso8601,
 ClassMeta<T> targetType,
 TemporalFormat formatHint,
 TimeZone timeZone)

Parses an ISO 8601 wire value into the specified Temporal subtype.

Honors formatHint when set to anything other than TemporalFormat.NOT_SET or TemporalFormat.DEFAULT; the default path uses the per-subtype default formatter (e.g. DateTimeFormatter.ISO_INSTANT for Instant, DateTimeFormatter.ISO_LOCAL_DATE for LocalDate, …).

Type Parameters:

T - The target temporal subtype.

Parameters:

iso8601 - The wire value to parse. null returns null.

targetType - The target class metadata. Must represent a Temporal subtype.

formatHint - The temporal wire format. May be null (treated as TemporalFormat.NOT_SET).

timeZone - The session time zone (used as the default zone when the wire value lacks zone info).

Returns:

The parsed value, or null if iso8601 is null or the target is not a Temporal subtype.

fromEpochMillis

public static <T> T fromEpochMillis(long epochMillis,
 ClassMeta<T> targetType,
 TimeZone timeZone)

Converts epoch milliseconds to the target date/time type.

Type Parameters:

T - The target type.

Parameters:

epochMillis - The epoch milliseconds value.

targetType - The target class metadata.

timeZone - The session time zone.

Returns:

The converted date/time object, or null if the target type is not a recognized date/time type.