| java.lang.Object
 org.joda.time.DateTimeZone
All known Subclasses: org.joda.time.MockZone, org.joda.time.tz.FixedDateTimeZone, org.joda.time.tz.CachedDateTimeZone,
| DateTimeZone | | abstract public class DateTimeZone implements Serializable(Code) | | 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.
author:
Brian S O'Neill
author:
Stephen Colebourne
since:
1.0 |
| Method Summary | |
| public long | convertLocalToUTC(long instantLocal, boolean strict)
Converts a local instant to a standard UTC instant with the same
local time. | | public long | convertUTCToLocal(long instantUTC)
Converts a standard UTC instant to a local instant with the same
local time. | | abstract public boolean | equals(Object object)
Compare this datetime zone with another. | | 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. | | public static DateTimeZone | forOffsetHours(int hoursOffset)
Gets a time zone instance for the specified offset to UTC in hours. | | public static DateTimeZone | forOffsetHoursMinutes(int hoursOffset, int minutesOffset)
Gets a time zone instance for the specified offset to UTC in hours and minutes. | | public static DateTimeZone | forOffsetMillis(int millisOffset)
Gets a time zone instance for the specified offset to UTC in milliseconds. | | 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. | | public static Set | getAvailableIDs()
Gets all the available IDs supported. | | public static DateTimeZone | getDefault()
Gets the default time zone. | | final public String | getID()
Gets 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. | | final public String | getName(long instant)
Gets the long name of this datetime zone suitable for display using
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. | | abstract public String | getNameKey(long instant)
Returns a non-localized name that is unique to this time zone. | | public static NameProvider | getNameProvider()
Gets the name provider factory. | | abstract public int | getOffset(long instant)
Gets the millisecond offset to add to UTC to get local time. | | final public int | getOffset(ReadableInstant instant)
Gets 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. | | public static Provider | getProvider()
Gets the zone provider factory. | | final public String | getShortName(long instant)
Gets the short name of this datetime zone suitable for display using
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. | | abstract public int | getStandardOffset(long instant)
Gets the standard millisecond offset to add to UTC to get local time,
when standard time is in effect. | | public int | hashCode()
Gets a hash code compatable with equals. | | abstract public boolean | isFixed()
Returns true if this time zone has no transitions. | | 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. | | abstract public long | nextTransition(long instant)
Advances the given instant to where the time zone offset or name changes. | | abstract public long | previousTransition(long instant)
Retreats the given instant to where the time zone offset or name changes. | | public static void | setDefault(DateTimeZone zone)
Sets the default time zone. | | public static void | setNameProvider(NameProvider nameProvider)
Sets the name provider factory. | | public static void | setProvider(Provider provider)
Sets the zone provider factory. | | public String | toString()
Gets the datetime zone as a string, which is simply its ID. | | public java.util.TimeZone | toTimeZone()
Get the datetime zone as a
java.util.TimeZone . | | protected Object | writeReplace()
By default, when DateTimeZones are serialized, only a "stub" object
referring to the id is written out. |
| UTC | | final public static DateTimeZone UTC(Code) | | The time zone for Universal Coordinated Time
|
| convertLocalToUTC | | public long convertLocalToUTC(long instantLocal, boolean strict)(Code) | | 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
Parameters:
strict - whether the conversion should reject non-existent local times the UTC instant with the same local time,
throws:
ArithmeticException - if the result overflows a long
throws:
IllegalArgumentException - if the zone has no eqivalent local time
since:
1.5 |
| convertUTCToLocal | | public long convertUTCToLocal(long instantUTC)(Code) | | 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 the local instant with the same local time
throws:
ArithmeticException - if the result overflows a long
since:
1.5 |
| equals | | abstract public boolean equals(Object object)(Code) | | Compare this datetime zone with another.
Parameters:
object - the object to compare with true if equal, based on the ID and all internal rules |
| forID | | public static DateTimeZone forID(String id)(Code) | | 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 the DateTimeZone object for the ID
throws:
IllegalArgumentException - if the ID is not recognised |
| forOffsetHours | | public static DateTimeZone forOffsetHours(int hoursOffset) throws IllegalArgumentException(Code) | | 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 the DateTimeZone object for the offset
throws:
IllegalArgumentException - if the offset is too large or too small |
| forOffsetHoursMinutes | | public static DateTimeZone forOffsetHoursMinutes(int hoursOffset, int minutesOffset) throws IllegalArgumentException(Code) | | 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 resultiong zone is '-02:30'.
Parameters:
hoursOffset - the offset in hours from UTC
Parameters:
minutesOffset - the offset in minutes from UTC, must be between 0 and 59 inclusive the DateTimeZone object for the offset
throws:
IllegalArgumentException - if the offset or minute is too large or too small |
| forOffsetMillis | | public static DateTimeZone forOffsetMillis(int millisOffset)(Code) | | Gets a time zone instance for the specified offset to UTC in milliseconds.
Parameters:
millisOffset - the offset in millis from UTC the DateTimeZone object for the offset |
| forTimeZone | | public static DateTimeZone forTimeZone(TimeZone zone)(Code) | | 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 the DateTimeZone object for the zone
throws:
IllegalArgumentException - if the zone is not recognised |
| getAvailableIDs | | public static Set getAvailableIDs()(Code) | | Gets all the available IDs supported.
an unmodifiable Set of String IDs |
| getDefault | | public static DateTimeZone getDefault()(Code) | | Gets the default time zone.
the default datetime zone object |
| getID | | final public String getID()(Code) | | Gets the ID of this datetime zone.
the ID of this datetime zone |
| getMillisKeepLocal | | public long getMillisKeepLocal(DateTimeZone newZone, long oldInstant)(Code) | | 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
Parameters:
oldInstant - the UTC millisecond instant to convert the UTC millisecond instant with the same local time in the new zone |
| getName | | final public String getName(long instant)(Code) | | 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 the human-readable long name in the default locale |
| getName | | public String getName(long instant, Locale locale)(Code) | | 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
Parameters:
locale - the locale to get the name for the human-readable long name in the specified locale |
| getNameKey | | abstract public String getNameKey(long instant)(Code) | | 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 name key or null if id should be used for names |
| getNameProvider | | public static NameProvider getNameProvider()(Code) | | Gets the name provider factory.
The name provider is a pluggable instance factory that supplies the
names of each DateTimeZone.
the provider |
| getOffset | | abstract public int getOffset(long instant)(Code) | | 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 the millisecond offset to add to UTC to get local time |
| getOffset | | final public int getOffset(ReadableInstant instant)(Code) | | Gets the millisecond offset to add to UTC to get local time.
Parameters:
instant - instant to get the offset for, null means now the millisecond offset to add to UTC to get local time |
| getOffsetFromLocal | | public int getOffsetFromLocal(long instantLocal)(Code) | | 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, toget the offset for the millisecond offset to subtract from local time to get UTC time |
| getProvider | | public static Provider getProvider()(Code) | | Gets the zone provider factory.
The zone provider is a pluggable instance factory that supplies the
actual instances of DateTimeZone.
the provider |
| getShortName | | final public String getShortName(long instant)(Code) | | 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 the human-readable short name in the default locale |
| getShortName | | public String getShortName(long instant, Locale locale)(Code) | | 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
Parameters:
locale - the locale to get the name for the human-readable short name in the specified locale |
| getStandardOffset | | abstract public int getStandardOffset(long instant)(Code) | | 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 the millisecond offset to add to UTC to get local time |
| hashCode | | public int hashCode()(Code) | | Gets a hash code compatable with equals.
suitable hashcode |
| isFixed | | abstract public boolean isFixed()(Code) | | Returns true if this time zone has no transitions.
true if no transitions |
| isStandardOffset | | public boolean isStandardOffset(long instant)(Code) | | 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
DateTimeZone.getOffset(long) equals
DateTimeZone.getStandardOffset(long) at the specified instant.
Parameters:
instant - milliseconds from 1970-01-01T00:00:00Z to get the offset for true if the offset at the given instant is the standard offset
since:
1.5 |
| nextTransition | | abstract public long nextTransition(long instant)(Code) | | 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 milliseconds from 1970-01-01T00:00:00Z |
| previousTransition | | abstract public long previousTransition(long instant)(Code) | | 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 milliseconds from 1970-01-01T00:00:00Z |
| setNameProvider | | public static void setNameProvider(NameProvider nameProvider) throws SecurityException(Code) | | 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
throws:
IllegalArgumentException - if the provider is invalid |
| setProvider | | public static void setProvider(Provider provider) throws SecurityException(Code) | | 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
throws:
IllegalArgumentException - if the provider is invalid |
| toString | | public String toString()(Code) | | Gets the datetime zone as a string, which is simply its ID.
the id of the zone |
| writeReplace | | protected Object writeReplace() throws ObjectStreamException(Code) | | 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.
a stub object to go in the stream |
|
|