|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.joda.time.DateTimeZone
public abstract class DateTimeZone
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 of time are generally used:
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.
Field Summary | |
---|---|
static DateTimeZone |
UTC
The time zone for Universal Coordinated Time |
Constructor Summary | |
---|---|
protected |
DateTimeZone(String id)
Constructor. |
Method Summary | |
---|---|
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 a standard UTC instant with the same local time. |
long |
convertLocalToUTC(long instantLocal,
boolean strict,
long originalInstantUTC)
Converts a local instant to a standard UTC instant with the same local time attempting to use the same offset as the original. |
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<String> |
getAvailableIDs()
Gets all the available IDs supported. |
static DateTimeZone |
getDefault()
Gets the default time zone. |
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. |
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. |
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. |
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 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 |
---|
public static final DateTimeZone UTC
Constructor Detail |
---|
protected DateTimeZone(String id)
id
- the id to use
IllegalArgumentException
- if the id is nullMethod Detail |
---|
public static DateTimeZone getDefault()
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.
NOTE: If the java.util.TimeZone
default is updated after calling this
method, then the change will not be picked up here.
public static void setDefault(DateTimeZone zone) throws SecurityException
NOTE: Calling this method does not set the java.util.TimeZone
default.
zone
- the default datetime zone object, must not be null
IllegalArgumentException
- if the zone is null
SecurityException
- if the application has insufficient security rightspublic static DateTimeZone forID(String 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.
id
- the ID of the datetime zone, null means default
IllegalArgumentException
- if the ID is not recognisedpublic static DateTimeZone forOffsetHours(int hoursOffset) throws IllegalArgumentException
This factory is a convenient way of constructing zones with a fixed offset.
hoursOffset
- the offset in hours from UTC
IllegalArgumentException
- if the offset is too large or too smallpublic static DateTimeZone forOffsetHoursMinutes(int hoursOffset, int minutesOffset) throws IllegalArgumentException
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'.
hoursOffset
- the offset in hours from UTCminutesOffset
- the offset in minutes from UTC, must be between 0 and 59 inclusive
IllegalArgumentException
- if the offset or minute is too large or too smallpublic static DateTimeZone forOffsetMillis(int millisOffset)
millisOffset
- the offset in millis from UTC
public static DateTimeZone forTimeZone(TimeZone zone)
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.
zone
- the zone to convert, null means default
IllegalArgumentException
- if the zone is not recognisedpublic static Set<String> getAvailableIDs()
public static Provider getProvider()
The zone provider is a pluggable instance factory that supplies the actual instances of DateTimeZone.
public static void setProvider(Provider provider) throws SecurityException
The zone provider is a pluggable instance factory that supplies the actual instances of DateTimeZone.
provider
- provider to use, or null for default
SecurityException
- if you do not have the permission DateTimeZone.setProvider
IllegalArgumentException
- if the provider is invalidpublic static NameProvider getNameProvider()
The name provider is a pluggable instance factory that supplies the names of each DateTimeZone.
public static void setNameProvider(NameProvider nameProvider) throws SecurityException
The name provider is a pluggable instance factory that supplies the names of each DateTimeZone.
nameProvider
- provider to use, or null for default
SecurityException
- if you do not have the permission DateTimeZone.setNameProvider
IllegalArgumentException
- if the provider is invalidpublic final String getID()
public abstract String getNameKey(long instant)
instant
- milliseconds from 1970-01-01T00:00:00Z to get the name for
public final String getShortName(long instant)
If the name is not available for the locale, then this method returns a
string in the format [+-]hh:mm
.
instant
- milliseconds from 1970-01-01T00:00:00Z to get the name for
public String getShortName(long instant, Locale locale)
If the name is not available for the locale, then this method returns a
string in the format [+-]hh:mm
.
instant
- milliseconds from 1970-01-01T00:00:00Z to get the name forlocale
- the locale to get the name for
public final String getName(long instant)
If the name is not available for the locale, then this method returns a
string in the format [+-]hh:mm
.
instant
- milliseconds from 1970-01-01T00:00:00Z to get the name for
public String getName(long instant, Locale locale)
If the name is not available for the locale, then this method returns a
string in the format [+-]hh:mm
.
instant
- milliseconds from 1970-01-01T00:00:00Z to get the name forlocale
- the locale to get the name for
public abstract int getOffset(long instant)
instant
- milliseconds from 1970-01-01T00:00:00Z to get the offset for
public final int getOffset(ReadableInstant instant)
instant
- instant to get the offset for, null means now
public abstract int getStandardOffset(long instant)
instant
- milliseconds from 1970-01-01T00:00:00Z to get the offset for
public boolean isStandardOffset(long instant)
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.
instant
- milliseconds from 1970-01-01T00:00:00Z to get the offset for
public int getOffsetFromLocal(long instantLocal)
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
During a DST overlap (where the local time is ambiguous) this method will return the earlier instant. The combination of these two rules is to always favour daylight (summer) time over standard (winter) time.
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.
instantLocal
- the millisecond instant, relative to this time zone, to get the offset for
public long convertUTCToLocal(long instantUTC)
instantUTC
- the UTC instant to convert to local
ArithmeticException
- if the result overflows a longpublic long convertLocalToUTC(long instantLocal, boolean strict, long originalInstantUTC)
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.
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
ArithmeticException
- if the result overflows a long
IllegalArgumentException
- if the zone has no equivalent local timepublic long convertLocalToUTC(long instantLocal, boolean strict)
instantLocal
- the local instant to convert to UTCstrict
- whether the conversion should reject non-existent local times
ArithmeticException
- if the result overflows a long
IllegalInstantException
- if the zone has no equivalent local timepublic long getMillisKeepLocal(DateTimeZone newZone, long oldInstant)
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.
newZone
- the new zone, null means defaultoldInstant
- the UTC millisecond instant to convert
public boolean isLocalDateTimeGap(LocalDateTime localDateTime)
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.
localDateTime
- the time to check, not null
public long adjustOffset(long instant, boolean earlierOrLater)
instant
- the instant to adjustearlierOrLater
- false for earlier, true for later
public abstract boolean isFixed()
public abstract long nextTransition(long instant)
instant
- milliseconds from 1970-01-01T00:00:00Z
public abstract long previousTransition(long instant)
instant
- milliseconds from 1970-01-01T00:00:00Z
public TimeZone toTimeZone()
TimeZone
.
public abstract boolean equals(Object object)
equals
in class Object
object
- the object to compare with
public int hashCode()
hashCode
in class Object
public String toString()
toString
in class Object
protected Object writeReplace() throws ObjectStreamException
ObjectStreamException
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |