Package org.apache.juneau.commons.time

Class GranularZonedDateTime

java.lang.Object

org.apache.juneau.commons.time.GranularZonedDateTime

public class GranularZonedDateTime
extends Object

A ZonedDateTime with precision information for granular time operations.

This class combines a ZonedDateTime with a ChronoField precision identifier, allowing for granular time operations such as rolling by specific time units.

The precision field indicates the granularity of the time value, which determines how the roll(int) method behaves. For example, a precision of ChronoField.YEAR means rolling by 1 will advance the year, while a precision of ChronoField.HOUR_OF_DAY means rolling by 1 will advance the hour.

ISO8601 Parsing:

The of(String) method can parse various ISO8601 timestamp formats:

• Date formats: "2011", "2011-01", "2011-01-15"
• DateTime formats: "2011-01-15T12", "2011-01-15T12:30", "2011-01-15T12:30:45"
• With fractional seconds: "2011-01-15T12:30:45.123", "2011-01-15T12:30:45,123"
• Time-only formats: "T12", "T12:30", "T12:30:45"
• With timezone: "2011-01-15T12:30:45Z", "2011-01-15T12:30:45+05:30", "2011-01-15T12:30:45-05:30"

The precision is automatically determined from the input format. For example:

• "2011" → ChronoField.YEAR
• "2011-01" → ChronoField.MONTH_OF_YEAR
• "2011-01-15" → ChronoField.DAY_OF_MONTH
• "2011-01-15T12" → ChronoField.HOUR_OF_DAY
• "2011-01-15T12:30" → ChronoField.MINUTE_OF_HOUR
• "2011-01-15T12:30:45" → ChronoField.SECOND_OF_MINUTE
• "2011-01-15T12:30:45.123" → ChronoField.MILLI_OF_SECOND (1-3 digits)
• "2011-01-15T12:30:45.123456789" → ChronoField.NANO_OF_SECOND (4-9 digits)

Example:

// Parse an ISO8601 timestamp with year precision GranularZonedDateTime gdt = GranularZonedDateTime.of("2011"); // Roll forward by one year gdt = gdt.roll(1); // Get the ZonedDateTime ZonedDateTime zdt = gdt.getZonedDateTime(); // Result: 2012-01-01T00:00:00 with system default timezone

// Parse a datetime with hour precision GranularZonedDateTime gdt2 = GranularZonedDateTime.of("2011-01-15T12Z"); // Roll forward by 2 hours gdt2 = gdt2.roll(ChronoField.HOUR_OF_DAY, 2); // Result: 2011-01-15T14:00:00Z

Thread Safety:

This class is immutable and thread-safe.

See Also:

• ZonedDateTime
• ChronoField
• DateUtils

Field Summary

Fields

Modifier and Type	Field	Description
final ChronoField	precision	The precision of this time value
final ZonedDateTime	zdt	The ZonedDateTime value

Constructor Summary

Constructors

Constructor	Description
GranularZonedDateTime(ZonedDateTime zdt, ChronoField precision)	Constructor.

Method Summary

Modifier and Type	Method	Description
GranularZonedDateTime	copy()	Creates a copy of this object.
ChronoField	getPrecision()	Returns the precision of this time value.
ZonedDateTime	getZonedDateTime()	Returns the ZonedDateTime value.
static GranularZonedDateTime	of(String value)	Parses an ISO8601 timestamp string into a GranularZonedDateTime.
static GranularZonedDateTime	of(String value, ZoneId defaultZoneId, TimeProvider timeProvider)	Parses an ISO8601 timestamp string into a GranularZonedDateTime with a default timezone and custom time provider.
static GranularZonedDateTime	of(String value, TimeProvider timeProvider)	Parses an ISO8601 timestamp string into a GranularZonedDateTime with a custom time provider.
static GranularZonedDateTime	of(ZonedDateTime date, ChronoField precision)	Creates a GranularZonedDateTime from a ZonedDateTime with the specified precision.
static GranularZonedDateTime	of(Date date, ChronoField precision)	Creates a GranularZonedDateTime from a Date with the specified precision.
static GranularZonedDateTime	of(Date date, ChronoField precision, ZoneId zoneId)	Creates a GranularZonedDateTime from a Date with the specified precision and timezone.
GranularZonedDateTime	roll(int amount)	Rolls this time value by the specified amount using the current precision.
GranularZonedDateTime	roll(ChronoField field, int amount)	Rolls this time value by the specified amount using the specified field.
String	toString()

Methods inherited from class java.lang.Object

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

Field Details

zdt

public final ZonedDateTime zdt

The ZonedDateTime value

precision

public final ChronoField precision

The precision of this time value

Constructor Details

GranularZonedDateTime

