Package org.apache.juneau.marshall

Enum Class TemporalFormat

java.lang.Object

java.lang.Enum<TemporalFormat>

org.apache.juneau.marshall.TemporalFormat

All Implemented Interfaces:

Serializable, Comparable<TemporalFormat>, Constable

public enum TemporalFormat
extends Enum<TemporalFormat>

Supported wire formats for TemporalAccessor values.

Used by MarshallingContext.Builder.temporalFormat(TemporalFormat), Marshalled.temporalFormat(), MarshalledProp.temporalFormat(), and MarshalledConfig.temporalFormat() to control how TemporalAccessor values (Instant, LocalDate, LocalDateTime, LocalTime, OffsetDateTime, OffsetTime, ZonedDateTime, Year, YearMonth, MonthDay, …) are written to and read from the wire.

The default is DEFAULT which uses the per-subtype default formatter (e.g. DateTimeFormatter.ISO_INSTANT for Instant, DateTimeFormatter.ISO_LOCAL_DATE for LocalDate, etc.) — preserving the historical wire output produced before this enum existed.

Numeric formats (MILLIS) emit native numeric wire types on binary serializers (BSON / CBOR / MsgPack) and bare numbers on text formats. Text formats emit a quoted ISO 8601 string for every other constant.

Most subtypes implement Temporal, but MonthDay only implements TemporalAccessor. Format/parse methods accept any TemporalAccessor so that MonthDay round-trips through the same dispatch path as the Temporal subtypes.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Enum

Enum.EnumDesc<E extends Enum<E>>

Enum Constant Summary

Enum Constants

Enum Constant	Description
BASIC_ISO_DATE	DateTimeFormatter.BASIC_ISO_DATE: "20111203".
DEFAULT	Per-subtype default formatter (the historical wire output).
ISO_DATE	DateTimeFormatter.ISO_DATE: "2011-12-03+01:00" or "2011-12-03".
ISO_DATE_TIME	DateTimeFormatter.ISO_DATE_TIME: "2011-12-03T10:15:30+01:00[Europe/Paris]".
ISO_INSTANT	DateTimeFormatter.ISO_INSTANT: "2011-12-03T10:15:30Z".
ISO_LOCAL_DATE	DateTimeFormatter.ISO_LOCAL_DATE: "2011-12-03".
ISO_LOCAL_DATE_TIME	DateTimeFormatter.ISO_LOCAL_DATE_TIME: "2011-12-03T10:15:30".
ISO_LOCAL_TIME	DateTimeFormatter.ISO_LOCAL_TIME: "10:15:30".
ISO_OFFSET_DATE	DateTimeFormatter.ISO_OFFSET_DATE: "2011-12-03+01:00".
ISO_OFFSET_DATE_TIME	DateTimeFormatter.ISO_OFFSET_DATE_TIME: "2011-12-03T10:15:30+01:00".
ISO_OFFSET_TIME	DateTimeFormatter.ISO_OFFSET_TIME: "10:15:30+01:00".
ISO_ORDINAL_DATE	DateTimeFormatter.ISO_ORDINAL_DATE: "2012-337".
ISO_TIME	DateTimeFormatter.ISO_TIME: "10:15:30+01:00" or "10:15:30".
ISO_WEEK_DATE	DateTimeFormatter.ISO_WEEK_DATE: "2012-W48-6".
ISO_YEAR	Year only — pattern "uuuu": "2012".
ISO_YEAR_MONTH	Year and month — pattern "uuuu-MM": "2012-12".
ISO_ZONED_DATE_TIME	DateTimeFormatter.ISO_ZONED_DATE_TIME: "2011-12-03T10:15:30+01:00[Europe/Paris]".
MILLIS	Epoch milliseconds as a numeric value.
NOT_SET	Sentinel meaning "no value configured" — falls through to the next-higher precedence level.
RFC_1123_DATE_TIME	DateTimeFormatter.RFC_1123_DATE_TIME: "Tue, 3 Jun 2008 11:05:30 GMT".

Method Summary

