net.degreedays.api.data

Class Location

java.lang.Object

net.degreedays.api.data.Location

Direct Known Subclasses:

GeographicLocation, StationIdLocation

public abstract class Location
extends java.lang.Object

Defines a location for which degree days should be calculated.

To create a Location object you can use the static factory methods of this class. For example:

 Location losAngelesAirportWeatherStation = Location.stationId("KLAX");
 
 Location empireStateBuilding = Location.postalCode("10118", "US");
 
 Location trafalgarSquare = Location.longLat(new LongLat(-0.12795, 51.50766));
 

empireStateBuilding and trafalgarSquare are examples of geographic locations, which provide a powerful way to get data for locations around the world. See GeographicLocation for more on how these geographic locations work.

This abstract class is not designed to be extended by third-party code, which is why it does not have an accessible constructor.

All concrete subclasses of this abstract class are immutable. You can safely reuse them and call them from multiple threads at once.

Method Summary

Modifier and Type	Method and Description
boolean	equals(java.lang.Object o) Two Location objects are equal if it can be ascertained that they both represent the exact same weather station(s) or geographic location, and that two requests for data, one with each Location and identical in every other respect, would return identical data.
int	hashCode() Overridden to ensure consistency with equals.
static LongLatLocation	longLat(LongLat longLat) Returns a non-null LongLatLocation object with the specified longitude and latitude position.
static PostalCodeLocation	postalCode(java.lang.String postalCode, java.lang.String twoLetterIsoCountryCodeInUpperCase) Returns a non-null PostalCodeLocation object with a postal code (or zip code, post code, or postcode) and a two-letter country code representing the country that the postal code belongs to.
static StationIdLocation	stationId(java.lang.String stationId) Returns a non-null StationIdLocation object with the specified weather station ID.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

stationId

public static StationIdLocation stationId(java.lang.String stationId)
                                   throws java.lang.IllegalArgumentException

Returns a non-null StationIdLocation object with the specified weather station ID.

Parameters:

stationId - the non-null, non-empty ID of the weather station that the StationIdLocation should represent (i.e. the station you want data for). Cannot contain contain any characters other than [-_0-9a-zA-Z], and cannot contain more than 60 characters (a limit that is significantly larger than the length of any station ID that we are currently aware of, but that is set high to allow for "virtual station IDs" to be introduced in the future, combining data from multiple stations).

Throws:

java.lang.NullPointerException - if stationId is null.

java.lang.IllegalArgumentException - if tests indicate that stationId fails to match the specification detailed above.

longLat

public static LongLatLocation longLat(LongLat longLat)

Returns a non-null LongLatLocation object with the specified longitude and latitude position.

Parameters:

longLat - the non-null longitude/latitude position.

Throws:

java.lang.NullPointerException - if longLat is null.

See Also:

GeographicLocation

postalCode

public static PostalCodeLocation postalCode(java.lang.String postalCode,
                                            java.lang.String twoLetterIsoCountryCodeInUpperCase)
                                     throws java.lang.IllegalArgumentException

Returns a non-null PostalCodeLocation object with a postal code (or zip code, post code, or postcode) and a two-letter country code representing the country that the postal code belongs to.

Parameters:

postalCode - the non-null, non-empty postal code (or zip code, post code, or postcode) of the location you want data for. Cannot be longer than 16 characters (a length that we believe allows for all current postal codes worldwide), and cannot contain any characters other than [- 0-9a-zA-Z].

twoLetterIsoCountryCodeInUpperCase - the ISO 3166-1-alpha-2 country code of the country that postalCode belongs to. It must be a two-character string comprised of only characters A-Z (i.e. upper case only). For example, pass "US" if postalCode is a US zip code, pass "GB" (for "Great Britain") if postalCode is a UK post code, and pass "CA" if postalCode is a Canadian zip code.

Throws:

java.lang.NullPointerException - if postalCode or twoLetterIsoCountryCodeInUpperCase is null.

java.lang.IllegalArgumentException - if tests indicate that postalCode or twoLetterIsoCountryCodeInUpperCase fails to match the specifications detailed above.

See Also:

GeographicLocation

equals

public final boolean equals(java.lang.Object o)

Two Location objects are equal if it can be ascertained that they both represent the exact same weather station(s) or geographic location, and that two requests for data, one with each Location and identical in every other respect, would return identical data.

If this method returns false, it does not necessarily mean that the two Location objects do not represent the same weather station(s) or geographic location. For example, it is impossible to determine if a LongLatLocation maps to the same weather station(s) as a PostalCodeLocation without putting in two requests for data, one with each Location and identical in every other respect, and comparing for equality the station IDs that come back with each response.

Overrides:

equals in class java.lang.Object

Returns:

true if it is clear that o is a Location that represents the exact same weather station(s) or geographic location as this Location object, or false if it is clear that it isn't or if it's impossible to tell without putting in two requests for data, one with each Location and identical in every other respect, and comparing for equality the station IDs that come back with each response.

hashCode

public final int hashCode()

Overridden to ensure consistency with equals.

Overrides:

hashCode in class java.lang.Object