org.opensha.commons.data
Class TimeSpan

java.lang.Object
  extended by org.opensha.commons.data.TimeSpan
All Implemented Interfaces:
java.io.Serializable, java.util.EventListener, ParameterChangeListener

public class TimeSpan
extends java.lang.Object
implements ParameterChangeListener, java.io.Serializable

Title: TimeSpan

Description: This object represents a start time and a duration in the UTC time zone.

The start-time is represented with a Year, Month, Day, Hour, Minute, Second, and Millisecond, all of which are stored internally with IntegerParameter objects. The default constraints (range of allowed values) for these parameters are:

Important Notes: 1) the Month parameter constraint here (min=1, max=12) differs from the 0-11 range in the java.util.GregorianCalendar object. This means that what's returned from the getStartTimeMonth() method is always one greater than what's obtained using getStartTimeCalendar().get(Calendar.MONTH)). Keep this in mind if you use the setStartTimeCalendar(), getStartTimeCalendar(), or getEndTimeCalendar methods. 2) the Day and Hour fields here correspond to the DATE and HOUR_OF_DAY fields, respecively in java.util.GregorianCalendar (the HOUR field of GregorianCalendar goes from 0 to 11 rather than 0 to 23).

The above start-time parameter constraints can be overridden using the setStartTimeConstraint() method. The startTimePrecision field specifies the level of precision. For example, if this is set as "Days", then one cannot set or get the Hours, Minute, Second, or Millisecond parameter values (and the associated methods throw exceptions). Setting the startTimePrecsion as "None" indicates that only the Duration is relevant (e.g., for a Poissonian forecast). Presently one can only set the startTimePrecision in the constructor, but we could relax this later. If one gets a GregorianCalendar using the getStartTimeCalendar() method, the fields that are not within the specified precision are set to their minimum value.

