Package org.joda.time.tz

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
See Also:

  • Field Details

  • 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

    • writeMillis

      static void writeMillis(DataOutput out, long millis) throws IOException
      Millisecond encoding formats: upper two bits units field length approximate range --------------------------------------------------------------- 00 30 minutes 1 byte +/- 16 hours 01 minutes 4 bytes +/- 1020 years 10 seconds 5 bytes +/- 4355 years 11 millis 9 bytes +/- 292,000,000 years Remaining bits in field form signed offset from 1970-01-01T00:00:00Z.
      Throws:
      IOException

    • readMillis

      static long readMillis(DataInput in) throws IOException
      Reads encoding generated by writeMillis.
      Throws:
      IOException

    • buildFixedZone

      private static DateTimeZone buildFixedZone(String id, String nameKey, int wallOffset, int standardOffset)

    • 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

    • getLastRuleSet

      private DateTimeZoneBuilder.RuleSet getLastRuleSet()

    • 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

    • addTransition

      private boolean addTransition(ArrayList<DateTimeZoneBuilder.Transition> transitions, DateTimeZoneBuilder.Transition tr)

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