net.degreedays.api.data
Class DatedDataSet

java.lang.Object
  extended by net.degreedays.api.data.DataSet
      extended by net.degreedays.api.data.DatedDataSet
All Implemented Interfaces:
java.io.Serializable

public final class DatedDataSet
extends DataSet
implements java.io.Serializable

Contains a set of dated data (e.g. daily/weekly/monthly degree days) generated to fulfil a DatedDataSpec for a specific Location.

See Also:
AverageDataSet

Instances of this class are immutable. You can safely reuse them and call them from multiple threads at once.


Nested Class Summary
static class DatedDataSet.Builder
          A builder class for creating immutable DatedDataSet objects e.g. for testing purposes.
 
Method Summary
 boolean equals(java.lang.Object o)
          Returns true if o is a DatedDataSet containing equal values covering equal dates, and with an equal percentageEstimated().
 DayRange fullRange()
          Returns a non-null DayRange object indicating the period of time that is covered by this DatedDataSet's values.
 DatedDataValue[] getValues()
          Returns an array of the DatedDataValue objects that make up this DatedDataSet.
 int hashCode()
          Overridden to ensure consistency with equals.
 boolean isDailyData()
          Returns true if each of the values contained within this DatedDataSet covers one day.
 boolean isMonthlyData()
          Returns true if each of the values contained within this DatedDataSet covers one month.
 boolean isWeeklyData()
          Returns true if each of the values contained within this DatedDataSet covers one week.
 boolean isYearlyData()
          Returns true if each of the values contained within this DatedDataSet covers one year.
 double percentageEstimated()
          Returns a number between 0 and 100 (both inclusive), indicating the overall extent to which this DataSet is based on estimated data.
 java.lang.String toString()
          Returns a non-null, non-empty string representation of this object for logging and debugging purposes.
 AverageDataSet transformToAverage(AverageBreakdown targetBreakdown)
          Returns a new AverageDataSet object, based on the data contained within this, but transformed to fit the targetBreakdown.
 DatedDataSet transformToDated(DatedBreakdown targetBreakdown)
          Returns a new DatedDataSet object, based on the data contained within this, but transformed to fit the targetBreakdown.
 DatedDataValue valueAt(int index)
          Returns the DatedDataValue at the specified index, which must be between 0 (inclusive) and valueCount() (exclusive).
 int valueCount()
          Returns the number of values held by this DatedDataSet object, which will always be greater than zero.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

percentageEstimated

public double percentageEstimated()
Description copied from class: DataSet
Returns a number between 0 and 100 (both inclusive), indicating the overall extent to which this DataSet is based on estimated data.

Generally speaking, data with a lower percentage-estimated figure is likely to be more reliable than data with a higher percentage-estimated figure.

Specified by:
percentageEstimated in class DataSet

valueCount

public int valueCount()
Returns the number of values held by this DatedDataSet object, which will always be greater than zero.

See Also:
valueAt(int), getValues()

valueAt

public DatedDataValue valueAt(int index)
Returns the DatedDataValue at the specified index, which must be between 0 (inclusive) and valueCount() (exclusive).

Parameters:
index - a number, greater than or equal to zero, and less than valueCount() indicating which value should be returned. Values are stored in consecutive order, so a greater index means a later value.
Throws:
java.lang.IndexOutOfBoundsException - if index is less than zero or greater than or equal to valueCount().
See Also:
getValues()

getValues

public DatedDataValue[] getValues()
Returns an array of the DatedDataValue objects that make up this DatedDataSet.

The returned array can be modified freely without affecting the immutability of this DatedDataSet or the arrays returned by past, concurrent, or future calls to this method. This is possible because a new array is generated with each call to this method. Bear this in mind if you're iterating over all the values... The following example is fine, as getValues() is only called once:

 // This is fine:
 for (DatedDataValue v : dataSet.getValues()) {
     // Do something with v.
 }
 
 // as is this:
 DatedDataValue[] values = dataSet.getValues();
 for (int i = 0; i < values.length; i++) {
     DatedDataValue v = values[i];
     // Do something with v.
 }
 

But you definitely don't want to do something like:

 // Don't do it like this!
 for (int i = 0; i < dataSet.getValues().length; i++) {
     DatedDataValue v = dataSet.getValues()[i];
     // Do something with v.
 }
 