public GranularZonedDateTime(ZonedDateTime zdt,
 ChronoField precision)

Constructor.

Parameters:

zdt - The ZonedDateTime value.

precision - The precision of this time value.

Method Details

of

public static GranularZonedDateTime of(Date date,
 ChronoField precision)

Creates a GranularZonedDateTime from a Date with the specified precision.

The date is converted to a ZonedDateTime using the system default timezone.

Parameters:

date - The date to convert.

precision - The precision of the time value.

Returns:

A new GranularZonedDateTime instance.

Throws:

IllegalArgumentException - if date or precision is null.

of

public static GranularZonedDateTime of(Date date,
 ChronoField precision,
 ZoneId zoneId)

Creates a GranularZonedDateTime from a Date with the specified precision and timezone.

The date is converted to a ZonedDateTime using the specified timezone.

Parameters:

date - The date to convert.

precision - The precision of the time value.

zoneId - The timezone to use.

Returns:

A new GranularZonedDateTime instance.

Throws:

IllegalArgumentException - if date, precision, or zoneId is null.

of

public static GranularZonedDateTime of(String value)

Parses an ISO8601 timestamp string into a GranularZonedDateTime.

This method parses various ISO8601 formats and automatically determines the precision based on the format. If no timezone is specified in the string, the system default timezone is used.

Supported Formats:

• Date: "2011", "2011-01", "2011-01-15"
• DateTime: "2011-01-15T12", "2011-01-15T12:30", "2011-01-15T12:30:45"
• With fractional seconds: "2011-01-15T12:30:45.123", "2011-01-15T12:30:45,123"
• Time-only: "T12", "T12:30", "T12:30:45" (uses current date)
• With timezone: "2011-01-15T12:30:45Z", "2011-01-15T12:30:45+05:30", "2011-01-15T12:30:45-05:30"

Timezone Handling:

• If the string contains a timezone (Z, +HH:mm, -HH:mm, etc.), that timezone is used.
• If no timezone is specified, the system default timezone is used.
• For time-only formats (starting with "T"), the current date is used with the specified or default timezone.

Precision Detection:

The precision is automatically determined from the format:

• Year only → ChronoField.YEAR
• Year-Month → ChronoField.MONTH_OF_YEAR
• Year-Month-Day → ChronoField.DAY_OF_MONTH
• With hour → ChronoField.HOUR_OF_DAY
• With minute → ChronoField.MINUTE_OF_HOUR
• With second → ChronoField.SECOND_OF_MINUTE
• With 1-3 fractional digits → ChronoField.MILLI_OF_SECOND
• With 4-9 fractional digits → ChronoField.NANO_OF_SECOND

Parameters:

value - The ISO8601 timestamp string to parse.

Returns:

A new GranularZonedDateTime instance.

Throws:

IllegalArgumentException - if timestamp is null.

DateTimeParseException - if the timestamp format is invalid.

of

public static GranularZonedDateTime of(String value,
 TimeProvider timeProvider)

Parses an ISO8601 timestamp string into a GranularZonedDateTime with a custom time provider.

This method is similar to of(String), but allows you to specify a custom TimeProvider to use for obtaining the system default timezone and current time. This is useful for testing or when you need deterministic time behavior.

The time provider is used when:

• No timezone is specified in the string - uses TimeProvider.getSystemDefaultZoneId()
• Time-only formats (starting with "T") - uses TimeProvider.now(ZoneId) to get the current date

Example:

// Parse with custom time provider for testing var timeProvider = new FakeTimeProvider(); GranularZonedDateTime gdt = GranularZonedDateTime.of( "T12:30:45", timeProvider ); // Result uses the time provider's current date and timezone

Parameters:

value - The ISO8601 timestamp string to parse.

timeProvider - The time provider to use for system default timezone and current time. If null, TimeProvider.INSTANCE is used.

Returns:

A new GranularZonedDateTime instance.

Throws:

IllegalArgumentException - if value is null.

DateTimeParseException - if the timestamp format is invalid.

of

public static GranularZonedDateTime of(String value,
 ZoneId defaultZoneId,
 TimeProvider timeProvider)

Parses an ISO8601 timestamp string into a GranularZonedDateTime with a default timezone and custom time provider.

This method is similar to of(String), but allows you to specify both a default timezone and a custom TimeProvider to use when no timezone is present in the timestamp string.

If the timestamp string contains a timezone (Z, +HH:mm, -HH:mm, etc.), that timezone takes precedence over the defaultZoneId parameter. The defaultZoneId is only used when no timezone is specified in the string.

The time provider is used when:

• No timezone is specified and defaultZoneId is null - uses TimeProvider.getSystemDefaultZoneId()
• Time-only formats (starting with "T") - uses TimeProvider.now(ZoneId) to get the current date

