net.degreedays.api.data
Class DataSets

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

public final class DataSets
extends java.lang.Object
implements java.io.Serializable

Contains all sets of degree-day data generated to fulfil the DataSpecs for a specific Location.

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


Nested Class Summary
static class DataSets.Builder
          A builder class for creating immutable DataSets objects e.g. for testing purposes.
 
Method Summary
 boolean equals(java.lang.Object o)
           A DataSets object is equal to another DataSets object with an equal DataSet for each DataSpec that it was created with.
 DataSet get(DataSpec dataSpec)
          Returns the DataSet that was generated to fulfil the specified DataSpec from the request, or throws a SourceDataException if no such DataSet could be generated.
 AverageDataSet getAverage(AverageDataSpec dataSpec)
          Convenience alternative to calling get(dataSpec) with an AverageDataSpec and then casting the result.
 DatedDataSet getDated(DatedDataSpec dataSpec)
          Convenience alternative to calling get(dataSpec) with a DatedDataSpec and then casting the result.
 DataSet getWithKey(java.lang.String key)
           For unusual use cases, this enables you to access the DataSet objects using the string keys that are usually managed internally.
 int hashCode()
          Overridden to ensure consistency with equals.
 java.lang.String toString()
          Returns a non-null, non-empty string representation of this object for logging and debugging purposes.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

get

public DataSet get(DataSpec dataSpec)
            throws SourceDataException
Returns the DataSet that was generated to fulfil the specified DataSpec from the request, or throws a SourceDataException if no such DataSet could be generated.

Parameters:
dataSpec - a DataSpec from the request.
Returns:
the non-null DataSet that was generated to fulfil dataSpec.
Throws:
SourceDataException - if the API's processing of dataSpec failed.
java.lang.NullPointerException - if dataSpec is null.
java.lang.IllegalArgumentException - if dataSpec is not a DataSpec from the original request.
java.lang.IllegalStateException - if this DataSets object was not created with access to the DataSpecs object from the request (this won't be an issue if you are using this framework end to end).
See Also:
getDated(DatedDataSpec), getAverage(AverageDataSpec)

getDated

public DatedDataSet getDated(DatedDataSpec dataSpec)
                      throws SourceDataException
Convenience alternative to calling get(dataSpec) with a DatedDataSpec and then casting the result.

Parameters:
dataSpec - a DatedDataSpec from the request.
Returns:
the non-null DatedDataSet that was generated to fulfil dataSpec.
Throws:
SourceDataException - if the API's processing of dataSpec failed.
java.lang.NullPointerException - if dataSpec is null.
java.lang.IllegalArgumentException - if dataSpec is not a DataSpec from the original request.
java.lang.IllegalStateException - if this DataSets object was not created with access to the DataSpecs object from the request (this won't be an issue if you are using this framework end to end).
See Also:
getAverage(AverageDataSpec), get(DataSpec)

getAverage

public AverageDataSet getAverage(AverageDataSpec dataSpec)
                          throws SourceDataException
Convenience alternative to calling get(dataSpec) with an AverageDataSpec and then casting the result.

Parameters:
dataSpec - an AverageDataSpec from the request.
Returns:
the non-null AverageDataSet that was generated to fulfil dataSpec.
Throws:
SourceDataException - if the API's processing of dataSpec failed.
java.lang.NullPointerException - if dataSpec is null.
java.lang.IllegalArgumentException - if dataSpec is not a DataSpec from the original request.
java.lang.IllegalStateException - if this DataSets object was not created with access to the DataSpecs object from the request (this won't be an issue if you are using this framework end to end).
See Also:
getDated(DatedDataSpec), get(DataSpec)

getWithKey

public DataSet getWithKey(java.lang.String key)
                   throws SourceDataException

For unusual use cases, this enables you to access the DataSet objects using the string keys that are usually managed internally.

Usually you'll want the methods that take a DataSpec (or subclass) instead of this one, but you might need this method if you are:

  1. generating your XML requests outside of this framework; or
  2. creating the string keys used by DataSpecs yourself; or
  3. testing an XML ResponseParser that you have written.

Parameters:
key - a non-null, non-empty string key that you expect to be present in the response, associated with the set of data that you want to access.
Returns:
the non-null DataSet associated with key (matching a data specification with key key from the original request).
Throws:
SourceDataException - if there was a failure in the API's processing of the data specification associated with key.
java.lang.NullPointerException - if key is null.
java.lang.IllegalArgumentException - if key isn't recognized as a key from this response.
See Also:
getDated(DatedDataSpec), getAverage(AverageDataSpec), get(DataSpec)

equals

public boolean equals(java.lang.Object o)

A DataSets object is equal to another DataSets object with an equal DataSet for each DataSpec that it was created with.

If this DataSets object was created without a DataSpecs object, then it can only be equal to another DataSets object that was created without a DataSpecs object, and that has equal keys and an equal DataSet object for each of those keys.

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/