Module org.tquadrat.foundation.util

Package org.tquadrat.foundation.util

Class DateTimeUtils

java.lang.Object

org.tquadrat.foundation.util.DateTimeUtils

@UtilityClass
@ClassVersion(sourceVersion="$Id: DateTimeUtils.java 1091 2024-01-25 23:10:08Z tquadrat $")
@API(status=STABLE,
     since="0.3.0")
public final class DateTimeUtils
extends Object

Additional helpers for the work with date/time values.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: DateTimeUtils.java 1091 2024-01-25 23:10:08Z tquadrat $

Since:

0.3.0

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.util.DateTimeUtils"

⁠

Field Summary

Fields

Modifier and Type	Field	Description
private static final SoftLazy<Map<String,String>>	m_ZoneIdAliasMap	The alias map.
private static final Map<String,ZoneId>	m_ZoneIdCache	The cached zone ids.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	DateTimeUtils()	No instance allowed for this class!

Method Summary

Modifier and Type	Method	Description
static final Map<String,String>	createZoneIdAliasMap()	Creates the alias map for the old (deprecated) zone ids that are used for the call to ZoneId.of(String, java.util.Map) to retrieve a ZoneId instance for the given zone id.
static final Map<String,String>	getZoneIdAliasMap()	Returns the alias map for the zone id, holding the deprecated ids.
static final ZoneId	replaceByCachedZoneId(ZoneId zoneId)	Replaces the given instance of ZoneId by one from the cache.
static final ZoneId	retrieveCachedZoneId(String id)	Retrieves a cached instance of ZoneId.
static final ZoneId	retrieveCachedZoneId(String prefix, ZoneOffset offset)	Retrieves a cached instance of ZoneId for the given offset.
static final ZoneId	retrieveCachedZoneId(String id, Map<String,String> aliases)	Retrieves a cached instance of ZoneId using a map of aliases.
static final ZoneId	retrieveCachedZoneId(TemporalAccessor temporal)	Retrieves a cached instance of ZoneId from the given temporal.

Methods inherited from class java.lang.Object

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

Field Details

m_ZoneIdAliasMap

@API(status=INTERNAL,
     since="0.4.0")
private static final SoftLazy<Map<String,String>> m_ZoneIdAliasMap

The alias map.

Since:

0.3.0

See Also:

• createZoneIdAliasMap()

m_ZoneIdCache

private static final Map<String,ZoneId> m_ZoneIdCache

The cached zone ids.

Constructor Details

DateTimeUtils

private DateTimeUtils()

No instance allowed for this class!

Method Details

createZoneIdAliasMap

@API(status=STABLE,
     since="0.4.0")
public static final Map<String,String> createZoneIdAliasMap()

Creates the alias map for the old (deprecated) zone ids that are used for the call to ZoneId.of(String, java.util.Map) to retrieve a ZoneId instance for the given zone id.

Returns:

The alias map.

Since:

0.4.0

getZoneIdAliasMap

@API(status=STABLE,
     since="0.4.0")
public static final Map<String,String> getZoneIdAliasMap()

Returns the alias map for the zone id, holding the deprecated ids. If not yet created, the alias map will be created by a call to createZoneIdAliasMap() and the result to that call will be cached for future calls.

Returns:

The alias map.

Since:

0.4.0

See Also:

• createZoneIdAliasMap()

replaceByCachedZoneId

public static final ZoneId replaceByCachedZoneId(ZoneId zoneId)

Replaces the given instance of ZoneId by one from the cache.

Parameters:

zoneId - The instance of ZoneId that needs to be replaced.

Returns:

The instance of ZoneId from the cache; this may be the same as the argument in case the zone id was not yet in the cache.

See Also:

• retrieveCachedZoneId(String)

retrieveCachedZoneId

public static final ZoneId retrieveCachedZoneId(String id)
                                         throws DateTimeException,
ZoneRulesException

Retrieves a cached instance of ZoneId.

Usually, each call to ZoneId.of(String) returns a new instance, even if the argument remains the same. This means that it cannot be assumed that

ZoneId.of( "UTC" ) == ZoneId.of( "UTC" )

returns true (although it cannot be excluded either).

If an application uses ZoneIds a lot, this could cause significant memory pressure, so it would make sense to cache them.

This is safe because the instances of ZoneId are immutable (the documentation says, they should be treated as ValueBased).

As the number of distinct timezones is limited, there is no housekeeping for the cache itself.

Note:

• The id strings are case-sensitive!

Parameters:

id - The id for the time zone.

Returns:

The instance of ZoneId for the given id.

Throws:

DateTimeException - The given id has an invalid format.

ZoneRulesException - The given id is a region id that cannot be found.

See Also:

• stackoverflow: "Many instances of java.time.ZoneRegion in Java heap"

retrieveCachedZoneId

public static final ZoneId retrieveCachedZoneId(String id,
 Map<String,String> aliases)
                                         throws DateTimeException,
ZoneRulesException

Retrieves a cached instance of ZoneId using a map of aliases.

Parameters:

id - The id for the time zone.

aliases - A map of alias zone ids (typically abbreviations) to real zone ids.

Returns:

The instance of ZoneId for the given id.

Throws:

DateTimeException - The given id has an invalid format.

ZoneRulesException - The given id is a region id that cannot be found.

See Also:

• retrieveCachedZoneId(String)
• ZoneId.of(String,Map)

retrieveCachedZoneId

public static final ZoneId retrieveCachedZoneId(TemporalAccessor temporal)
                                         throws DateTimeException

Retrieves a cached instance of ZoneId from the given temporal.

Parameters:

temporal - The temporal object.

Returns:

The instance of ZoneId for the temporal.

Throws:

DateTimeException - The given temporal cannot be converted to a ZoneId.

See Also:

• retrieveCachedZoneId(String)
• ZoneId.from(TemporalAccessor)

retrieveCachedZoneId

public static final ZoneId retrieveCachedZoneId(String prefix,
 ZoneOffset offset)
                                         throws IllegalArgumentException

Retrieves a cached instance of ZoneId for the given offset.

Parameters:

prefix - One of "GMT", "UTC", "UT" or the empty string.

offset - The offset.

Returns:

The instance of ZoneId for the arguments.

Throws:

IllegalArgumentException - The prefix is not one of "GMT", "UTC", "UT" or the empty string.

See Also:

• retrieveCachedZoneId(String)
• ZoneId.ofOffset(String, ZoneOffset)