org.joda.time
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 in 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, Pacific Time, USA is expressed as UTC-08:00, or UTC-07:00 in the summer. The offset -08:00 indicates that Pacific 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.

Since:

1.0

Author:

Brian S O'Neill, Stephen Colebourne

See Also:

Serialized Form

Field Summary

static DateTimeZone

UTC The UTC time zone

Constructor Summary

DateTimeZone(java.lang.String id)

Method Summary

abstract boolean	equals(java.lang.Object obj) Compare this datetime zone with another.
static java.util.Set	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.
static DateTimeZone	getInstance(java.lang.String id) Get the time zone by id.
static DateTimeZone	getInstance(java.util.TimeZone zone) Get the time zone by Java TimeZone.
java.lang.String	getName(long millis) Gets the long name of this datetime zone suitable for display using the default locale.
java.lang.String	getName(long millis, 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 millis) Returns a non-localized name that is unique to this time zone.
static NameProvider	getNameProvider()
abstract int	getOffset(long millis) 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 millisLocal) Gets the millisecond offset to subtract from local time to get UTC time.
static Provider	getProvider()
java.lang.String	getShortName(long millis) Gets the short name of this datetime zone suitable for display using the default locale.
java.lang.String	getShortName(long millis, java.util.Locale locale) Gets the short name of this datetime zone suitable for display using the specified locale.
abstract int	getStandardOffset(long millis) 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 long	nextTransition(long millis) Advances the given instant to where the time zone offset or name changes.
abstract long	previousTransition(long millis) 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)
static void	setProvider(Provider provider)
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 a TimeZone.
protected java.lang.Object	writeReplace() By default, when DateTimeZones are serialized, only a "stub" object referring to the id is written out.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

UTC

public static final DateTimeZone UTC

The UTC time zone

Constructor Detail

DateTimeZone

public DateTimeZone(java.lang.String id)

Method Detail

getDefault

public static DateTimeZone getDefault()

Gets the default time zone.

Returns:

the default datetime zone object

setDefault

public static void setDefault(DateTimeZone zone)
                       throws java.lang.SecurityException

Sets the default time zone.

Parameters:

zone - the default datetime zone object, must not be null

Throws:

java.lang.IllegalArgumentException - if the zone is null

java.lang.SecurityException

getInstance

public static DateTimeZone getInstance(java.lang.String id)
                                throws java.lang.IllegalArgumentException

Get the time zone by 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

Returns:

the DateTimeZone object for the ID

Throws:

java.lang.IllegalArgumentException - if the ID is null or not recognised

getInstance

public static DateTimeZone getInstance(java.util.TimeZone zone)

Get the time zone by Java 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.

Parameters:

zone - the zone to convert

Returns:

the DateTimeZone object for the zone

Throws:

java.lang.IllegalArgumentException - if the zone is null or not recognised

getAvailableIDs

public static java.util.Set getAvailableIDs()

Gets all the available IDs supported.

Returns:

an unmodifiable Set of String IDs

getProvider

public static Provider getProvider()

setProvider

public static void setProvider(Provider provider)
                        throws java.lang.SecurityException

java.lang.SecurityException

getNameProvider

public static NameProvider getNameProvider()

setNameProvider

public static void setNameProvider(NameProvider nameProvider)
                            throws java.lang.SecurityException

java.lang.SecurityException

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 millis)

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:

millis - 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 millis)

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:

millis - 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 millis,
                                     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:

millis - milliseconds from 1970-01-01T00:00:00Z to get the name for

Returns:

the human-readable short name in the specified locale

getName

public final java.lang.String getName(long millis)

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:

millis - 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 millis,
                                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:

millis - milliseconds from 1970-01-01T00:00:00Z to get the name for

Returns:

the human-readable long name in the specified locale

getOffset

public abstract int getOffset(long millis)

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

Parameters:

millis - 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.

Parameters:

instant - instant to get the offset for

Returns:

the millisecond offset to add to UTC to get local time

Throws:

java.lang.IllegalArgumentException - if the instant is null

getStandardOffset

public abstract int getStandardOffset(long millis)

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

Parameters:

millis - milliseconds from 1970-01-01T00:00:00Z to get the offset for

Returns:

the millisecond offset to add to UTC to get local time

getOffsetFromLocal

public int getOffsetFromLocal(long millisLocal)

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.

Parameters:

millisLocal - the millisecond instant, relative to this time zone, to get the offset for

Returns:

the millisceond offset to subtract from local time to get UTC time.

nextTransition

public abstract long nextTransition(long millis)

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:

millis - milliseconds from 1970-01-01T00:00:00Z

Returns:

milliseconds from 1970-01-01T00:00:00Z

previousTransition

public abstract long previousTransition(long millis)

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:

millis - 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 a TimeZone.

Returns:

the equivalent TimeZone object

equals

public abstract boolean equals(java.lang.Object obj)

Compare this datetime zone with another.

Overrides:

equals in class java.lang.Object

Returns:

true if equal, based on the ID and all internal rules

hashCode

public int hashCode()

Gets a hash code compatable with equals.

Overrides:

hashCode in class java.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 class java.lang.Object

writeReplace

protected java.lang.Object writeReplace()
                                 throws java.io.ObjectStreamException

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.

java.io.ObjectStreamException