Class DateTimeZone
- java.lang.Object
-
- org.joda.time.DateTimeZone
-
- All Implemented Interfaces:
java.io.Serializable
- Direct Known Subclasses:
CachedDateTimeZone
,FixedDateTimeZone
public abstract class DateTimeZone extends java.lang.Object implements java.io.Serializable
DateTimeZone represents a time zone.A time zone is a system of rules to convert time from one geographic location to another. For example, Paris, France is one hour ahead of London, England. Thus when it is 10:00 in London, it is 11:00 in Paris.
All time zone rules are expressed, for historical reasons, relative to Greenwich, London. Local time in Greenwich is referred to as Greenwich Mean Time (GMT). This is similar, but not precisely identical, to Universal Coordinated Time, or UTC. This library only uses the term UTC.
Using this system, America/Los_Angeles is expressed as UTC-08:00, or UTC-07:00 in the summer. The offset -08:00 indicates that America/Los_Angeles time is obtained from UTC by adding -08:00, that is, by subtracting 8 hours.
The offset differs in the summer because of daylight saving time, or DST. The following definitions are helpful:
- UTC - The reference time.
- Offset - The amount of time a zone differs from UTC. This can vary during the year.
- Daylight Saving - The process of having two offsets each year, one in winter and one in summer.
- Raw offset - The base offset of the zone.
- Additional offset - The additional offset on top of the raw offset. This is typically zero in winter and one hour in summer in zones that apply DST.
- Actual offset - The actual offset that applies, which is the combination of the raw offset and additional offset.
For example, in 2018 Greece applied daylight saving. Throughout the whole year, the raw offset was +02:00. In winter, the additional offset was zero, while in summer the additional offset was one hour. Thus, the actual offset was +02:00 in winter and +03:00 in summer.
Note: Some governments, most notably Ireland, define daylight saving by describing a "standard" time in summer and a negative DST offset in winter. Joda-Time, like the JDK, follows a model for time-zone data where there is a raw offset all year round and a positive additional offset. As such, callers cannot assume that the raw offset is that defined by law for the zone.
Note: Some governments define a daylight saving time that applies for two separate periods. For example, the year might be winter time, then summer time, then a special time equal to winter time, then back to summer time before finally dropping back to winter time. As such, callers cannot assume that the raw and DST offsets directly correlate to summer and winter.
Unlike the Java TimeZone class, DateTimeZone is immutable. It also only supports long format time zone ids. Thus PST and ECT are not accepted. However, the factory that accepts a TimeZone will attempt to convert from the old short id to a suitable long id.
There are four approaches to loading time-zone data, which are tried in this order:
- load the specific
Provider
specified by the system propertyorg.joda.time.DateTimeZone.Provider
. - load
ZoneInfoProvider
using the data in the filing system folder pointed to by system propertyorg.joda.time.DateTimeZone.Folder
. - load
ZoneInfoProvider
using the data in the classpath locationorg/joda/time/tz/data
. - load
UTCProvider
Unless you override the standard behaviour, the default if the third approach.
DateTimeZone is thread-safe and immutable, and all subclasses must be as well.
- Since:
- 1.0
- See Also:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
DEFAULT_TZ_DATA_PATH
The default TZ data path This is the default classpath location containing the compiled data files.static DateTimeZone
UTC
The time zone for Universal Coordinated Time
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description long
adjustOffset(long instant, boolean earlierOrLater)
Adjusts the offset to be the earlier or later one during an overlap.long
convertLocalToUTC(long instantLocal, boolean strict)
Converts a local instant to an actual UTC instant with the same local time.long
convertLocalToUTC(long instantLocal, boolean strict, long originalInstantUTC)
Converts a local instant to an actual UTC instant with the same local time attempting to use the same offset as the original.long
convertUTCToLocal(long instantUTC)
Converts an actual UTC instant to a local instant with the same local time.abstract boolean
equals(java.lang.Object object)
Compare this datetime zone with another.static DateTimeZone
forID(java.lang.String id)
Gets a time zone instance for the specified time zone id.static DateTimeZone
forOffsetHours(int hoursOffset)
Gets a time zone instance for the specified offset to UTC in hours.static DateTimeZone
forOffsetHoursMinutes(int hoursOffset, int minutesOffset)
Gets a time zone instance for the specified offset to UTC in hours and minutes.static DateTimeZone
forOffsetMillis(int millisOffset)
Gets a time zone instance for the specified offset to UTC in milliseconds.static DateTimeZone
forTimeZone(java.util.TimeZone zone)
Gets a time zone instance for a JDK TimeZone.static java.util.Set<java.lang.String>
getAvailableIDs()
Gets all the available IDs supported.static DateTimeZone
getDefault()
Gets the default time zone.java.lang.String
getID()
Gets the ID of this datetime zone.long
getMillisKeepLocal(DateTimeZone newZone, long oldInstant)
Gets the millisecond instant in another zone keeping the same local time.java.lang.String
getName(long instant)
Gets the long name of this datetime zone suitable for display using the default locale.java.lang.String
getName(long instant, java.util.Locale locale)
Gets the long name of this datetime zone suitable for display using the specified locale.abstract java.lang.String
getNameKey(long instant)
Returns a non-localized name that is unique to this time zone.static NameProvider
getNameProvider()
Gets the name provider factory.abstract int
getOffset(long instant)
Gets the millisecond offset to add to UTC to get local time.int
getOffset(ReadableInstant instant)
Gets the millisecond offset to add to UTC to get local time.int
getOffsetFromLocal(long instantLocal)
Gets the millisecond offset to subtract from local time to get UTC time.static Provider
getProvider()
Gets the zone provider factory.java.lang.String
getShortName(long instant)
Gets the short name of this datetime zone suitable for display using the default locale.java.lang.String
getShortName(long instant, java.util.Locale locale)
Gets the short name of this datetime zone suitable for display using the specified locale.abstract int
getStandardOffset(long instant)
Gets the raw millisecond offset to add to UTC.int
hashCode()
Gets a hash code compatible with equals.abstract boolean
isFixed()
Returns true if this time zone has no transitions.boolean
isLocalDateTimeGap(LocalDateTime localDateTime)
Checks if the givenLocalDateTime
is within a gap.boolean
isStandardOffset(long instant)
Checks whether, at a particular instant, the offset is raw or not.abstract long
nextTransition(long instant)
Advances the given instant to where the time zone offset or name changes.abstract long
previousTransition(long instant)
Retreats the given instant to where the time zone offset or name changes.static void
setDefault(DateTimeZone zone)
Sets the default time zone.static void
setNameProvider(NameProvider nameProvider)
Sets the name provider factory.static void
setProvider(Provider provider)
Sets the zone provider factory.java.lang.String
toString()
Gets the datetime zone as a string, which is simply its ID.java.util.TimeZone
toTimeZone()
Get the datetime zone as aTimeZone
.
-
-
-
Field Detail
-
UTC
public static final DateTimeZone UTC
The time zone for Universal Coordinated Time
-
DEFAULT_TZ_DATA_PATH
public static final java.lang.String DEFAULT_TZ_DATA_PATH
The default TZ data path This is the default classpath location containing the compiled data files.- See Also:
- Constant Field Values
-
-
Method Detail
-
getDefault
public static DateTimeZone getDefault()
Gets the default time zone.The default time zone is derived from the system property
user.timezone
. If that isnull
or is not a valid identifier, then the value of the JDKTimeZone
default is converted. If that fails,UTC
is used.NOTE: If the
java.util.TimeZone
default is updated after calling this method, then the change will not be picked up here.- Returns:
- the default datetime zone object
-
setDefault
public static void setDefault(DateTimeZone zone) throws java.lang.SecurityException
Sets the default time zone.NOTE: Calling this method does not set the
java.util.TimeZone
default.- Parameters:
zone
- the default datetime zone object, must not be null- Throws:
java.lang.IllegalArgumentException
- if the zone is nulljava.lang.SecurityException
- if the application has insufficient security rights
-
forID
public static DateTimeZone forID(java.lang.String id)
Gets a time zone instance for the specified time zone id.The time zone id may be one of those returned by getAvailableIDs. Short ids, as accepted by
TimeZone
, are not accepted. All IDs must be specified in the long format. The exception is UTC, which is an acceptable id.Alternatively a locale independent, fixed offset, datetime zone can be specified. The form
[+-]hh:mm
can be used.- Parameters:
id
- the ID of the datetime zone, null means default- Returns:
- the DateTimeZone object for the ID
- Throws:
java.lang.IllegalArgumentException
- if the ID is not recognised
-
forOffsetHours
public static DateTimeZone forOffsetHours(int hoursOffset) throws java.lang.IllegalArgumentException
Gets a time zone instance for the specified offset to UTC in hours. This method assumes standard length hours.This factory is a convenient way of constructing zones with a fixed offset.
- Parameters:
hoursOffset
- the offset in hours from UTC, from -23 to +23- Returns:
- the DateTimeZone object for the offset
- Throws:
java.lang.IllegalArgumentException
- if the offset is too large or too small
-
forOffsetHoursMinutes
public static DateTimeZone forOffsetHoursMinutes(int hoursOffset, int minutesOffset) throws java.lang.IllegalArgumentException
Gets a time zone instance for the specified offset to UTC in hours and minutes. This method assumes 60 minutes in an hour, and standard length minutes.This factory is a convenient way of constructing zones with a fixed offset. The hours value must be in the range -23 to +23. The minutes value must be in the range -59 to +59. The following combinations of sign for the hour and minute are possible:
Hour Minute Example Result +ve +ve (2, 15) +02:15 +ve zero (2, 0) +02:00 +ve -ve (2, -15) IllegalArgumentException zero +ve (0, 15) +00:15 zero zero (0, 0) +00:00 zero -ve (0, -15) -00:15 -ve +ve (-2, 15) -02:15 -ve zero (-2, 0) -02:00 -ve -ve (-2, -15) -02:15
Note that in versions before 2.3, the minutes had to be zero or positive.- Parameters:
hoursOffset
- the offset in hours from UTC, from -23 to +23minutesOffset
- the offset in minutes from UTC, from -59 to +59- Returns:
- the DateTimeZone object for the offset
- Throws:
java.lang.IllegalArgumentException
- if any value is out of range, the minutes are negative when the hours are positive, or the resulting offset exceeds +/- 23:59:59.000
-
forOffsetMillis
public static DateTimeZone forOffsetMillis(int millisOffset)
Gets a time zone instance for the specified offset to UTC in milliseconds.- Parameters:
millisOffset
- the offset in millis from UTC, from -23:59:59.999 to +23:59:59.999- Returns:
- the DateTimeZone object for the offset
-
forTimeZone
public static DateTimeZone forTimeZone(java.util.TimeZone zone)
Gets a time zone instance for a JDK TimeZone.DateTimeZone only accepts a subset of the IDs from TimeZone. The excluded IDs are the short three letter form (except UTC). This method will attempt to convert between time zones created using the short IDs and the full version.
This method is not designed to parse time zones with rules created by applications using
SimpleTimeZone
directly.- Parameters:
zone
- the zone to convert, null means default- Returns:
- the DateTimeZone object for the zone
- Throws:
java.lang.IllegalArgumentException
- if the zone is not recognised
-
getAvailableIDs
public static java.util.Set<java.lang.String> getAvailableIDs()
Gets all the available IDs supported.- Returns:
- an unmodifiable Set of String IDs
-
getProvider
public static Provider getProvider()
Gets the zone provider factory.The zone provider is a pluggable instance factory that supplies the actual instances of DateTimeZone.
- Returns:
- the provider
-
setProvider
public static void setProvider(Provider provider) throws java.lang.SecurityException
Sets the zone provider factory.The zone provider is a pluggable instance factory that supplies the actual instances of DateTimeZone.
- Parameters:
provider
- provider to use, or null for default- Throws:
java.lang.SecurityException
- if you do not have the permission DateTimeZone.setProviderjava.lang.IllegalArgumentException
- if the provider is invalid
-
getNameProvider
public static NameProvider getNameProvider()
Gets the name provider factory.The name provider is a pluggable instance factory that supplies the names of each DateTimeZone.
- Returns:
- the provider
-
setNameProvider
public static void setNameProvider(NameProvider nameProvider) throws java.lang.SecurityException
Sets the name provider factory.The name provider is a pluggable instance factory that supplies the names of each DateTimeZone.
- Parameters:
nameProvider
- provider to use, or null for default- Throws:
java.lang.SecurityException
- if you do not have the permission DateTimeZone.setNameProviderjava.lang.IllegalArgumentException
- if the provider is invalid
-
getID
public final java.lang.String getID()
Gets the ID of this datetime zone.- Returns:
- the ID of this datetime zone
-
getNameKey
public abstract java.lang.String getNameKey(long instant)
Returns a non-localized name that is unique to this time zone. It can be combined with id to form a unique key for fetching localized names.- Parameters:
instant
- milliseconds from 1970-01-01T00:00:00Z to get the name for- Returns:
- name key or null if id should be used for names
-
getShortName
public final java.lang.String getShortName(long instant)
Gets the short name of this datetime zone suitable for display using the default locale.If the name is not available for the locale, then this method returns a string in the format
[+-]hh:mm
.- Parameters:
instant
- milliseconds from 1970-01-01T00:00:00Z to get the name for- Returns:
- the human-readable short name in the default locale
-
getShortName
public java.lang.String getShortName(long instant, java.util.Locale locale)
Gets the short name of this datetime zone suitable for display using the specified locale.If the name is not available for the locale, then this method returns a string in the format
[+-]hh:mm
.- Parameters:
instant
- milliseconds from 1970-01-01T00:00:00Z to get the name forlocale
- the locale to get the name for- Returns:
- the human-readable short name in the specified locale
-
getName
public final java.lang.String getName(long instant)
Gets the long name of this datetime zone suitable for display using the default locale.If the name is not available for the locale, then this method returns a string in the format
[+-]hh:mm
.- Parameters:
instant
- milliseconds from 1970-01-01T00:00:00Z to get the name for- Returns:
- the human-readable long name in the default locale
-
getName
public java.lang.String getName(long instant, java.util.Locale locale)
Gets the long name of this datetime zone suitable for display using the specified locale.If the name is not available for the locale, then this method returns a string in the format
[+-]hh:mm
.- Parameters:
instant
- milliseconds from 1970-01-01T00:00:00Z to get the name forlocale
- the locale to get the name for- Returns:
- the human-readable long name in the specified locale
-
getOffset
public abstract int getOffset(long instant)
Gets the millisecond offset to add to UTC to get local time.This returns the actual offset from UTC for the zone at the specified instant. If the method is called with a different instant, the offset returned may be different as a result of daylight saving or other government rule changes.
- Parameters:
instant
- milliseconds from 1970-01-01T00:00:00Z to get the offset for- Returns:
- the millisecond offset to add to UTC to get local time
-
getOffset
public final int getOffset(ReadableInstant instant)
Gets the millisecond offset to add to UTC to get local time.This returns the actual offset from UTC for the zone at the specified instant. If the method is called with a different instant, the offset returned may be different as a result of daylight saving or other government rule changes.
- Parameters:
instant
- instant to get the offset for, null means now- Returns:
- the millisecond offset to add to UTC to get local time
-
getStandardOffset
public abstract int getStandardOffset(long instant)
Gets the raw millisecond offset to add to UTC.This should be treated as an implementation detail. End-users should use
getOffset(long)
.This returns the raw offset from UTC for the zone at the specified instant, effectively ignoring DST. If the method is called with a different instant, the offset returned may be different as a result of government rule changes.
This method should be named
getRawOffset()
but cannot be renamed for compatibility reasons.- Parameters:
instant
- milliseconds from 1970-01-01T00:00:00Z to get the offset for- Returns:
- the millisecond offset to add to UTC to get local time
-
isStandardOffset
public boolean isStandardOffset(long instant)
Checks whether, at a particular instant, the offset is raw or not.This method can be used to estimate whether Summer Time (DST) applies at the specified instant. As a general rule, if the actual offset equals the raw offset at the specified instant then either winter time applies or the zone does not have DST rules. If the actual offset does not equal the raw offset, then some form of Summer Time applies.
The implementation of the method is simply whether
getOffset(long)
equalsgetStandardOffset(long)
at the specified instant.This method should be named
isRawOffsetInUse()
but cannot be renamed for compatibility reasons.- Parameters:
instant
- milliseconds from 1970-01-01T00:00:00Z to get the offset for- Returns:
- true if the offset at the given instant is the same as the raw offset
- Since:
- 1.5
-
getOffsetFromLocal
public int getOffsetFromLocal(long instantLocal)
Gets the millisecond offset to subtract from local time to get UTC time. This offset can be used to undo adding the offset obtained by getOffset.millisLocal == millisUTC + getOffset(millisUTC) millisUTC == millisLocal - getOffsetFromLocal(millisLocal)
NOTE: After calculating millisLocal, some error may be introduced. At offset transitions (due to DST or other historical changes), ranges of local times may map to different UTC times.For overlaps (where the local time is ambiguous), this method returns the offset applicable before the gap. The effect of this is that any instant calculated using the offset from an overlap will be in "summer" time.
For gaps, this method returns the offset applicable before the gap, ie "winter" offset. However, the effect of this is that any instant calculated using the offset from a gap will be after the gap, in "summer" time.
For example, consider a zone with a gap from 01:00 to 01:59:
Input: 00:00 (before gap) Output: Offset applicable before gap DateTime: 00:00
Input: 00:30 (before gap) Output: Offset applicable before gap DateTime: 00:30
Input: 01:00 (in gap) Output: Offset applicable before gap DateTime: 02:00
Input: 01:30 (in gap) Output: Offset applicable before gap DateTime: 02:30
Input: 02:00 (after gap) Output: Offset applicable after gap DateTime: 02:00
Input: 02:30 (after gap) Output: Offset applicable after gap DateTime: 02:30
NOTE: Prior to v2.0, the DST overlap behaviour was not defined and varied by hemisphere. Prior to v1.5, the DST gap behaviour was also not defined. In v2.4, the documentation was clarified again.
- Parameters:
instantLocal
- the millisecond instant, relative to this time zone, to get the offset for- Returns:
- the millisecond offset to subtract from local time to get UTC time
-
convertUTCToLocal
public long convertUTCToLocal(long instantUTC)
Converts an actual UTC instant to a local instant with the same local time. This conversion is used before performing a calculation so that the calculation can be done using a simple local zone.- Parameters:
instantUTC
- the UTC instant to convert to local- Returns:
- the local instant with the same local time
- Throws:
java.lang.ArithmeticException
- if the result overflows a long- Since:
- 1.5
-
convertLocalToUTC
public long convertLocalToUTC(long instantLocal, boolean strict, long originalInstantUTC)
Converts a local instant to an actual UTC instant with the same local time attempting to use the same offset as the original.This conversion is used after performing a calculation where the calculation was done using a simple local zone. Whenever possible, the same offset as the original offset will be used. This is most significant during a daylight savings overlap.
- Parameters:
instantLocal
- the local instant to convert to UTCstrict
- whether the conversion should reject non-existent local timesoriginalInstantUTC
- the original instant that the calculation is based on- Returns:
- the UTC instant with the same local time,
- Throws:
java.lang.ArithmeticException
- if the result overflows a longjava.lang.IllegalArgumentException
- if the zone has no equivalent local time- Since:
- 2.0
-
convertLocalToUTC
public long convertLocalToUTC(long instantLocal, boolean strict)
Converts a local instant to an actual UTC instant with the same local time. This conversion is used after performing a calculation where the calculation was done using a simple local zone.- Parameters:
instantLocal
- the local instant to convert to UTCstrict
- whether the conversion should reject non-existent local times- Returns:
- the UTC instant with the same local time,
- Throws:
java.lang.ArithmeticException
- if the result overflows a longIllegalInstantException
- if the zone has no equivalent local time- Since:
- 1.5
-
getMillisKeepLocal
public long getMillisKeepLocal(DateTimeZone newZone, long oldInstant)
Gets the millisecond instant in another zone keeping the same local time.The conversion is performed by converting the specified UTC millis to local millis in this zone, then converting back to UTC millis in the new zone.
- Parameters:
newZone
- the new zone, null means defaultoldInstant
- the UTC millisecond instant to convert- Returns:
- the UTC millisecond instant with the same local time in the new zone
-
isLocalDateTimeGap
public boolean isLocalDateTimeGap(LocalDateTime localDateTime)
Checks if the givenLocalDateTime
is within a gap.When switching into Daylight Savings Time there is typically a gap where a clock hour is missing. This method identifies whether the local datetime refers to such a gap.
- Parameters:
localDateTime
- the time to check, not null- Returns:
- true if the given datetime refers to a gap
- Since:
- 1.6
-
adjustOffset
public long adjustOffset(long instant, boolean earlierOrLater)
Adjusts the offset to be the earlier or later one during an overlap.- Parameters:
instant
- the instant to adjustearlierOrLater
- false for earlier, true for later- Returns:
- the adjusted instant millis
-
isFixed
public abstract boolean isFixed()
Returns true if this time zone has no transitions.- Returns:
- true if no transitions
-
nextTransition
public abstract long nextTransition(long instant)
Advances the given instant to where the time zone offset or name changes. If the instant returned is exactly the same as passed in, then no changes occur after the given instant.- Parameters:
instant
- milliseconds from 1970-01-01T00:00:00Z- Returns:
- milliseconds from 1970-01-01T00:00:00Z
-
previousTransition
public abstract long previousTransition(long instant)
Retreats the given instant to where the time zone offset or name changes. If the instant returned is exactly the same as passed in, then no changes occur before the given instant.- Parameters:
instant
- milliseconds from 1970-01-01T00:00:00Z- Returns:
- milliseconds from 1970-01-01T00:00:00Z
-
toTimeZone
public java.util.TimeZone toTimeZone()
Get the datetime zone as aTimeZone
.- Returns:
- the closest matching TimeZone object
-
equals
public abstract boolean equals(java.lang.Object object)
Compare this datetime zone with another.- Overrides:
equals
in classjava.lang.Object
- Parameters:
object
- the object to compare with- Returns:
- true if equal, based on the ID and all internal rules
-
hashCode
public int hashCode()
Gets a hash code compatible with equals.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- suitable hashcode
-
toString
public java.lang.String toString()
Gets the datetime zone as a string, which is simply its ID.- Overrides:
toString
in classjava.lang.Object
- Returns:
- the id of the zone
-
-