Before a value is returned from any one of the getStartTime*() methods, it is first confirmed that the start-time parameter settings correspond to an acutual date. For example, assuming the startTimePrecision is "Months", one could execute the method: setStartTime(2003,2,29). However, when they go to get one of these fields (e.g., getStartYear() or getStartMonth()) an exception will be thrown because there are not 29 days in Feburary (unless it's a leap year). This check is made in the get* rather than set* methods to allow users to finish their settings (e.g., in a GUI) before checking values. The Units on the Duration field must presently be set in the constructor, (this could be relaxed later). These Units are assumed when using the getDuration() and setDuration(double duration) methods. If one wishes to get or set the duration with other units (e.g., to avoid having to check what the internal units are), they can use the setDuration(String units, double duration) and getDuration(String units, double duration) methods, but note that the internal "chosen" units will not have changed. The constraints on the units can be set using the setDurationConstraint() method. NOTE: in converting between duration units it is assumed there are 365.25 days per year (correct only for durations in years that are an integer when divided by four). This limitation can be fixed, but will require some thought.

Finally, one can get an end-time calendar object that corresponds to the start time plus the duration (getEndTimeCalendar()). Note, that because this invoves a duration unit conversion, it is assumed that there are 365.25 days per year (see discussion above).

TO DO LATER:

Make the Duration units adjustable after construction. This could be done by allowing an "Adjustable" opting for the duration units in the constructor. For this case, make the units field of the durationParameter empty, and use the value set in the durationUnitsParameter for the getDuration() and setDuration() methods. Also add durationUnitsParameter to the list returned by the getAdjustableParamsList(). This raises the question of how non-default constraints can be applied if the user is changing the units (perhaps only default constraints can be applied in this case). Care will be required in using the getDuration() and setDuration() methods if other objects can change the units (perhaps these should throw and non-usable exception).

We might need a setNonEditable() method here (e.g., to prevent ouside entities from changing constraints).

Version:
1.0
Author:
Edward Field, based on an earlier version by Sid Hellman and Steven W. Rock.
See Also:
Serialized Form

Field Summary
protected static java.lang.String C
          The name of this class, used for debug statements
protected static boolean D
          Static boolean whether to print out debugging statements
static java.lang.String DAYS
           
static java.lang.String DURATION
           
static java.lang.String HOURS
           
static java.lang.String MILLISECONDS
           
static java.lang.String MINUTES
           
static java.lang.String MONTHS
           
static java.lang.String NONE
           
static java.lang.String SECONDS
           
static java.lang.String START_DAY
           
static java.lang.String START_HOUR
           
static java.lang.String START_MILLISECOND
           
static java.lang.String START_MINUTE
           
static java.lang.String START_MONTH
           
static java.lang.String START_SECOND
           
static java.lang.String START_TIME_PRECISION
           
static java.lang.String START_YEAR
           
protected  java.util.GregorianCalendar startTimeCal
           
static java.lang.String XML_METADATA_NAME
           
static java.lang.String YEARS
           
 
Constructor Summary
TimeSpan(java.lang.String startTimePrecision, java.lang.String durationUnits)
          Constructor
 
Method Summary
 void addParameterChangeListener(TimeSpanChangeListener listener)
          This method will be used by ERFs to listen for changes in Timespan object
static TimeSpan fromXMLMetadata(Element el)
           
 ParameterList getAdjustableParams()
          This returns a ParameterList (e.g., to put in a GUI so users can set values).
 double getDuration()
          Gets the duration in the default (internally specified) units
 double getDuration(java.lang.String units)
          This returns the duration in the units specified (it leaves the units specified internally unchanged).
 java.lang.String getDurationUnits()
          Gets the units for the duration
 java.util.GregorianCalendar getEndTimeCalendar()
          This returns an end-time GregorianCalendar representing the start time plus the duration.
 java.util.GregorianCalendar getStartTimeCalendar()
          This returns a GregorianCalendar representation of the start-time fields in the "UTC" time zone.
 int getStartTimeDay()
           
 int getStartTimeFromType(java.lang.String type)
           
 int getStartTimeHour()
           
 long getStartTimeInMillis()
          This returns the start time in milliseconds in the "UTC" time zone.
 int getStartTimeMillisecond()
           
 int getStartTimeMinute()
           
 int getStartTimeMonth()
          Note that our indexing on Month goes from 1 to 12, whereas that for the GregorianCalendar.MONTH goes from 0 to 11.
 java.lang.String getStartTimePrecision()
          This returns the Start-Time Precision String
 int getStartTimeSecond()
           
 int getStartTimeYear()
           
 void parameterChange(ParameterChangeEvent e)
          this function is called whenenver any parameter changes in the params list This function then notifies all the listeners about this change
 void setDuractionConstraint(double min, double max)
          This puts a new constraint on the duration parameter, although the new min and max must be within the default values (0 and Double.MAX_VALUE, respectively).
 void setDuration(double duration)
          This sets the duration assuming the previously set units.
 void setDuration(double duration, java.lang.String units)
          This sets the duration from the units specified.
 void setDurationConstraint(java.util.ArrayList<java.lang.Double> doubles)
          This puts a new discrete constraint (list of doubles) on the duration parameter.
 void setStartTime(java.util.GregorianCalendar cal)
          This sets the start-time fields (year, month, day, hour, minute, second, and millisecond) from the input GregorianCalendar.
 void setStartTime(int year)
          Sets the start time if start-time precision = "Years".
 void setStartTime(int year, int month)
          Sets the start time if start-time precision = "Months".
 void setStartTime(int year, int month, int day)
          Sets the start time if start-time precision = "Days".
 void setStartTime(int year, int month, int day, int hour)
          Sets the start time if start-time precision = "Hours".
 void setStartTime(int year, int month, int day, int hour, int minute)
          Sets the start time if start-time precision = "Minutes".
 void setStartTime(int year, int month, int day, int hour, int minute, int second)
          Sets the start time if start-time precision = "Seconds".
 void setStartTime(int year, int month, int day, int hour, int minute, int second, int millisecond)
          Sets the start time if start-time precision = "Milliseconds".
 void setStartTimeConstraint(java.lang.String name, int min, int max)
          This method allows one to override the default constraints for any of the start-time parameters.
 void setStartTimeInMillis(long millis)
          This sets the start time from milliseconds (which should be given in the "UTC" time zone).
 Element toXMLMetadata(Element root)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

C

protected static final java.lang.String C
The name of this class, used for debug statements

See Also:
Constant Field Values

XML_METADATA_NAME

public static final java.lang.String XML_METADATA_NAME
See Also:
Constant Field Values

D

protected static final boolean D
Static boolean whether to print out debugging statements

See Also:
Constant Field Values

startTimeCal

protected java.util.GregorianCalendar startTimeCal

START_YEAR

public static final java.lang.String START_YEAR
See Also:
Constant Field Values

START_MONTH

public static final java.lang.String START_MONTH
See Also:
Constant Field Values

START_DAY

public static final java.lang.String START_DAY
See Also:
Constant Field Values

START_HOUR

public static final java.lang.String START_HOUR
See Also:
Constant Field Values

START_MINUTE

public static final java.lang.String START_MINUTE
See Also:
Constant Field Values

START_SECOND

public static final java.lang.String START_SECOND
See Also:
Constant Field Values

START_MILLISECOND

public static final java.lang.String START_MILLISECOND
See Also:
Constant Field Values

YEARS

public static final java.lang.String YEARS
See Also:
Constant Field Values

MONTHS

public static final java.lang.String MONTHS
See Also:
Constant Field Values

DAYS

public static final java.lang.String DAYS
See Also:
Constant Field Values

HOURS

public static final java.lang.String HOURS
See Also:
Constant Field Values

MINUTES

public static final java.lang.String MINUTES
See Also:
Constant Field Values

SECONDS

public static final java.lang.String SECONDS
See Also:
Constant Field Values

MILLISECONDS

public static final java.lang.String MILLISECONDS
See Also:
Constant Field Values

NONE

public static final java.lang.String NONE
See Also:
Constant Field Values

DURATION

public static final java.lang.String DURATION
See Also:
Constant Field Values

START_TIME_PRECISION

public static final java.lang.String START_TIME_PRECISION
See Also:
Constant Field Values
Constructor Detail

TimeSpan

public TimeSpan(java.lang.String startTimePrecision,
                java.lang.String durationUnits)
Constructor

Parameters:
startTimePrecision -
durationUnits -
Method Detail

setStartTimeConstraint

public void setStartTimeConstraint(java.lang.String name,
                                   int min,
                                   int max)
This method allows one to override the default constraints for any of the start-time parameters. The name options (start-time parameter names) are: "Start Year", "Start Month", "Start Day", "Start Hour", "Start Minute", "Start Second", or "Start Millisecond". Note that you cannot set the min and max outside the default bounds (e.g., min and max for "Start Hour" must be between 0 and 23). Note also that this method ignores the start-time precision (e.g., you can set new constraints on "Start Minute" even if the start-time precision has been set as "Years").

Parameters:
name - - the name of the start-time parameter
min - - the new minimum
max - - the new maximum

getStartTimePrecision

public java.lang.String getStartTimePrecision()
This returns the Start-Time Precision String

Returns:

getStartTimeFromType

public int getStartTimeFromType(java.lang.String type)

getStartTimeYear

public int getStartTimeYear()
                     throws java.lang.RuntimeException
Returns:
Start-time year
Throws:
java.lang.RuntimeException - if year is not within the start-time precision.

getStartTimeMonth

public int getStartTimeMonth()
                      throws java.lang.RuntimeException
Note that our indexing on Month goes from 1 to 12, whereas that for the GregorianCalendar.MONTH goes from 0 to 11.

Returns:
Start-time month
Throws:
java.lang.RuntimeException - if month is not within the start-time precision.

getStartTimeDay

public int getStartTimeDay()
                    throws java.lang.RuntimeException
Returns:
Start-time day
Throws:
java.lang.RuntimeException - if day is not within the start-time precision.

getStartTimeHour

public int getStartTimeHour()
                     throws java.lang.RuntimeException
Returns:
Start-time hour
Throws:
java.lang.RuntimeException - if hour is not within the start-time precision.

getStartTimeMinute

public int getStartTimeMinute()
                       throws java.lang.RuntimeException
Returns:
Start-time minute
Throws:
java.lang.RuntimeException - if minute is not within the start-time precision.

getStartTimeSecond

public int getStartTimeSecond()
                       throws java.lang.RuntimeException
Returns:
Start-time second
Throws:
java.lang.RuntimeException - if second is not within the start-time precision.

getStartTimeMillisecond

public int getStartTimeMillisecond()
                            throws java.lang.RuntimeException
Returns:
Start-time millisecond
Throws:
java.lang.RuntimeException - if millisecond is not within the start-time precision.

getDurationUnits

public java.lang.String getDurationUnits()
Gets the units for the duration

Returns:

setDuration

public void setDuration(double duration)
This sets the duration assuming the previously set units.

Parameters:
duration -

setDuration

public void setDuration(double duration,
                        java.lang.String units)
This sets the duration from the units specified. Duration-unit options are "Years", "Days","Hours", "Minutes", "Seconds", or "Milliseconds". This does not change the "chosen" units held internally.

Parameters:
duration - - in the units supplied
units - - the units of the passed in duration

setDuractionConstraint

public void setDuractionConstraint(double min,
                                   double max)
This puts a new constraint on the duration parameter, although the new min and max must be within the default values (0 and Double.MAX_VALUE, respectively).

Parameters:
min - - new minimum
max - - new maximum

setDurationConstraint

public void setDurationConstraint(java.util.ArrayList<java.lang.Double> doubles)
This puts a new discrete constraint (list of doubles) on the duration parameter. All the new values must be within the default values (0 and Double.MAX_VALUE, respectively).

Parameters:
doubles - - a vector of doubles

getDuration

public double getDuration()
Gets the duration in the default (internally specified) units

Returns:

getDuration

public double getDuration(java.lang.String units)
This returns the duration in the units specified (it leaves the units specified internally unchanged). Duration-unit options are "Years", "Days","Hours", "Minutes", "Seconds", or "Milliseconds".

Parameters:
units - - the desired units
Returns:

setStartTime

public void setStartTime(int year)
                  throws java.lang.RuntimeException
Sets the start time if start-time precision = "Years".

Parameters:
year -
Throws:
java.lang.RuntimeException - if start-time precision is not "Years"

setStartTime

public void setStartTime(int year,
                         int month)
                  throws java.lang.RuntimeException
Sets the start time if start-time precision = "Months".

Throws:
java.lang.RuntimeException - if start-time precision is not "Months"

setStartTime

public void setStartTime(int year,
                         int month,
                         int day)
                  throws java.lang.RuntimeException
Sets the start time if start-time precision = "Days".

Throws:
java.lang.RuntimeException - if start-time precision is not "Days"

setStartTime

public void setStartTime(int year,
                         int month,
                         int day,
                         int hour)
                  throws java.lang.RuntimeException
Sets the start time if start-time precision = "Hours".

Throws:
java.lang.RuntimeException - if start-time precision is not "Hours"

setStartTime

public void setStartTime(int year,
                         int month,
                         int day,
                         int hour,
                         int minute)
                  throws java.lang.RuntimeException
Sets the start time if start-time precision = "Minutes".

Throws:
java.lang.RuntimeException - if start-time precision is not "Minutes"

setStartTime

public void setStartTime(int year,
                         int month,
                         int day,
                         int hour,
                         int minute,
                         int second)
                  throws java.lang.RuntimeException
Sets the start time if start-time precision = "Seconds".

Throws:
java.lang.RuntimeException - if start-time precision is not "Seconds"

setStartTime

public void setStartTime(int year,
                         int month,
                         int day,
                         int hour,
                         int minute,
                         int second,
                         int millisecond)
                  throws java.lang.RuntimeException
Sets the start time if start-time precision = "Milliseconds".

Throws:
java.lang.RuntimeException - if start-time precision is not "Milliseconds"

setStartTime

public void setStartTime(java.util.GregorianCalendar cal)
This sets the start-time fields (year, month, day, hour, minute, second, and millisecond) from the input GregorianCalendar. Fields above the start-time precision are ignored. For example, if the start- time precision equals "Hour", then the year, month, day, and hour are set, but the minute, second, and millisecond fields are not. If start- time precision equals "None", then none of the fields are filled in. An exception is throw if the calendar is not in the UTC time zone.

Parameters:
cal -

getEndTimeCalendar

public java.util.GregorianCalendar getEndTimeCalendar()
This returns an end-time GregorianCalendar representing the start time plus the duration. Note that this correctly accounts for leap years (and leap seconds?) thanks to the sophistication of the java.util.GregorianCalendar object. Note also the indexing difference for the Month field (our parameter goes from 1 to 12, whereas GregorianCalendar.MONTH goes from 0 to 11).


getAdjustableParams

public ParameterList getAdjustableParams()
This returns a ParameterList (e.g., to put in a GUI so users can set values). This only includes start-time parameters that are within the chosen precision.

Returns:

getStartTimeCalendar

public java.util.GregorianCalendar getStartTimeCalendar()
                                                 throws java.lang.RuntimeException
This returns a GregorianCalendar representation of the start-time fields in the "UTC" time zone. Those fields above the start-time precision are set to their defaults (generally the lowest possible value). For example, if start-time precision equals "Day", then the HOUR_OF_DAY, MINUTE, SECOND, and MILLISECOND fields of the returned GregorianCalendar are all set to 0. Note also the indexing difference for the Month field (our parameter goes from 1 to 12, whereas GregorianCalendar.MONTH goes from 0 to 11).

Returns:
Throws:
java.lang.Exception
java.lang.RuntimeException

getStartTimeInMillis

public long getStartTimeInMillis()
This returns the start time in milliseconds in the "UTC" time zone.

Returns:

setStartTimeInMillis

public void setStartTimeInMillis(long millis)
This sets the start time from milliseconds (which should be given in the "UTC" time zone).


addParameterChangeListener

public void addParameterChangeListener(TimeSpanChangeListener listener)
This method will be used by ERFs to listen for changes in Timespan object

Parameters:
listener - : Object that wants to listen to changes in Timespan object listener must implement the TimeSpanChangeListener interface

parameterChange

public void parameterChange(ParameterChangeEvent e)
this function is called whenenver any parameter changes in the params list This function then notifies all the listeners about this change

Specified by:
parameterChange in interface ParameterChangeListener
Parameters:
e -

toXMLMetadata

public Element toXMLMetadata(Element root)

fromXMLMetadata

public static TimeSpan fromXMLMetadata(Element el)