net.degreedays.api.data.impl
Class LatestValuesPeriod

java.lang.Object
  extended by net.degreedays.api.data.Period
      extended by 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:

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
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
 int getMinimumNumberOfValues()
          Returns the number, greater than zero, that was specified using withMinimumNumberOfValues(int), or throws an IllegalStateException if no such number was specified (call 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 or equal to zero.
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.

A LatestValuesPeriod created through the constructor does not have an explicit 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 = 
     new LatestValuesPeriod(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 (call 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


www.degreedays.net/api/