In the bad example immediately above, two fresh arrays are created for each iteration of the loop. Looping over the values like this would be very bad for performance, particularly if this set contains daily data with thousands of values.

See Also:
valueAt(int), valueCount()

fullRange

public DayRange fullRange()
Returns a non-null DayRange object indicating the period of time that is covered by this DatedDataSet's values.

Specified by:
fullRange in class DataSet

isDailyData

public boolean isDailyData()
Returns true if each of the values contained within this DatedDataSet covers one day.

Note that a DatedDataSet will always hold contiguous dated values, so daily data means an ordered run of consecutive days.


isWeeklyData

public boolean isWeeklyData()
Returns true if each of the values contained within this DatedDataSet covers one week. Weekly data can have any DayOfWeek as the first day of the week, so long as it's consistent.

Note that a DatedDataSet will always hold contiguous dated values, so weekly data means an ordered run of consecutive weeks.


isMonthlyData

public boolean isMonthlyData()
Returns true if each of the values contained within this DatedDataSet covers one month. Monthly data can have any StartOfMonth, so long as it's consistent.

Note that a DatedDataSet will always hold contiguous dated values, so monthly data means an ordered run of consecutive months.


isYearlyData

public boolean isYearlyData()
Returns true if each of the values contained within this DatedDataSet covers one year. Yearly data can have any StartOfYear, so long as it's consistent.

Note that a DatedDataSet will always hold contiguous dated values, so yearly data means an ordered run of consecutive years.


transformToAverage

public AverageDataSet transformToAverage(AverageBreakdown targetBreakdown)
                                  throws DataTransformException
Returns a new AverageDataSet object, based on the data contained within this, but transformed to fit the targetBreakdown.

If targetBreakdown cannot be satisfied fully using the data contained within this, this method will return a partial set of data if it can. For example, if your target is a 5-year average breakdown, but this only covers 3 full years, then assuming those 3 full years overlap with the target, this method will return a 3-year average data set. But many sorts of transformations just aren't possible... For example, you can't turn weekly or yearly data into an average data set. Not without losing accuracy anyway, which this method will not do.

This method will work on daily or monthly data (provided the months in the monthly data start on the first of the month).

Be prepared for a DataTransformException if you have any doubt about whether it will be possible to get the breakdown you want from the data you have.

Parameters:
targetBreakdown - a non-null object that specifies the breakdown that the returned data should have.
Returns:
a new AverageDataSet with the targetBreakdown.
Throws:
DataTransformException - if the method is unable to transform the data contained within this into data with the targetBreakdown.
java.lang.NullPointerException - if targetBreakdown is null.

transformToDated

public DatedDataSet transformToDated(DatedBreakdown targetBreakdown)
                              throws DataTransformException
Returns a new DatedDataSet object, based on the data contained within this, but transformed to fit the targetBreakdown.

If targetBreakdown cannot be satisfied fully using the data contained within this, this method will return a partial set of data if it can. For example, if your target breakdown is a WeeklyBreakdown with a Period that is longer than that covered by this, then, assuming there is overlap, this method will return weekly data covering as much of the period as it can. But many sorts of transformations just aren't possible - for example, a data set covering only 2009 can never be transformed into a data set covering 2010, and monthly data can never be turned into daily data. Not without losing accuracy anyway, which this method will not do.

This method is generally best called on sets of daily data. Daily data is the ideal starting point for all other breakdowns.

Be prepared for a DataTransformException if you have any doubt about whether it will be possible to get the breakdown you want from the data you have.

Parameters:
targetBreakdown - a non-null object that specifies the breakdown that the returned data should have.
Returns:
a new DatedDataSet with the targetBreakdown.
Throws:
DataTransformException - if the method is unable to transform the data contained within this into data with the targetBreakdown.
java.lang.NullPointerException - if targetBreakdown is null.

equals

public boolean equals(java.lang.Object o)
Returns true if o is a DatedDataSet containing equal values covering equal dates, and with an equal percentageEstimated().

Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
Overridden to ensure consistency with equals.

Overrides:
hashCode in class java.lang.Object

toString

public java.lang.String toString()
Returns a non-null, non-empty string representation of this object for logging and debugging purposes.

The exact details of the representation are unspecified and subject to change.

Overrides:
toString in class java.lang.Object


www.degreedays.net/api/