net.degreedays.api.data.impl

Class LatestValuesPeriod

java.lang.Object

net.degreedays.api.data.Period

net.degreedays.api.data.impl.LatestValuesPeriod

All Implemented Interfaces:

java.io.Serializable

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

A type of Period that automatically resolves to a date range including the latest available data and the specified number of degree-day values. The meaning of the specified number of values depends on the type of the Breakdown that holds this period. For example, if you create a LatestValuesPeriod specifying x values then:

• Used as the Period in a DailyBreakdown it would specify the x most recent days of data.
• Used as the Period in a WeeklyBreakdown it would specify the x most recent weeks of data.
• Used as the Period in a MonthlyBreakdown it would specify the x most recent months of data.
• Used as the Period in a YearlyBreakdown it would specify the x most recent years of data.
• Used as the Period in a FullYearsAverageBreakdown it would specify the x most recent full calendar years of data.

If you want data covering specific dates, you may be better off using a DayRangePeriod. But this class can be a useful convenience if you want the latest available data containing a specific number of daily, weekly, monthly, or yearly values. It can save you from some date arithmetic, and you won't need to consider the time-zones or update delays of the weather stations that you're getting data from to figure out the exact dates of the latest data that is likely to be available.

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

Constructor Summary

Constructors

Constructor and Description
LatestValuesPeriod(int numberOfValues) Constructs a LatestValuesPeriod object that automatically resolves to a date range including the latest available data and the specified number of degree-day values.

Method Summary

Modifier and Type	Method and Description
int	getMinimumNumberOfValues() Returns the number, greater than zero, that was specified using withMinimumNumberOfValues(int), or throws an IllegalStateException if no such number was specified (check hasMinimumNumberOfValues() before calling this).
boolean	hasMinimumNumberOfValues() Returns true if this LatestValuesPeriod specifies the number of values that must be included in the response to a request for data covering this LatestValuesPeriod.
int	numberOfValues() Returns a number, greater than zero, indicating how many degree-day values this period should cover (see this explanation of how the values in question can be daily, weekly, monthly, or yearly).
java.lang.String	toString() Returns a non-null, non-empty string representation of this object for logging and debugging purposes.
LatestValuesPeriod	withMinimumNumberOfValues(int minimumNumberOfValues) Returns a new LatestValuesPeriod with the same numberOfValues() as this, but also specifying minimumNumberOfValues as the minimum number of values 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

LatestValuesPeriod

public LatestValuesPeriod(int numberOfValues)

Constructs a LatestValuesPeriod object that automatically resolves to a date range including the latest available data and the specified number of degree-day values.

Parameters:

numberOfValues - a number, greater than zero, that specifies how many degree-day values the period should cover (see this explanation of how the values in question can be daily, weekly, monthly, or yearly). This is effectively an upper bound: if there isn't enough good data to cover the numberOfValues specified, the API will assemble and return what it can.

Throws:

java.lang.IllegalArgumentException - if numberOfValues is less than 1.

Method Detail

withMinimumNumberOfValues

public LatestValuesPeriod withMinimumNumberOfValues(int minimumNumberOfValues)

Returns a new LatestValuesPeriod with the same numberOfValues() as this, but also specifying minimumNumberOfValues as the minimum number of values required.

By default a LatestValuesPeriod does not have a minimum number of values. Without a minimum, the API can decide what to do if there is not enough data available to satisfy the numberOfValues() requested, and it will typically return as many values as it can. If this method is used to specify a minimum number of values, then a request for data will fail unless that minimum number of values can be satisfied.

The following example shows typical usage of this method:

 LatestValuesPeriod period = 
     Period.latestValues(targetNo).withMinimumNumberOfValues(minimumNo);
 

Parameters:

minimumNumberOfValues - the minimum number of values that the returned LatestValuesPeriod object should hold. Must be between 1 and numberOfValues() (both inclusive).

Throws:

java.lang.IllegalArgumentException - if minimumNumberOfValues is less than 1 or greater than numberOfValues().

numberOfValues

public int numberOfValues()

Returns a number, greater than zero, indicating how many degree-day values this period should cover (see this explanation of how the values in question can be daily, weekly, monthly, or yearly).

hasMinimumNumberOfValues

public boolean hasMinimumNumberOfValues()

Returns true if this LatestValuesPeriod specifies the number of values that must be included in the response to a request for data covering this LatestValuesPeriod. If this returns true, it is safe to call getMinimumNumberOfValues().

See Also:

withMinimumNumberOfValues(int)

getMinimumNumberOfValues

public int getMinimumNumberOfValues()

Returns the number, greater than zero, that was specified using withMinimumNumberOfValues(int), or throws an IllegalStateException if no such number was specified (check hasMinimumNumberOfValues() before calling this).

Throws:

java.lang.IllegalStateException - if this LatestValuesPeriod does not hold a minimum number of values.

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