Click or drag to resize

DataSpecs Class

Defines up to 100 sets of data that should be generated to fulfil a LocationDataRequest.
Inheritance Hierarchy
SystemObject
  DegreeDays.Api.DataDataSpecs

Namespace:  DegreeDays.Api.Data
Assembly:  DegreeDays (in DegreeDays.dll) Version: 1.3
Syntax
public sealed class DataSpecs : IEnumerable<DataSpec>, 
	IEnumerable

The DataSpecs type exposes the following members.

Constructors
Properties
  NameDescription
Public propertyCount
Gets the number of DataSpec objects held by this DataSpecs - always greater than zero.
Public propertyItemString
Gets the non-null DataSpec that has been assigned the specified string key.
Public propertyKeys
Gets the read-only collection of string keys that are assigned to the DataSpec objects stored within this DataSpecs.
Top
Methods
  NameDescription
Public methodEquals(Object)
Two DataSpecs objects are equal if they contain the same set of unique DataSpec objects - neither Keys nor the order of keys make any difference.
(Overrides ObjectEquals(Object).)
Public methodGetEnumerator
Returns an enumerator for iterating over each DataSpec contained within this DataSpecs.
Public methodGetHashCode
Overridden to ensure consistency with Equals.
(Overrides ObjectGetHashCode.)
Public methodGetKey(DataSpec)
Returns the non-null, non-empty string key associated with dataSpec.
Public methodToString
Returns a non-null, non-empty string representation of this instance for logging and debugging purposes.
(Overrides ObjectToString.)
Top
Remarks

When requesting multiple sets of data for a particular location, it makes sense to use multiple DataSpec objects to retrieve as much data as possible in a single request. This is cheaper and faster than fetching the same data across multiple requests. For example, for a particular location you might want to request heating and cooling degree days at 5 different base temperatures each. This would require 10 different DataSpec objects in total. By putting all 10 DataSpec objects in a single DataSpecs object, you could fetch all 10 sets of data in a single request.

For most use cases, all you will ever need to do with this class is use the constructors to create instances to pass into LocationDataRequest objects. However, if you are customizing this framework (e.g. using it to construct requests but handling the response XML using your own system entirely), you will probably find it useful to understand about keys and the uniqueness of DataSpec objects.

Keys

The XML request (which this .NET framework generates internally) requires that each DataSpec be assigned a unique string key attribute so that its corresponding data set can be found in the XML response (which this .NET framework parses internally). This DataSpecs class is central to the way that the keys are created and managed. It essentially gives you two options for key management:

  1. You can let this DataSpecs class generate and manage the keys entirely, such that you never have to see them or use them directly. This is the sensible option if you're sticking with the defaults and letting the .NET framework parse the XML response. With this option you do not need to deal with keys at all - you can fetch your data set objects out of the LocationDataResponse using the DataSpec objects that you created for the request (and kept on hand for this purpose).
  2. You can specify your own keys explicitly. The only reason we can think of for doing this is if, for whatever reason, you are parsing or transforming the XML response yourself and your parsing/transforming code expects the keys to have specific values or a specific format (e.g. matching keys in a database of yours). If this is the case, use the DataSpecsCustomKeyBuilder class to create a DataSpecs object with your own custom key-to-DataSpec mappings.

Uniqueness of DataSpec objects

There is no point in submitting a request containing multiple identical DataSpec objects, as it would lead to unnecessary duplication in the results and unnecessary bandwidth usage for the communication between the client and API servers.

Unless you are specifying your own keys (using DataSpecsCustomKeyBuilder), this class is set up to prevent duplicate DataSpec objects from being submitted as part of a request. It does this by filtering and discarding all duplicate DataSpec objects passed in to the constructors of this class. So, if you pass 10 DataSpec objects to one of the constructors, and only 5 of those are unique, then only the 5 unique DataSpec objects will be stored internally and sent as part of the XML request.

Because discarded duplicate DataSpec objects are identical to their retained counterparts, you can still use the duplicates to retrieve fetched data out of the LocationDataResponse. In other words, the internal process of filtering and discarding duplicate DataSpec objects should not affect the way in which you use this API.

If you create your own keys using DataSpecsCustomKeyBuilder, then duplicate DataSpec objects are not filtered. Filtering duplicate DataSpec objects would also involve filtering the keys associated with the duplicates, and this could cause problems for code of yours that was expecting those keys in the XML response. You can rely on the fact that, if you define your own DataSpec keys using CustomKeyBuilder, your XML response will contain entries for all of your keys, irrespective of whether some of the data associated with those keys is duplicated.

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