Package org.hibernate.annotations

Enum TimeZoneStorageType

java.lang.Object

java.lang.Enum<TimeZoneStorageType>

org.hibernate.annotations.TimeZoneStorageType

All Implemented Interfaces:

Serializable, Comparable<TimeZoneStorageType>

@Incubating
public enum TimeZoneStorageType
extends Enum<TimeZoneStorageType>

Describes the storage of timezone information for zoned datetime types, in particular, for the types OffsetDateTime and ZonedDateTime.

A default TimeZoneStorageType may be configured explicitly using "hibernate.timezone.default_storage". Otherwise, the storage type may be overridden for a given field or property of an entity using the TimeZoneStorage annotation.

In choosing a TimeZoneStorageType we must consider whether a round trip to the database, writing and then reading a zoned datetime, preserves:

• the instant represented by the zoned datetime, and/or
• the offset or zone in which the instant is represented.

We must also consider the physical representation of the zoned datetime in the database table.

The default strategy guarantees that a round trip preserves the instant. Whether the zone or offset is preserved depends on whether the underlying database has a timestamp with time zone type which preserves offsets:

• if the database does indeed have such an ANSI-compliant type, then both instant and zone or offset are preserved by round trips, but
• if not, it's guaranteed that the physical representation is in UTC, so that datetimes retrieved from the database will be represented in UTC.

When this default strategy is not appropriate, recommended alternatives are:

• AUTO or COLUMN, which each guarantee that both instant and zone or offset are preserved by round trips on every platform, or
• NORMALIZE_UTC, which guarantees that only the instant is preserved, and that datetimes retrieved from the database will always be represented in UTC.

Since:

6.0

See Also:

TimeZoneStorage, TimeZoneStorageStrategy

Enum Constant Summary

Enum Constants

Enum Constant	Description
AUTO	Stores the time zone either with NATIVE if Dialect.getTimeZoneSupport() is TimeZoneSupport.NATIVE, otherwise uses the COLUMN strategy.
COLUMN	Stores the time zone in a separate column; works in conjunction with TimeZoneColumn.
DEFAULT	Stores the time zone either with NATIVE if Dialect.getTimeZoneSupport() is TimeZoneSupport.NATIVE, otherwise uses the NORMALIZE_UTC strategy.
NATIVE	Stores the timezone by using the with time zone SQL column type.
NORMALIZE	Does not store the time zone, and instead: when persisting to the database, normalizes JDBC timestamps to the JdbcSettings.JDBC_TIME_ZONE or to the JVM default time zone if not set.
NORMALIZE_UTC	Does not preserve the time zone, and instead normalizes timestamps to UTC.

Method Summary

Modifier and Type	Method	Description
static TimeZoneStorageType	valueOf(String name)	Returns the enum constant of this type with the specified name.
static TimeZoneStorageType[]	values()	Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

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

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

NATIVE

public static final TimeZoneStorageType NATIVE

Stores the timezone by using the with time zone SQL column type.

Error if Dialect.getTimeZoneSupport() is not TimeZoneSupport.NATIVE.

NORMALIZE

public static final TimeZoneStorageType NORMALIZE

Does not store the time zone, and instead:

• when persisting to the database, normalizes JDBC timestamps to the JdbcSettings.JDBC_TIME_ZONE or to the JVM default time zone if not set.
• when reading back from the database, sets the offset or zone of OffsetDateTime/ZonedDateTime values to the JVM default time zone.

Provided partly for backward compatibility with older versions of Hibernate.

NORMALIZE_UTC

public static final TimeZoneStorageType NORMALIZE_UTC

Does not preserve the time zone, and instead normalizes timestamps to UTC.

The DDL column type depends on the setting "hibernate.type.preferred_instant_jdbc_type".

COLUMN

public static final TimeZoneStorageType COLUMN

Stores the time zone in a separate column; works in conjunction with TimeZoneColumn.

AUTO

public static final TimeZoneStorageType AUTO

Stores the time zone either with NATIVE if Dialect.getTimeZoneSupport() is TimeZoneSupport.NATIVE, otherwise uses the COLUMN strategy.

This option automatically picks an appropriate strategy for the database dialect which preserves both the instant represented by a zoned datetime type, and the offset or timezone.

DEFAULT

public static final TimeZoneStorageType DEFAULT

Stores the time zone either with NATIVE if Dialect.getTimeZoneSupport() is TimeZoneSupport.NATIVE, otherwise uses the NORMALIZE_UTC strategy.

This option automatically picks an appropriate strategy for the database dialect which preserves the instant represented by a zoned datetime type. It does not promise that the offset or timezone is preserved by a round trip to the database.

Since:

6.2

Method Detail

values

public static TimeZoneStorageType[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (TimeZoneStorageType c : TimeZoneStorageType.values())
    System.out.println(c);

Returns:

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

valueOf

public static TimeZoneStorageType valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (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 type has no constant with the specified name

NullPointerException - if the argument is null