net.degreedays.api.data

Class LocationInfoResponse

java.lang.Object

net.degreedays.api.Response

net.degreedays.api.data.LocationInfoResponse

All Implemented Interfaces:

java.io.Serializable

public final class LocationInfoResponse
extends Response
implements java.io.Serializable

Contains the location/station-related info returned in response to a LocationInfoRequest.

This mirrors LocationDataResponse, except it doesn't actually contain any data (i.e. no DataSets).

See DataApi.getLocationInfo(LocationInfoRequest) for more info and code samples.

Since:

1.1

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	LocationInfoResponse.Builder A builder class for creating immutable LocationInfoResponse objects e.g. for testing purposes.

Method Summary

Modifier and Type	Method and Description
boolean	equals(java.lang.Object o) Returns true if o is a LocationInfoResponse with equal values for everything apart from the metadata() (which is not considered in the equality test).
Source[]	getSources() Returns the non-null, non-empty array of source(s) (essentially weather stations) that would be used to generate data for an equivalent LocationDataResponse.
int	hashCode() Overridden to ensure consistency with equals.
java.lang.String	stationId() Returns the non-null, non-empty canonical ID of the weather station or combination of weather stations that would be used to generate data for an equivalent LocationDataResponse.
LongLat	targetLongLat() Returns the non-null LongLat object that specifies the geographic position of the Location from the LocationInfoRequest that led to this response.
java.lang.String	toString() Returns a non-null, non-empty string representation of this object for logging and debugging purposes.

Methods inherited from class net.degreedays.api.Response

metadata

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

stationId

public java.lang.String stationId()

Returns the non-null, non-empty canonical ID of the weather station or combination of weather stations that would be used to generate data for an equivalent LocationDataResponse.

If the Location in the LocationInfoRequest was a StationIdLocation, this method will simply return the canonical form of that weather station's ID. We say "canonical" because it's possible for a station ID to be expressed in more than one way, like upper case or lower case. The canonical form of the station ID is the form that you should display in a UI or store in a database if appropriate.

If the Location in the LocationInfoRequest was a GeographicLocation, then:

• If the data for an equivalent LocationDataResponse would be calculated using a single station (the usual case), this method will return the canonical form of that station's ID.
• If the data for an equivalent LocationDataResponse would be calculated using multiple stations (something that the API might optionally start doing at some point in the future), this method will return the ID of a "virtual station" that represents the specific combination of weather stations used.

Either way, the station ID returned by this method can be used to fetch data for the same station(s) that would have been used to generate data in response to an equivalent LocationDataRequest. Typically you would use this to get the station ID to best represent a GeographicLocation, and then use that ID in LocationDataRequests going forward.

targetLongLat

public LongLat targetLongLat()

Returns the non-null LongLat object that specifies the geographic position of the Location from the LocationInfoRequest that led to this response.

If the Location from the request was a PostalCodeLocation, this will return the LongLat that the API determined to be the central point of that postal code.

If the Location from the request was a StationIdLocation, this will return the LongLat of that station (also accessible through getSources()).

If the Location from the request was a LongLatLocation, this will simply return the LongLat that was originally specified. (Bear in mind that the longitude and latitude may have been rounded slightly between the request and the response. Such rounding would only introduce very small differences that would be insignificant as far as the real-world position is concerned, but it's worth bearing this in mind in case you are comparing for equality the returned LongLat with the LongLat from the request. The two positions will be close, but they might not be equal.)

getSources

public Source[] getSources()

Returns the non-null, non-empty array of source(s) (essentially weather stations) that would be used to generate data for an equivalent LocationDataResponse.

At the time of writing there will only be one source for any given response (so getSources()[0] is the way to get it)... But at some point we might start combining data from multiple sources to satisfy requests for data from geographic locations. If we do add this feature, it will be optional, and disabled by default, so the behaviour of your system won't change unless you want it to.

The returned array can be modified freely without affecting the immutability of this LocationInfoResponse or the arrays returned by past, concurrent, or future calls to this method.

equals

public boolean equals(java.lang.Object o)

Returns true if o is a LocationInfoResponse with equal values for everything apart from the metadata() (which is not considered in the equality test).

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