com.randomnoun.common.jexl.DateSpan

All Implemented Interfaces:: Serializable

public class DateSpan extends Object implements Serializable

Data object representing a point in time, or a 24-hour day period.

You should probably use something in joda or the java 8 time package these days

DateSpans may be fixed, which refer to dates that do not necessarily have timezones (e.g. a valueDate, represented with the fixed date "2004-11-07" is always the 7th of November, regardless of where in the world this may be interpreted). Note that Date objects are stored internally as milliseconds since the Unix epoch UTC, and therefore do *not* qualify as 'fixed' dates. Anything that isn't fixed I refer to as 'timezoned' in the documentation here (because they only make sense when interpretted in a specific timezone).

Examples of DateSpans:

 new DateSpan("2004-11-07")          - fixed day span       (representing November 7, 2004, 24hr period))
 new DateSpan("2004-11-07T20:00:00") - fixed timestamp      (representing November 7, 2004, 8:00pm)
 new DateSpan(
   DateUtils.getStartOfDay(new Date(),
   TimeZone.getDefault()), true)     - timezoned day span   (representing today in local time (24hr period))
 new DateSpan(new Date())            - timezoned timestamp  (representing right now in local time)

Note that only yyyy-MM-dd or yyyy-MM-dd'T'HH:mm:ss (without timezone) string formats are permitted; this is more strict than that allowed by ISO8901, so I do not use that class here.

Note that timestamps are only precise down to 1 second.

'fixed' times may also be assigned default timezones, which can be used when comparing timezoned values with fixed DateSpans; e.g. the RUNDATE for Market Center "New York" may be specified as "2004-11-07" (and compared with valueDates with that same fixed date), but when compared against a SystemArrivalTime, needs to be interpretted in a time zone (in this case, TimeZone.getTimezone("America/New_York")). This can be specified at construction time, e.g.

   new DateSpan("2004-11-07", TimeZone.getTimezone("America/New_York"))

Note that if a timezone is not supplied for a 'fixed' time, then any call to getStartAsDate() or getEndAsDate() will return an IllegalStateException.

This class only supports the 'fixed day span', 'timezoned day span' or 'timezoned timestamp' examples above. Could extend this later on to 'fixed timestamp' values. Similarly, this class only supports 24hour spans, but could support more arbitrary durations if this was needed further down the track.

Only years between 1000 and 9999 will be handled correctly by this class.

Author:

knoxg

See Also:

Constructor Summary

Constructors

Constructor

Description

DateSpan(String dateSpan, TimeZone defaultTimezone)

Create a 'timezoneless' date.

DateSpan(Date timestamp)

A single timestamp instant, without timezone.

DateSpan(Date dateSpanStart, boolean isDay, TimeZone defaultTimezone)

