Package org.joda.time.tz

Class DateTimeZoneBuilder

  • public class DateTimeZoneBuilder
extends java.lang.Object
    DateTimeZoneBuilder allows complex DateTimeZones to be constructed. Since creating a new DateTimeZone this way is a relatively expensive operation, built zones can be written to a file. Reading back the encoded data is a quick operation.

    DateTimeZoneBuilder itself is mutable and not thread-safe, but the DateTimeZone objects that it builds are thread-safe and immutable.

    It is intended that ZoneInfoCompiler be used to read time zone data files, indirectly calling DateTimeZoneBuilder. The following complex example defines the America/Los_Angeles time zone, with all historical transitions: 

     DateTimeZone America_Los_Angeles = new DateTimeZoneBuilder()
     .addCutover(-2147483648, 'w', 1, 1, 0, false, 0)
     .setStandardOffset(-28378000)
     .setFixedSavings("LMT", 0)
     .addCutover(1883, 'w', 11, 18, 0, false, 43200000)
     .setStandardOffset(-28800000)
     .addRecurringSavings("PDT", 3600000, 1918, 1919, 'w',  3, -1, 7, false, 7200000)
     .addRecurringSavings("PST",       0, 1918, 1919, 'w', 10, -1, 7, false, 7200000)
     .addRecurringSavings("PWT", 3600000, 1942, 1942, 'w',  2,  9, 0, false, 7200000)
     .addRecurringSavings("PPT", 3600000, 1945, 1945, 'u',  8, 14, 0, false, 82800000)
     .addRecurringSavings("PST",       0, 1945, 1945, 'w',  9, 30, 0, false, 7200000)
     .addRecurringSavings("PDT", 3600000, 1948, 1948, 'w',  3, 14, 0, false, 7200000)
     .addRecurringSavings("PST",       0, 1949, 1949, 'w',  1,  1, 0, false, 7200000)
     .addRecurringSavings("PDT", 3600000, 1950, 1966, 'w',  4, -1, 7, false, 7200000)
     .addRecurringSavings("PST",       0, 1950, 1961, 'w',  9, -1, 7, false, 7200000)
     .addRecurringSavings("PST",       0, 1962, 1966, 'w', 10, -1, 7, false, 7200000)
     .addRecurringSavings("PST",       0, 1967, 2147483647, 'w', 10, -1, 7, false, 7200000)
     .addRecurringSavings("PDT", 3600000, 1967, 1973, 'w', 4, -1,  7, false, 7200000)
     .addRecurringSavings("PDT", 3600000, 1974, 1974, 'w', 1,  6,  0, false, 7200000)
     .addRecurringSavings("PDT", 3600000, 1975, 1975, 'w', 2, 23,  0, false, 7200000)
     .addRecurringSavings("PDT", 3600000, 1976, 1986, 'w', 4, -1,  7, false, 7200000)
     .addRecurringSavings("PDT", 3600000, 1987, 2147483647, 'w', 4, 1, 7, true, 7200000)
     .toDateTimeZone("America/Los_Angeles", true);
    Since:
    1.0
    See Also:
    ZoneInfoCompiler, ZoneInfoProvider

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      DateTimeZoneBuilder addCutover​(int year, char mode, int monthOfYear, int dayOfMonth, int dayOfWeek, boolean advanceDayOfWeek, int millisOfDay)
      Adds a cutover for added rules.
      DateTimeZoneBuilder addRecurringSavings​(java.lang.String nameKey, int saveMillis, int fromYear, int toYear, char mode, int monthOfYear, int dayOfMonth, int dayOfWeek, boolean advanceDayOfWeek, int millisOfDay)
      Add a recurring daylight saving time rule.
      static DateTimeZone readFrom​(java.io.DataInput in, java.lang.String id)
      Decodes a built DateTimeZone from the given stream, as encoded by writeTo.
      static DateTimeZone readFrom​(java.io.InputStream in, java.lang.String id)
      Decodes a built DateTimeZone from the given stream, as encoded by writeTo.
      DateTimeZoneBuilder setFixedSavings​(java.lang.String nameKey, int saveMillis)
      Set a fixed savings rule at the cutover.
      DateTimeZoneBuilder setStandardOffset​(int standardOffset)
      Sets the standard offset to use for newly added rules until the next cutover is added.
      DateTimeZone toDateTimeZone​(java.lang.String id, boolean outputID)
      Processes all the rules and builds a DateTimeZone.
      void writeTo​(java.lang.String zoneID, java.io.DataOutput out)
      Encodes a built DateTimeZone to the given stream.
      void writeTo​(java.lang.String zoneID, java.io.OutputStream out)
      Encodes a built DateTimeZone to the given stream.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • DateTimeZoneBuilder

        public DateTimeZoneBuilder()

    • Method Detail

      • readFrom

        public static DateTimeZone readFrom​(java.io.InputStream in,
                                    java.lang.String id)
                             throws java.io.IOException
        Decodes a built DateTimeZone from the given stream, as encoded by writeTo.
        Parameters:
        in - input stream to read encoded DateTimeZone from.
        id - time zone id to assign
        Throws:
        java.io.IOException

      • readFrom

        public static DateTimeZone readFrom​(java.io.DataInput in,
                                    java.lang.String id)
                             throws java.io.IOException
        Decodes a built DateTimeZone from the given stream, as encoded by writeTo.
        Parameters:
        in - input stream to read encoded DateTimeZone from.
        id - time zone id to assign
        Throws:
        java.io.IOException

      • addCutover

        public DateTimeZoneBuilder addCutover​(int year,
                                      char mode,
                                      int monthOfYear,
                                      int dayOfMonth,
                                      int dayOfWeek,
                                      boolean advanceDayOfWeek,
                                      int millisOfDay)
        Adds a cutover for added rules. The standard offset at the cutover defaults to 0. Call setStandardOffset afterwards to change it.
        Parameters:
        year - the year of cutover
        mode - 'u' - cutover is measured against UTC, 'w' - against wall offset, 's' - against standard offset
        monthOfYear - the month from 1 (January) to 12 (December)
        dayOfMonth - if negative, set to ((last day of month) - ~dayOfMonth). For example, if -1, set to last day of month
        dayOfWeek - from 1 (Monday) to 7 (Sunday), if 0 then ignore
        advanceDayOfWeek - if dayOfMonth does not fall on dayOfWeek, advance to dayOfWeek when true, retreat when false.
        millisOfDay - additional precision for specifying time of day of cutover

      • setStandardOffset

        public DateTimeZoneBuilder setStandardOffset​(int standardOffset)
        Sets the standard offset to use for newly added rules until the next cutover is added.
        Parameters:
        standardOffset - the standard offset in millis

      • setFixedSavings

        public DateTimeZoneBuilder setFixedSavings​(java.lang.String nameKey,
                                           int saveMillis)
        Set a fixed savings rule at the cutover.

      • addRecurringSavings

        public DateTimeZoneBuilder addRecurringSavings​(java.lang.String nameKey,
                                               int saveMillis,
                                               int fromYear,
                                               int toYear,
                                               char mode,
                                               int monthOfYear,
                                               int dayOfMonth,
                                               int dayOfWeek,
                                               boolean advanceDayOfWeek,
                                               int millisOfDay)
        Add a recurring daylight saving time rule.
        Parameters:
        nameKey - the name key of new rule
        saveMillis - the milliseconds to add to standard offset
        fromYear - the first year that rule is in effect, MIN_VALUE indicates beginning of time
        toYear - the last year (inclusive) that rule is in effect, MAX_VALUE indicates end of time
        mode - 'u' - transitions are calculated against UTC, 'w' - transitions are calculated against wall offset, 's' - transitions are calculated against standard offset
        monthOfYear - the month from 1 (January) to 12 (December)
        dayOfMonth - if negative, set to ((last day of month) - ~dayOfMonth). For example, if -1, set to last day of month
        dayOfWeek - from 1 (Monday) to 7 (Sunday), if 0 then ignore
        advanceDayOfWeek - if dayOfMonth does not fall on dayOfWeek, advance to dayOfWeek when true, retreat when false.
        millisOfDay - additional precision for specifying time of day of transitions

      • toDateTimeZone

        public DateTimeZone toDateTimeZone​(java.lang.String id,
                                   boolean outputID)
        Processes all the rules and builds a DateTimeZone.
        Parameters:
        id - time zone id to assign
        outputID - true if the zone id should be output

      • writeTo

        public void writeTo​(java.lang.String zoneID,
                    java.io.OutputStream out)
             throws java.io.IOException
        Encodes a built DateTimeZone to the given stream. Call readFrom to decode the data into a DateTimeZone object.
        Parameters:
        out - the output stream to receive the encoded DateTimeZone
        Throws:
        java.io.IOException
        Since:
        1.5 (parameter added)

      • writeTo

        public void writeTo​(java.lang.String zoneID,
                    java.io.DataOutput out)
             throws java.io.IOException
        Encodes a built DateTimeZone to the given stream. Call readFrom to decode the data into a DateTimeZone object.
        Parameters:
        out - the output stream to receive the encoded DateTimeZone
        Throws:
        java.io.IOException
        Since:
        1.5 (parameter added)