net.degreedays.api.data.impl
Class DayRangePeriod

java.lang.Object
  extended by net.degreedays.api.data.Period
      extended by net.degreedays.api.data.impl.DayRangePeriod
All Implemented Interfaces:
java.io.Serializable

public final class DayRangePeriod
extends Period
implements java.io.Serializable

A type of Period that is defined explicitly in terms of the range of days that it covers.

Widening: interpretation of a DayRangePeriod in the context of a Breakdown

If the boundaries of a DayRangePeriod line up neatly with the date splitting of a Breakdown that contains it, then the calculated data will cover the specified range exactly (or a subset of that range if there isn't enough data to satisfy the request fully). This will always be the case if the period is contained within a DailyBreakdown.

If you put a DayRangePeriod inside a WeeklyBreakdown, MonthlyBreakdown, YearlyBreakdown, or FullYearsAverageBreakdown, then it is up to you whether you ensure that the boundaries of your period line up neatly with the weekly/monthly/yearly splitting of the breakdown. If your period specifies dates that do line up with the breakdown, then those dates will be treated as an exact specification. If your period specifies dates that don't line up with the breakdown, the API will effectively widen the range (at the beginning, or the end, or both boundaries if necessary) to ensure that the returned data covers all the dates that your range specifies (assuming enough data exists to do this).

The following examples should help to make this clearer:

Widening example 1

 DayRangePeriod period = 
         new DayRangePeriod(Day.of(2010, 10, 19).to(Day.of(2010, 11, 5)));
 DatedBreakdown breakdown = new MonthlyBreakdown(period);
 

In this example you can see that the dates of the period (2010-10-19 to 2010-11-05) do not match up with the calendar months that the MonthlyBreakdown specifies. In this instance the API would widen the range at both the beginning and the end, attempting to return one monthly value for October 2010 and one for November 2010.

If the first day of the specified period was the first day of a breakdown month (e.g. 2010-10-01), the range would not have been widened at the start. Similarly, if the last day of the specified period was the last day of a breakdown month (e.g. 2010-11-30), the range would not have been widened at the end. Widening only occurs when the dates don't line up with the splitting of the breakdown.

Widening example 2

 Day singleDay = Day.of(2009, 7, 21);
 DayRangePeriod period = new DayRangePeriod(singleDay.to(singleDay));
 DatedBreakdown breakdown = new YearlyBreakdown(period);
 

In this example the period is specified to cover just one day: 2009-07-21. Of course, that period, if interpreted explicitly, is not long enough to allow a yearly breakdown.

In this instance the API would widen the range at the beginning and the end, giving 2009-01-01 to 2009-12-31, so that it could return a yearly value for 2009 (the year containing the specified range).

Additional notes on widening

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


Constructor Summary
DayRangePeriod(DayRange dayRange)
          Constructs a DayRangePeriod object that specifies the period covered by dayRange.
 
Method Summary
 DayRange dayRange()
          Returns the non-null DayRange object that specifies the day(s) that this period covers.
 DayRange getMinimumDayRange()
          Returns the non-null minimum day range that was specified using withMinimumDayRange(net.degreedays.time.DayRange), or throws an IllegalStateException if no such range was specified (call hasMinimumDayRange() before calling this).
 boolean hasMinimumDayRange()
          Returns true if this DayRangePeriod specifies the day(s) that must be covered by any data returned in response to a request for data covering this DayRangePeriod.
 java.lang.String toString()
          Returns a non-null, non-empty string representation of this object for logging and debugging purposes.
 DayRangePeriod withMinimumDayRange(DayRange minimumDayRange)
          Returns a new DayRangePeriod with the same dayRange() as this, but also specifying minimumDayRange as the minimum range required.
 
Methods inherited from class net.degreedays.api.data.Period
dayRange, equals, hashCode, latestValues
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

DayRangePeriod

public DayRangePeriod(DayRange dayRange)
Constructs a DayRangePeriod object that specifies the period covered by dayRange.

Parameters:
dayRange - the range of days that the period should cover. Cannot be null.
Throws:
java.lang.NullPointerException - if dayRange is null.
Method Detail

withMinimumDayRange

public DayRangePeriod withMinimumDayRange(DayRange minimumDayRange)
Returns a new DayRangePeriod with the same dayRange() as this, but also specifying minimumDayRange as the minimum range required.

A DayRangePeriod created through the constructor does not have a minimum range. Without a minimum range, the API can decide what to do if there is not enough data available to satisfy the dayRange(), and it will typically return what it can from within dayRange(). If this method is used to specify a minimum range, then a request for data will fail unless that minimum range can be satisfied.

The following example shows typical usage of this method:

 DayRangePeriod period = 
     new DayRangePeriod(targetRange).withMinimumDayRange(minimumRange);
 

Warning: be careful with minimum ranges, particularly when defining the last day of a minimum range. The degree days for any given day will never become available until the day has finished in the location's local timezone, and it usually takes at least a few hours more for the required temperature data to filter through the system. For stations that don't record temperatures in the early morning (this explains the high "% estimated" figures of some minor airport stations), it can consistently take 10 or so hours for the previous day's data to become available, as our system needs a usable temperature reading from today before it will calculate the degree days from yesterday. Occasionally there can also be problems that can delay the appearance of fresh data further for certain stations, and delays of up to 10 or so days are possible, albeit rare. If your system specifies a minimum range that is too restrictive, it can easily end up with no data at all when in fact there's plenty of usable data available.

That said, there are times when a minimum range with highly-restrictive dates is exactly what you want (and you'd rather get nothing than slightly less data), so don't be afraid to specify restrictive minimum ranges if you need them.

Parameters:
minimumDayRange - the non-null minimum range that the returned DayRangePeriod object should hold.
Throws:
java.lang.NullPointerException - if minimumDayRange is null.
java.lang.IllegalArgumentException - if minimumDayRange extends earlier or later than dayRange().

dayRange

public DayRange dayRange()
Returns the non-null DayRange object that specifies the day(s) that this period covers.


hasMinimumDayRange

public boolean hasMinimumDayRange()
Returns true if this DayRangePeriod specifies the day(s) that must be covered by any data returned in response to a request for data covering this DayRangePeriod. If this returns true, it is safe to call getMinimumDayRange().

See Also:
withMinimumDayRange(net.degreedays.time.DayRange)

getMinimumDayRange

public DayRange getMinimumDayRange()
Returns the non-null minimum day range that was specified using withMinimumDayRange(net.degreedays.time.DayRange), or throws an IllegalStateException if no such range was specified (call hasMinimumDayRange() before calling this).

Throws:
java.lang.IllegalStateException - if this DayRangePeriod does not hold a minimum day range.

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/