Specify a 24-hour period, starting at point (e.g.
Method Summary
Modifier and Type

Method

Description

boolean

equals(Object obj)

Returns true if the object passed to this method as an equivalent dateSpan instance to the current object.

Date

getEndAsDate()

Returns the end of this DateSpan as a Date (milliseconds from UTC epoch).

String

getEndAsYyyymmdd()

Returns the end of this DateSpan in yyyyMMdd format (presumably for comparing against the value date column).

String

getFixed()

Gets the 'fixed' representation of this DateSpan, if the DateSpan is fixed.

Date

getStartAsDate()

Returns the start of this DateSpan as a Date (milliseconds from UTC epoch).

String

getStartAsYyyymmdd()

Returns the start of this DateSpan in yyyyMMdd format (presumably for comparing against the value date column).

boolean

isDay()

Returns true for a 24hour period.

boolean

isFixed()

Returns true for a 'fixed' DateSpan.

String

toString()

A string representation of this object, useful for debugging.

static DateSpan

valueOf(String text)

Inverse of toString(); required for

invalid reference

com.randomnoun.common.Text#parseStructOutput(String)

to do it's thing.
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details
- DateSpan
  
  public DateSpan(Date timestamp)
  
  A single timestamp instant, without timezone. Equivalent to DateSpan(Date, false, null)
- DateSpan
  
  public DateSpan(String dateSpan, TimeZone defaultTimezone)
  
  Create a 'timezoneless' date. A defaultTimezone may be supplied, which will be used when converting to Date objects.
  
  Parameters:
  
  dateSpan - A date in yyyy-MM-dd or yyyy-MM-dd'T'HH:mm:ss format (the former specifies a day period, the latter specifies a single instant
  
  defaultTimezone - A default timezone to use when converting to Date objects. This parameter may be null.
  
  Throws:
  
  NullPointerException - if the dateSpan passed to this method is null
- DateSpan
  
  public DateSpan(Date dateSpanStart, boolean isDay, TimeZone defaultTimezone)
  
  Specify a 24-hour period, starting at point (e.g. "today" spans 24 hours).
  
  Parameters:
  
  dateSpanStart - the time of this DateSpan (or the beginning, if a period)
  
  isDay - set this to true if this DateSpan represents a 24 hour day, false otherwise
  
  defaultTimezone - the timezone to interpret this date in, if we need to convert it to string form.
  
  Throws:
  
  NullPointerException - if the dateSpanStart parameter passed to this method is null
Method Details
- isFixed
  
  public boolean isFixed()
  
  Returns true for a 'fixed' DateSpan. See the class javadocs for details.
  
  Returns:
  
  true for a 'fixed' DateSpan
- isDay
  
  public boolean isDay()
  
  Returns true for a 24hour period. See the class javadocs for details
  
  Returns:
  
  true if this DateSpan represents a 24 hour period, false otherwise
- getFixed
  
  public String getFixed()
  
  Gets the 'fixed' representation of this DateSpan, if the DateSpan is fixed. This may return a day string (yyyy-MM-dd) or a day/time (yyyy-MM-dd'T'HH:mm:ss).
  
  Returns:
  
  the 'fixed' representation of this DateSpan, if the DateSpan is fixed
  
  Throws:
  
  IllegalStateException - if this DateSpan is not fixed.
- getStartAsYyyymmdd
  
  public String getStartAsYyyymmdd()
  
  Returns the start of this DateSpan in yyyyMMdd format (presumably for comparing against the value date column). If this is a timezoned DateSpan and no default timezone has been set, raises an IllegalStateException
  
  Returns:
  
  the start of this DateSpan in yyyyMMdd format
  
  Throws:
  
  IllegalStateException - if no defaultTimezone has been specified for a timezoned DateSpan
- getStartAsDate
  
  public Date getStartAsDate()
  
  Returns the start of this DateSpan as a Date (milliseconds from UTC epoch). If this is a fixed DateSpan and no default timezone has been set, raises an IllegalStateException
  
  Returns:
  
  the start of this DateSpan as a Date
  
  Throws:
  
  IllegalStateException - if no defaultTimezone has been specified for a fixed DateSpan
- getEndAsYyyymmdd
  
  public String getEndAsYyyymmdd()
  
  Returns the end of this DateSpan in yyyyMMdd format (presumably for comparing against the value date column). If this is a timezoned DateSpan and no default timezone has been set, raises an IllegalStateException
  
  Returns:
  
  the end of this DateSpan in yyyyMMdd format
  
  Throws:
  
  IllegalStateException - if this DateSpan represents a point in time (not a duration), or if no defaultTimezone has been specified for a timezoned DateSpan
- getEndAsDate
  
  public Date getEndAsDate()
  
  Returns the end of this DateSpan as a Date (milliseconds from UTC epoch). If this is a fixed DateSpan and no default timezone has been set, raises an IllegalStateException
  
  Returns:
  
  the end of this DateSpan as a Date
  
  Throws:
  
  IllegalStateException - if no defaultTimezone has been specified for a fixed DateSpan
- toString
  
  public String toString()
  
  A string representation of this object, useful for debugging.
  
  Overrides:
  
  toString in class Object
  
  Returns:
  
  a string representation of this object, useful for debugging.
- valueOf
  
  public static DateSpan valueOf(String text) throws ParseException
  Inverse of toString(); required for
  
  invalid reference
  
  com.randomnoun.common.Text#parseStructOutput(String)
  
  to do it's thing.
  Parameters:
  
  string - The text representation of this object (as returned by .toString())
  
  Returns:
  
  an instance of a DateSpan
  
  Throws:
  
  ParseException
- equals
  
  public boolean equals(Object obj)
  
  Returns true if the object passed to this method as an equivalent dateSpan instance to the current object. (Used in unit testing only)
  
  Overrides:
  
  equals in class Object
  
  Parameters:
  
  other - the object we are comparing agianst
  
  Returns:
  
  true if the other object is identical to this one, false otherwise

Class DateSpan

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Details

DateSpan

DateSpan

DateSpan

Method Details

isFixed

isDay

getFixed

getStartAsYyyymmdd

getStartAsDate

getEndAsYyyymmdd

getEndAsDate

toString

valueOf

equals