Modifier and Type	Method	Description
String	format(TemporalAccessor value, ZoneId zoneId)	Formats the specified value using this format.
static boolean	isMillisNumeric(Class<? extends TemporalAccessor> c)	Returns true when MILLIS produces a numeric wire string for the specified subtype.
boolean	isNumeric()	Returns true if this format is numeric on the wire.
<T extends TemporalAccessor> T	parse(String value, Class<T> targetType, ZoneId zoneId)	Parses the specified wire value using this format.
static TemporalFormat	valueOf(String name)	Returns the enum constant of this class with the specified name.
static TemporalFormat[]	values()	Returns an array containing the constants of this enum class, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Details

NOT_SET

public static final TemporalFormat NOT_SET

Sentinel meaning "no value configured" — falls through to the next-higher precedence level.

DEFAULT

public static final TemporalFormat DEFAULT

Per-subtype default formatter (the historical wire output).

Uses the ISO formatter most appropriate for each Temporal subtype: DateTimeFormatter.ISO_INSTANT for Instant, DateTimeFormatter.ISO_LOCAL_DATE for LocalDate, DateTimeFormatter.ISO_OFFSET_DATE_TIME for ZonedDateTime / OffsetDateTime, etc.

BASIC_ISO_DATE

public static final TemporalFormat BASIC_ISO_DATE

DateTimeFormatter.BASIC_ISO_DATE: "20111203".

ISO_DATE

public static final TemporalFormat ISO_DATE

DateTimeFormatter.ISO_DATE: "2011-12-03+01:00" or "2011-12-03".

ISO_DATE_TIME

public static final TemporalFormat ISO_DATE_TIME

DateTimeFormatter.ISO_DATE_TIME: "2011-12-03T10:15:30+01:00[Europe/Paris]".

ISO_INSTANT

public static final TemporalFormat ISO_INSTANT

DateTimeFormatter.ISO_INSTANT: "2011-12-03T10:15:30Z".

ISO_LOCAL_DATE

public static final TemporalFormat ISO_LOCAL_DATE

DateTimeFormatter.ISO_LOCAL_DATE: "2011-12-03".

ISO_LOCAL_DATE_TIME

public static final TemporalFormat ISO_LOCAL_DATE_TIME

DateTimeFormatter.ISO_LOCAL_DATE_TIME: "2011-12-03T10:15:30".

ISO_LOCAL_TIME

public static final TemporalFormat ISO_LOCAL_TIME

DateTimeFormatter.ISO_LOCAL_TIME: "10:15:30".

ISO_OFFSET_DATE

public static final TemporalFormat ISO_OFFSET_DATE

DateTimeFormatter.ISO_OFFSET_DATE: "2011-12-03+01:00".

ISO_OFFSET_DATE_TIME

public static final TemporalFormat ISO_OFFSET_DATE_TIME

DateTimeFormatter.ISO_OFFSET_DATE_TIME: "2011-12-03T10:15:30+01:00".

ISO_OFFSET_TIME

public static final TemporalFormat ISO_OFFSET_TIME

DateTimeFormatter.ISO_OFFSET_TIME: "10:15:30+01:00".

ISO_ORDINAL_DATE

public static final TemporalFormat ISO_ORDINAL_DATE

DateTimeFormatter.ISO_ORDINAL_DATE: "2012-337".

ISO_TIME

public static final TemporalFormat ISO_TIME

DateTimeFormatter.ISO_TIME: "10:15:30+01:00" or "10:15:30".

ISO_WEEK_DATE

public static final TemporalFormat ISO_WEEK_DATE

DateTimeFormatter.ISO_WEEK_DATE: "2012-W48-6".

ISO_YEAR

public static final TemporalFormat ISO_YEAR

Year only — pattern "uuuu": "2012".

ISO_YEAR_MONTH

public static final TemporalFormat ISO_YEAR_MONTH

Year and month — pattern "uuuu-MM": "2012-12".

ISO_ZONED_DATE_TIME

public static final TemporalFormat ISO_ZONED_DATE_TIME

