gov.noaa.pfel.erddap.util

Class Calendar2

java.lang.Object

gov.noaa.pfel.erddap.util.Calendar2

public class Calendar2
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).

Field Summary

Fields

Modifier and Type	Field and Description
static int	MILLISECOND
static int	SECONDS_PER_DAY
static int	SECONDS_PER_HOUR
static int	SECONDS_PER_MINUTE
static int	YEAR
static TimeZone	zuluTimeZone

Constructor Summary

Constructors

Constructor and Description
Calendar2()

Method Summary

Methods

Modifier and Type	Method and Description
static double	factorToGetSeconds(String units) This returns the factor to multiply by 'units' data to get seconds data (e.g., "minutes" returns 60).
static double[]	getTimeBaseAndFactor(String tsUnits) 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).
static GregorianCalendar	newGCalendarZulu() Get a GregorianCalendar object with the current UTC (A.K.A., GMT or Zulu) time and a UTC time zone.
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.
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.

Methods inherited from class java.lang.Object

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

Field Detail

YEAR

public static final int YEAR

See Also:

Constant Field Values

MILLISECOND

public static final int MILLISECOND

See Also:

Constant Field Values

SECONDS_PER_MINUTE

public static final int SECONDS_PER_MINUTE

See Also:

Constant Field Values

SECONDS_PER_HOUR

public static final int SECONDS_PER_HOUR

See Also:

Constant Field Values

SECONDS_PER_DAY

public static final int SECONDS_PER_DAY

See Also:

Constant Field Values

zuluTimeZone

public static final TimeZone zuluTimeZone

Constructor Detail

Calendar2

public Calendar2()

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