public abstract class

DateTimeZone

extends Object
implements Serializable
java.lang.Object
   ↳ org.joda.time.DateTimeZone
Known Direct Subclasses

Class Overview

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 folowing definitions of time are generally used:

  • UTC - The reference time.
  • Standard Time - The local time without a daylight saving time offset. For example, in Paris, standard time is UTC+01:00.
  • Daylight Saving Time - The local time with a daylight saving time offset. This offset is typically one hour, but not always. It is typically used in most countries away from the equator. In Paris, daylight saving time is UTC+02:00.
  • Wall Time - This is what a local clock on the wall reads. This will be either Standard Time or Daylight Saving Time depending on the time of year and whether the location uses Daylight Saving Time.

Unlike the Java TimeZone class, DateTimeZone is immutable. It also only supports long format time zone ids. Thus EST 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.

DateTimeZone is thread-safe and immutable, and all subclasses must be as well.

Summary

Fields
public static final DateTimeZone UTC The time zone for Universal Coordinated Time
Protected Constructors
DateTimeZone(String id)
Constructor.
Public Methods
long convertLocalToUTC(long instantLocal, boolean strict)
Converts a local instant to a standard UTC instant with the same local time.
long convertUTCToLocal(long instantUTC)
Converts a standard UTC instant to a local instant with the same local time.
abstract boolean equals(Object object)
Compare this datetime zone with another.
static DateTimeZone forID(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(TimeZone zone)
Gets a time zone instance for a JDK TimeZone.
static Set getAvailableIDs()
Gets all the available IDs supported.
static DateTimeZone getDefault()
Gets the default time zone.
final 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.
final String getName(long instant)
Gets the long name of this datetime zone suitable for display using the default locale.
String getName(long instant, Locale locale)
Gets the long name of this datetime zone suitable for display using the specified locale.
abstract String getNameKey(long instant)
Returns a non-localized name that is unique to this time zone.
static NameProvider getNameProvider()
Gets the name provider factory.
final int getOffset(ReadableInstant instant)
Gets the millisecond offset to add to UTC to get local time.
abstract int getOffset(long 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.
final String getShortName(long instant)
Gets the short name of this datetime zone suitable for display using the default locale.
String getShortName(long instant, Locale locale)
Gets the short name of this datetime zone suitable for display using the specified locale.
abstract int getStandardOffset(long instant)
Gets the standard millisecond offset to add to UTC to get local time, when standard time is in effect.
int hashCode()
Gets a hash code compatable with equals.
abstract boolean isFixed()
Returns true if this time zone has no transitions.
boolean isLocalDateTimeGap(LocalDateTime localDateTime)
Checks if the given LocalDateTime is within a gap.
boolean isStandardOffset(long instant)
Checks whether, at a particular instant, the offset is standard 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.
String toString()
Gets the datetime zone as a string, which is simply its ID.
TimeZone toTimeZone()
Get the datetime zone as a TimeZone.
Protected Methods
Object writeReplace()
By default, when DateTimeZones are serialized, only a "stub" object referring to the id is written out.
[Expand]
Inherited Methods
From class java.lang.Object

Fields

public static final DateTimeZone UTC

The time zone for Universal Coordinated Time

Protected Constructors

protected DateTimeZone (String id)

Constructor.

Parameters
id the id to use
Throws
IllegalArgumentException if the id is null

Public Methods

public long convertLocalToUTC (long instantLocal, boolean strict)

Converts a local instant to a standard 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 UTC
strict whether the conversion should reject non-existent local times
Returns
  • the UTC instant with the same local time,
Throws
ArithmeticException if the result overflows a long
IllegalArgumentException if the zone has no eqivalent local time

public long convertUTCToLocal (long instantUTC)

Converts a standard 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
ArithmeticException if the result overflows a long

public abstract boolean equals (Object object)

Compare this datetime zone with another.

Parameters
object the object to compare with
Returns
  • true if equal, based on the ID and all internal rules

public static DateTimeZone forID (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 java.util.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
IllegalArgumentException if the ID is not recognised

public static DateTimeZone forOffsetHours (int hoursOffset)

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
Returns
  • the DateTimeZone object for the offset
Throws
IllegalArgumentException if the offset is too large or too small

public static DateTimeZone forOffsetHoursMinutes (int hoursOffset, int minutesOffset)

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 minutes value is always positive and in the range 0 to 59. If constructed with the values (-2, 30), the resulting zone is '-02:30'.

Parameters
hoursOffset the offset in hours from UTC
minutesOffset the offset in minutes from UTC, must be between 0 and 59 inclusive
Returns
  • the DateTimeZone object for the offset
Throws
IllegalArgumentException if the offset or minute is too large or too small

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
Returns
  • the DateTimeZone object for the offset

public static DateTimeZone forTimeZone (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
IllegalArgumentException if the zone is not recognised

public static Set getAvailableIDs ()

Gets all the available IDs supported.

Returns
  • an unmodifiable Set of String IDs

public static DateTimeZone getDefault ()

Gets the default time zone.

The default time zone is derived from the system property user.timezone. If that is null or is not a valid identifier, then the value of the JDK TimeZone default is converted. If that fails, UTC is used.

Returns
  • the default datetime zone object

public final String getID ()

Gets the ID of this datetime zone.

Returns
  • the ID of this datetime zone

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 default
oldInstant the UTC millisecond instant to convert
Returns
  • the UTC millisecond instant with the same local time in the new zone

public final 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

public String getName (long instant, 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 for
locale the locale to get the name for
Returns
  • the human-readable long name in the specified locale

public abstract 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

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

public final int getOffset (ReadableInstant instant)

Gets the millisecond offset to add to UTC to get local time.

Parameters
instant instant to get the offset for, null means now
Returns
  • the millisecond offset to add to UTC to get local time

public abstract int getOffset (long instant)

Gets the millisecond offset to add to UTC to get local time.

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

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.

This method will return an offset suitable for calculating an instant after any DST gap. For example, consider a zone with a cutover from 01:00 to 01:59:
Input: 00:00 Output: 00:00
Input: 00:30 Output: 00:30
Input: 01:00 Output: 02:00
Input: 01:30 Output: 02:30
Input: 02:00 Output: 02:00
Input: 02:30 Output: 02:30

NOTE: The behaviour of this method changed in v1.5, with the emphasis on returning a consistent result later along the time-line (shown above).

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

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

public final 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

public String getShortName (long instant, 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 for
locale the locale to get the name for
Returns
  • the human-readable short name in the specified locale

public abstract int getStandardOffset (long instant)

Gets the standard millisecond offset to add to UTC to get local time, when standard time is in effect.

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

public int hashCode ()

Gets a hash code compatable with equals.

Returns
  • suitable hashcode

public abstract boolean isFixed ()

Returns true if this time zone has no transitions.

Returns
  • true if no transitions

public boolean isLocalDateTimeGap (LocalDateTime localDateTime)

Checks if the given LocalDateTime is within a gap.

When switching from standard time to 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

public boolean isStandardOffset (long instant)

Checks whether, at a particular instant, the offset is standard or not.

This method can be used to determine whether Summer Time (DST) applies. As a general rule, if the offset at the specified instant is standard, then either Winter time applies, or there is no Summer Time. If the instant is not standard, then Summer Time applies.

The implementation of the method is simply whether getOffset(long) equals getStandardOffset(long) at the specified instant.

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 standard offset

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

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

public static void setDefault (DateTimeZone zone)

Sets the default time zone.

Parameters
zone the default datetime zone object, must not be null
Throws
IllegalArgumentException if the zone is null
SecurityException if the application has insufficient security rights

public static void setNameProvider (NameProvider nameProvider)

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
SecurityException if you do not have the permission DateTimeZone.setNameProvider
IllegalArgumentException if the provider is invalid

public static void setProvider (Provider provider)

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
SecurityException if you do not have the permission DateTimeZone.setProvider
IllegalArgumentException if the provider is invalid

public String toString ()

Gets the datetime zone as a string, which is simply its ID.

Returns
  • the id of the zone

public TimeZone toTimeZone ()

Get the datetime zone as a TimeZone.

Returns
  • the closest matching TimeZone object

Protected Methods

protected Object writeReplace ()

By default, when DateTimeZones are serialized, only a "stub" object referring to the id is written out. When the stub is read in, it replaces itself with a DateTimeZone object.

Returns
  • a stub object to go in the stream
Throws
ObjectStreamException