Class DateTimeZoneBuilder

java.lang.Object
org.joda.time.tz.DateTimeZoneBuilder

public class DateTimeZoneBuilder extends 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
Author:
Brian S O'Neill
See Also:
  • Constructor Details

    • DateTimeZoneBuilder

      public DateTimeZoneBuilder()
  • Method Details

    • readFrom

      public static DateTimeZone readFrom(InputStream in, String id) throws 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:
      IOException
    • readFrom

      public static DateTimeZone readFrom(DataInput in, String id) throws 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:
      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(String nameKey, int saveMillis)
      Set a fixed savings rule at the cutover.
    • addRecurringSavings

      public DateTimeZoneBuilder addRecurringSavings(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(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(String zoneID, OutputStream out) throws 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:
      IOException
      Since:
      1.5 (parameter added)
    • writeTo

      public void writeTo(String zoneID, DataOutput out) throws 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:
      IOException
      Since:
      1.5 (parameter added)