DateTimeFormatter.ISO_ZONED_DATE_TIME: "2011-12-03T10:15:30+01:00[Europe/Paris]".

RFC_1123_DATE_TIME

public static final TemporalFormat RFC_1123_DATE_TIME

DateTimeFormatter.RFC_1123_DATE_TIME: "Tue, 3 Jun 2008 11:05:30 GMT".

MILLIS

public static final TemporalFormat MILLIS

Epoch milliseconds as a numeric value.

Emitted as a native int64 by binary serializers (BSON / CBOR / MsgPack) and as a bare integer literal by text serializers.

Per-subtype semantics (midnight UTC for non-instant subtypes):

• Instant — instant.toEpochMilli().
• OffsetDateTime, ZonedDateTime — value.toInstant().toEpochMilli().
• LocalDateTime — ldt.toInstant(ZoneOffset.UTC).toEpochMilli().
• LocalDate — ld.atStartOfDay(ZoneOffset.UTC).toInstant().toEpochMilli() (midnight UTC).
• YearMonth — first day of the month at midnight UTC.
• Year — January 1 at midnight UTC.
• LocalTime, OffsetTime, MonthDay — fall back to the type's DEFAULT (ISO string form) because no defensible epoch-millis interpretation exists without an associated date/year. See isMillisNumeric(Class) for the canonical decision predicate.

The asymmetry is intentional: a configured MILLIS setting silently produces a string for LocalTime / OffsetTime / MonthDay and a number for every other subtype.

Method Details

values

public static TemporalFormat[] values()

Returns an array containing the constants of this enum class, in the order they are declared.

Returns:

an array containing the constants of this enum class, in the order they are declared

valueOf

public static TemporalFormat valueOf(String name)

Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum class has no constant with the specified name

NullPointerException - if the argument is null

isMillisNumeric

public static boolean isMillisNumeric(Class<? extends TemporalAccessor> c)

Returns true when MILLIS produces a numeric wire string for the specified subtype.

Single source of truth for the MILLIS wire-type decision shared by format(java.time.temporal.TemporalAccessor, java.time.ZoneId) and the marshalling-side temporalSwap / temporalAccessorSwap factories. The helper exists so the swap-side Long.valueOf(s) coercion only fires when format(java.time.temporal.TemporalAccessor, java.time.ZoneId) actually emitted a numeric string — a mismatch on either side is a NumberFormatException waiting to happen.

Returns false for LocalTime, OffsetTime, and MonthDay — these subtypes have no defensible epoch-millis interpretation, so format(java.time.temporal.TemporalAccessor, java.time.ZoneId)'s MILLIS branch falls back to DEFAULT (an ISO string) for them and the swap must keep the value as a string.

Parameters:

c - The TemporalAccessor subtype to query.

Returns:

true if format(java.time.temporal.TemporalAccessor, java.time.ZoneId) emits a Long-parseable numeric string for c under MILLIS; false if the MILLIS branch falls back to ISO string.

format

public String format(TemporalAccessor value,
 ZoneId zoneId)

Formats the specified value using this format.

Parameters:

value - The value to format. Can be null (returns null).

zoneId - The default zone id used for time-only / unzoned values.

Returns:

The formatted string, or null if value is null. For MILLIS this is a numeric string for every subtype except LocalTime, OffsetTime, and MonthDay (which fall back to their DEFAULT ISO string form).

parse

public <T extends TemporalAccessor> T parse(String value,
 Class<T> targetType,
 ZoneId zoneId)

Parses the specified wire value using this format.

Type Parameters:

T - The temporal subtype.

Parameters:

value - The wire value. Can be null or blank (returns null).

targetType - The target temporal subtype. Must be either a Temporal subtype or MonthDay (the only non-Temporal TemporalAccessor the JDK currently exposes).

zoneId - The default zone id used for time-only / unzoned values.

Returns:

The parsed value, or null if value is null or blank.

isNumeric

public boolean isNumeric()

Returns true if this format is numeric on the wire.

Returns:

true if this format emits a numeric wire value.