Package ucar.nc2.ogc.erddap.util

Class ErddapCalendar2

  • public class ErddapCalendar2
extends Object
    This class has static methods for dealing with dates and times.

    newGCalendar only accounts for daylight savings if your computer is correctly set up. E.g., in Windows, make sure "Start : Control Panel : Date and Time : Time Zone : Automatically adjust clock for daylight savings changes" is checked. Otherwise, the TimeZone used by GregorianCalendar will be for standard time (not including daylight savings time, if any).

    Comments about working with Java's GregorianCalendar class:

    • GregorianCalendar holds millis since Jan 1, 1970 and a timeZone which influences the values that get/set deal with.
    • Using a simpleDateFormat to parse a string to a Gregorian Calendar: the simpleDateFormat has a timeZone which specified where the the strings value is from (e.g., 2005-10-31T15:12:10 in PST). When parsed, it is then interpreted by the GregorianCalendar's timeZone (e.g., it was 3pm PST but now I'll treat it as 6pm EST).
    • Similarly, using a simpleDateFormat to format a Gregorian Calendar to a String: the simpleDateFormat has a timeZone which specified where the the strings value will be for (e.g., 6pm EST will be formatted as 5pm Central).

    But this class seeks to simplify things to the more common cases of parsing and formatting using the same time zone as the GregorianCalendar class, and offering GregorianCalendar constructors for Local (with daylight savings if that is what your area does) and Zulu (aka GMT and UTC, which doesn't ever use daylight savings).

    A summary of ISO 8601 Date Time formats is at http://www.cl.cam.ac.uk/~mgk25/iso-time.html http://en.wikipedia.org/wiki/ISO_8601 and http://dotat.at/tmp/ISO_8601-2004_E.pdf (was http://www.iso.org/iso/date_and_time_format) and years B.C at http://www.tondering.dk/claus/cal/node4.html#SECTION00450000000000000000

    Calendar2 does not use ERA designations. It uses negative year values for B.C years (calendar2Year = 1 - BCYear). Note that BCYears are 1..., so 1 BC is calendar2Year 0 (or 0000), and 2 BC is calendar2Year -1 (or -0001).

    • Constructor Detail

      • ErddapCalendar2

        public ErddapCalendar2()

    • Method Detail

      • getTimeBaseAndFactor

        public static double[] getTimeBaseAndFactor​(String tsUnits)
                                     throws Exception
        This converts a string "[units] since [isoDate]" (e.g., "minutes since 1985-01-01") into a baseSeconds (seconds since 1970-01-01) and a factor ("minutes" returns 60).
        So simplistically, epochSeconds = storedTime * factor + baseSeconds.
        Or simplistically, storedTime = (epochSeconds - baseSeconds) / factor.

        WARNING: don't use the equations above. Use unitsSinceToEpochSeconds or epochSecondsToUnitsSince which correctly handle special cases.

        Parameters:
        tsUnits - e.g., "minutes since 1985-01-01". This may include hours, minutes, seconds, decimal, and Z or timezone offset (default=Zulu).
        Returns:
        double[]{baseSeconds, factorToGetSeconds}
        Throws:
        Exception - if trouble (tsUnits is null or invalid)

      • factorToGetSeconds

        public static double factorToGetSeconds​(String units)
                                 throws Exception
        This returns the factor to multiply by 'units' data to get seconds data (e.g., "minutes" returns 60). This is used for part of dealing with udunits-style "minutes since 1970-01-01"-style strings.
        Parameters:
        units -
        Returns:
        the factor to multiply by 'units' data to get seconds data. Since there is no exact value for months or years, this returns special values of 30*SECONDS_PER_DAY and 360*SECONDS_PER_DAY, respectively.
        Throws:
        Exception - if trouble (e.g., units is null or not an expected value)

      • newGCalendarZulu

        public static GregorianCalendar newGCalendarZulu()
        Get a GregorianCalendar object with the current UTC (A.K.A., GMT or Zulu) time and a UTC time zone. You can find the current Zulu/GMT time at: http://www.xav.com/time.cgi Info about UTC vs GMT vs TAI... see http://www.leapsecond.com/java/gpsclock.htm. And there was another good site... can't find it.
        Returns:
        the GregorianCalendar object for right now (Zulu time zone)

      • parseISODateTime

        public static GregorianCalendar parseISODateTime​(GregorianCalendar gc,
                                                 String s)
        This converts an ISO date time string ([-]YYYY-MM-DDTHH:MM:SS.SSS±ZZ:ZZ) into a GregorianCalendar object.
        It is lenient; so Jan 32 is converted to Feb 1;
        The 'T' may be any non-digit.
        The time zone can be omitted.
        The parts at the end of the time can be omitted.
        If there is no time, the end parts of the date can be omitted. Year is required.
        This tries hard to be tolerant of non-valid formats (e.g., "1971-1-2", "1971-01")
        As of 11/9/2006, NO LONGER TRUE: If year is 0..49, it is assumed to be 2000..2049.
        As of 11/9/2006, NO LONGER TRUE: If year is 50..99, it is assumed to be 1950..1999.
        If the string is too short, the end of "1970-01-01T00:00:00.000Z" will be added (effectively).
        If the string is too long, the excess will be ignored.
        If a required separator is incorrect, it is an error.
        If the date is improperly formatted, it returns null.
        Timezone "Z" or "" is treated as "-00:00" (UTC/Zulu time)
        Timezones: e.g., 2007-01-02T03:04:05-01:00 is same as 2007-01-02T04:04:05
        Parameters:
        gc - a GregorianCalendar object. The dateTime will be interpreted as being in gc's time zone. Timezone info is relative to the gc's time zone.
        s - the dateTimeString in the ISO format (YYYY-MM-DDTHH:MM:SS.SSS±ZZ:ZZ or -YYYY-MM-DDTHH:MM:SS.SSS±ZZ:ZZ for years B.C.) For years B.C., use calendar2Year = 1 - BCYear. Note that BCYears are 1..., so 1 BC is calendar2Year 0 (or 0000), and 2 BC is calendar2Year -1 (or -0001). This supports SS.SSS and SS,SSS (which ISO 8601 prefers!).
        Returns:
        the same GregorianCalendar object, but with the date info
        Throws:
        RuntimeException - if trouble (e.g., gc is null or s is null or not at least #)

      • parseISODateTimeZulu

        public static GregorianCalendar parseISODateTimeZulu​(String s)
        This converts an ISO (default *ZULU* time zone) date time string ([-]YYYY-MM-DDTHH:MM:SS±ZZ:ZZ) into a GregorianCalendar object with the Zulu time zone. See parseISODateTime documentation.
        Parameters:
        s - the dateTimeString in the ISO format ([-]YYYY-MM-DDTHH:MM:SS) This may include hours, minutes, seconds, decimal, and Z or timezone offset (default=Zulu).
        Returns:
        a GregorianCalendar object