Example:

// Parse with default timezone and custom time provider var timeProvider = new FakeTimeProvider(); GranularZonedDateTime gdt1 = GranularZonedDateTime.of( "2011-01-15T12:30:45", ZoneId.of("America/New_York"), timeProvider ); // Result uses America/New_York timezone // Parse with timezone in string (defaultZoneId is ignored) GranularZonedDateTime gdt2 = GranularZonedDateTime.of( "2011-01-15T12:30:45Z", ZoneId.of("America/New_York"), timeProvider ); // Result uses UTC (Z), not America/New_York

Parameters:

value - The ISO8601 timestamp string to parse.

defaultZoneId - The default timezone to use if no timezone is specified in the string. If null, the time provider's system default timezone is used.

timeProvider - The time provider to use for system default timezone and current time. If null, TimeProvider.INSTANCE is used.

Returns:

A new GranularZonedDateTime instance.

Throws:

IllegalArgumentException - if value is null.

DateTimeParseException - if the timestamp format is invalid.

of

public static GranularZonedDateTime of(ZonedDateTime date,
 ChronoField precision)

Creates a GranularZonedDateTime from a ZonedDateTime with the specified precision.

This is the most direct way to create a GranularZonedDateTime when you already have a ZonedDateTime and want to specify its precision.

Parameters:

date - The ZonedDateTime value.

precision - The precision of the time value.

Returns:

A new GranularZonedDateTime instance.

Throws:

IllegalArgumentException - if date or precision is null.

copy

public GranularZonedDateTime copy()

Creates a copy of this object.

Returns:

A new GranularZonedDateTime with the same values.

getZonedDateTime

public ZonedDateTime getZonedDateTime()

Returns the ZonedDateTime value.

Returns:

The ZonedDateTime value.

getPrecision

public ChronoField getPrecision()

Returns the precision of this time value.

The precision indicates the finest granularity of the time value, which determines how the value was parsed or created. For example:

• ChronoField.YEAR - Year precision (e.g., "2011")
• ChronoField.MONTH_OF_YEAR - Month precision (e.g., "2011-01")
• ChronoField.DAY_OF_MONTH - Day precision (e.g., "2011-01-15")
• ChronoField.HOUR_OF_DAY - Hour precision (e.g., "2011-01-15T12")
• ChronoField.MINUTE_OF_HOUR - Minute precision (e.g., "2011-01-15T12:30")
• ChronoField.SECOND_OF_MINUTE - Second precision (e.g., "2011-01-15T12:30:45")
• ChronoField.MILLI_OF_SECOND - Millisecond precision (e.g., "2011-01-15T12:30:45.123")
• ChronoField.NANO_OF_SECOND - Nanosecond precision (e.g., "2011-01-15T12:30:45.123456789")

Returns:

The precision of this time value.

toString

public String toString()

Overrides:

toString in class Object

roll

public GranularZonedDateTime roll(ChronoField field,
 int amount)

Rolls this time value by the specified amount using the specified field.

This method creates a new GranularZonedDateTime by adding the specified amount to the specified field. The precision of the returned object remains the same as this object.

Supported Fields:

• ChronoField.YEAR
• ChronoField.MONTH_OF_YEAR
• ChronoField.DAY_OF_MONTH
• ChronoField.HOUR_OF_DAY
• ChronoField.MINUTE_OF_HOUR
• ChronoField.SECOND_OF_MINUTE
• ChronoField.MILLI_OF_SECOND
• ChronoField.NANO_OF_SECOND

Example:

// Create a datetime with hour precision GranularZonedDateTime gdt = GranularZonedDateTime.of("2011-01-15T12Z"); // Roll forward by 2 hours gdt = gdt.roll(ChronoField.HOUR_OF_DAY, 2); // Result: 2011-01-15T14:00:00Z (precision still HOUR_OF_DAY)

Parameters:

field - The field to roll by. Must be one of the supported fields listed above.

amount - The amount to roll by. Positive values roll forward, negative values roll backward.

Returns:

A new GranularZonedDateTime with the rolled value.

Throws:

IllegalArgumentException - If the field is not supported.

roll

public GranularZonedDateTime roll(int amount)

Rolls this time value by the specified amount using the current precision.

This is a convenience method that calls roll(ChronoField, int) using this object's precision field.

Example:

// Create a datetime with year precision GranularZonedDateTime gdt = GranularZonedDateTime.of("2011"); // Roll forward by 1 (using YEAR precision) gdt = gdt.roll(1); // Result: 2012-01-01T00:00:00 (precision still YEAR)

Parameters:

amount - The amount to roll by. Positive values roll forward, negative values roll backward.

Returns:

A new GranularZonedDateTime with the rolled value.